Sandboxed Compiles

O Ayakaleaf Pro oferece a opção de executar compilações em um ambiente sandbox seguro, para segurança de nível empresarial. Isso é feito executando cada projeto em seu próprio ambiente Docker seguro.

​

Segurança aprimorada

Os Sandboxed Compiles são a abordagem recomendada para o Ayakaleaf Pro, pois muitos documentos LaTeX exigem ou têm a capacidade de executar comandos de shell arbitrários como parte do processo de compilação do PDF. Se você usar Sandboxed Compiles, cada compilação será executada em um contêiner Docker separado, com capacidades limitadas que não são compartilhadas com nenhum outro usuário ou projeto, e sem acesso a recursos externos, como a rede do host.

Se você tentar executar o Ayakaleaf Pro sem Sandboxed Compiles, a compilação será executada junto com outras compilações simultâneas dentro do contêiner Docker principal, e os usuários terão acesso total de leitura e escrita aos recursos do contêiner sharelatex (sistema de arquivos, rede e variáveis de ambiente) ao executar compilações LaTeX.

​

Gerenciamento de pacotes mais fácil

Para evitar a instalação manual de pacotes, recomendamos ativar os Sandboxed Compiles. Essa é uma configuração ajustável no Server Pro que fornecerá aos seus usuários acesso ao mesmo ambiente TeX Live do overleaf.com, mas dentro da sua própria instalação on-premises. As imagens do TeX Live usadas pelos Sandboxed Compiles contêm os pacotes e as fontes mais populares, testados com os templates da nossa galeria, garantindo a máxima compatibilidade com projetos on-premises.

Ativar os Sandboxed Compiles permite configurar quais versões do TeX Live os usuários podem escolher dentro de seus projetos, além de definir uma versão padrão da imagem do TeX Live para novos projetos.

Se você tentar executar o Ayakaleaf Pro sem Sandboxed Compiles, sua instância usará por padrão uma versão com esquema básico do TeX Live para as compilações. Essa versão básica é leve e contém apenas um subconjunto muito limitado de pacotes LaTeX, o que muito provavelmente resultará em erros de pacotes ausentes para seus usuários, especialmente se tentarem usar templates prontos.

Como o Ayakaleaf Pro foi projetado para funcionar offline, não há uma forma automatizada de integrar os templates da galeria do overleaf.com à sua instalação on-premises; no entanto, é possível fazer isso manualmente, template por template. Para mais informações sobre como isso funciona, consulte nosso guia de transferência de templates do overleaf.com: #transferring-templates-from-overleaf.com.

Os Sandboxed Compiles exigem que o contêiner sharelatex tenha acesso ao socket do Docker na máquina host (por meio de um bind mount), para que possa gerenciar esses contêineres de compilação irmãos.

​

Como funciona

Quando os Sandboxed Compiles estão ativados, o socket do Docker é montado da máquina host no contêiner sharelatex, para que o serviço de compilação no contêiner possa criar novos contêineres Docker no host. Em seguida, para cada execução do compilador em cada projeto, o serviço de compilação LaTeX (CLSI) fará o seguinte:

• Gravar os arquivos do projeto em um local dentro do OVERLEAF_DATA_PATH.
• Usar o socket do Docker montado para criar um novo contêiner texlive para a execução da compilação.
• Fazer com que o contêiner texlive leia os dados do projeto a partir do local em OVERLEAF_DATA_PATH.
• Compilar o projeto dentro do contêiner texlive.

​

Ativando os Sandboxed Compiles

​

Para usuários do Toolkit

Para ativar os Sandboxed Compiles (também conhecidos como Sibling containers), defina as seguintes opções de configuração em overleaf-toolkit/config/overleaf.rc:

config/overleaf.rc

SERVER_PRO=true
SIBLING_CONTAINERS_ENABLED=true

​

Para usuários do Docker Compose

A partir do Overleaf CE/Server Pro 5.0.3, as variáveis de ambiente foram renomeadas de SHARELATEX_* para OVERLEAF_*.

Se você estiver usando uma versão 4.x (ou anterior), certifique-se de que as variáveis tenham o prefixo correspondente (por exemplo, SHARELATEX_MONGO_URL em vez de OVERLEAF_MONGO_URL).

version: '2'
services:
    sharelatex:
        #...
        volumes:
            - /data/overleaf_data:/var/lib/overleaf
            - /var/run/docker.sock:/var/run/docker.sock
        environment:
            #...
            DOCKER_RUNNER: "true"
            SANDBOXED_COMPILES: "true"
            SANDBOXED_COMPILES_HOST_DIR: "/data/overleaf_data/data/compiles"
            #...
        #...

​

Configurar a imagem do TeX Live

Para usuários da China continental, é possível substituir ghcr.io por ghcr.nju.edu.cn para acelerar o download. Mas NÃO use ghcr.nju.edu.cn diretamente nas configurações de ambiente do Toolkit. Você deve manter ghcr.io como sua única opção.

O Ayakaleaf Pro usa três variáveis de ambiente para determinar quais imagens do TeX Live usar nos Sandboxed Compiles:

• TEX_LIVE_DOCKER_IMAGE (obrigatória), A imagem padrão do TeX Live usada para compilar novos projetos. Essa imagem deve estar incluída em ALL_TEX_LIVE_DOCKER_IMAGES.
• ALL_TEX_LIVE_DOCKER_IMAGE_NAMES (obrigatória), Uma lista separada por vírgulas de nomes amigáveis para as imagens, usados nas opções do frontend.
• ALL_TEX_LIVE_DOCKER_IMAGES (obrigatória), Uma lista separada por vírgulas das imagens do TeX Live a serem usadas. Se o Overleaf Toolkit for usado na implantação, essas imagens serão baixadas ou atualizadas. Para pular o download, defina SIBLING_CONTAINERS_PULL=false em config/overleaf.rc.

Ao iniciar sua instância do Ayakaleaf Pro usando o comando bin/up, o Toolkit baixará automaticamente todas as imagens listadas em ALL_TEX_LIVE_DOCKER_IMAGES.

Aqui está um exemplo em que usamos o TeX Live 2026 como padrão para novos projetos e mantemos o 2025 em uso para projetos antigos.

Instalação mínima

A configuração a seguir instala todas as imagens Docker completas do TeX Live de 2025 a 2026. Recomendamos ter pelo menos 64 GB de armazenamento disponível antes de usar esta configuração.

config/variables.env

ALL_TEX_LIVE_DOCKER_IMAGES=ghcr.io/ayaka-notes/texlive-full:2026.1, ghcr.io/ayaka-notes/texlive-full:2025.1
ALL_TEX_LIVE_DOCKER_IMAGE_NAMES=Texlive 2026, Texlive 2025
TEX_LIVE_DOCKER_IMAGE=ghcr.io/ayaka-notes/texlive-full:2026.1

Instalação completa

A configuração a seguir instala todas as imagens Docker completas do TeX Live de 2020 a 2026. Recomendamos ter pelo menos 150 GB de armazenamento disponível antes de usar esta configuração.

config/variables.env

ALL_TEX_LIVE_DOCKER_IMAGES=ghcr.io/ayaka-notes/texlive-full:2026.1,ghcr.io/ayaka-notes/texlive-full:2025.1,ghcr.io/ayaka-notes/texlive-full:2024.1,ghcr.io/ayaka-notes/texlive-full:2023.1,ghcr.io/ayaka-notes/texlive-full:2022.1,ghcr.io/ayaka-notes/texlive-full:2021.1,ghcr.io/ayaka-notes/texlive-full:2020.1
ALL_TEX_LIVE_DOCKER_IMAGE_NAMES=Texlive 2026,Texlive 2025,Texlive 2024,Texlive 2023,Texlive 2022,Texlive 2021,Texlive 2020
TEX_LIVE_DOCKER_IMAGE=ghcr.io/ayaka-notes/texlive-full:2026.1

É altamente recomendável configurar pelo menos 2 imagens texlive-full. Para saber o motivo em detalhes, consulte #known-issues

​

Imagens do TeX Live disponíveis

Estas são uma série de imagens do TeX Live especialmente otimizadas para o Overleaf, que também podem ser adicionadas a TEX_LIVE_DOCKER_IMAGE e ALL_TEX_LIVE_DOCKER_IMAGES:

• ghcr.io/ayaka-notes/texlive-full:2026.1 (também com a tag latest)
• ghcr.io/ayaka-notes/texlive-full:2025.1
• ghcr.io/ayaka-notes/texlive-full:2024.1
• ghcr.io/ayaka-notes/texlive-full:2023.1
• ghcr.io/ayaka-notes/texlive-full:2022.1
• ghcr.io/ayaka-notes/texlive-full:2021.1
• ghcr.io/ayaka-notes/texlive-full:2020.1

Existe um esquema rígido sobre como as imagens devem ser marcadas com tags (aplica-se a regex ^[0-9]+.[0-9]+, em que o primeiro número determina o ano do TeX Live e o segundo, a versão do patch).

​

Posso usar outro registro de imagens?

Algumas pessoas podem se perguntar se é possível substituir ghcr.io por outro site espelho, ou trocar o texlive por outra imagem do Docker Hub.

Não recomendamos, pois a configuração é relativamente complicada. Se você estiver baixando de um site espelho, pode renomear sua imagem para ghcr.io/ayaka-notes/texlive-full.

Mas, se você realmente quiser usar seu próprio registro de imagens, adicione:

config/variables.env

IMAGE_ROOT=hub.your.com/your-repo

Em seguida, você precisa garantir que todas as imagens do texlive estejam em your-repo, como

• hub.your.com/your-repo/texlive-full:2025.1
• hub.your.com/your-repo/texlive-full:2024.1

Para informações detalhadas, leia o código-fonte abaixo para entender como interpretamos suas variáveis de ambiente:

sandboxed-compiles/index.mjs

if (process.env.SANDBOXED_COMPILES === 'true') {
  // Set default image root if not provided
  let imageRootPath = process.env.IMAGE_ROOT || "ghcr.io/ayaka-notes";
  // Export imageRoot to Settings
  Settings.imageRoot = imageRootPath

  // allowedImageNames should be:
  // [
  //  { imageName: "texlive-2023:latest", imageDesc: "TeX Live 2023" },
  //  { imageName: "texlive-2022:latest", imageDesc: "TeX Live 2022" },
  // ]
  Settings.allowedImageNames = parseTextExtensions(process.env.ALL_TEX_LIVE_DOCKER_IMAGES)
    .map((texImage, index) => ({
      imageName: texImage.split("/")[texImage.split("/").length - 1],
      imageDesc: parseTextExtensions(process.env.ALL_TEX_LIVE_DOCKER_IMAGE_NAMES)[index]
        || texImage.split(':')[1],
    }))
  
  // In the end, imageName will be put together with imageRoot to form the full image path
  // The full name will be like: ghcr.io/ayaka-notes/texlive-2023:latest

  // Set default image name if not provided
  if(!process.env.TEX_LIVE_DOCKER_IMAGE) {
    process.env.TEX_LIVE_DOCKER_IMAGE = imageRootPath + "/" + Settings.allowedImageNames[0].imageName
  }

  // Export currentImageName to Settings
  // This is the new created projects' image name
  Settings.currentImageName = process.env.TEX_LIVE_DOCKER_IMAGE
}

​

Sincronização automatizada das imagens do TeX Live

Para evitar ter que atualizar manualmente sua instância com bin/up toda vez, você pode automatizar as atualizações da sua imagem do TeX Live. Consulte updating-tex-live-full-images-automatically.md.

​

Problemas conhecidos

Este é um caso real da comunidade do Overleaf:

Usando a 6.0.1-ext-v3.3, tenho estas configurações em variables.env:

TEX_LIVE_DOCKER_IMAGE=texlive/texlive:latest-full
ALL_TEX_LIVE_DOCKER_IMAGES=texlive/texlive:latest-full

Isso funciona bem com texlive/texlive:latest-full. No entanto, baixei outra imagem do texlive, danteev/texlive:2025-10-15, e alterei ambas as variáveis para o novo nome da imagem, mas não funciona:

TEX_LIVE_DOCKER_IMAGE=danteev/texlive:2025-10-15
ALL_TEX_LIVE_DOCKER_IMAGES=danteev/texlive:2025-10-15

Nos logs, vejo o seguinte:

{"name":"clsi","level":50,"err":{"message":"(HTTP code 404) no such container - No such image: texlive/texlive:latest-full ","name":"Error","stack":"Error: (HTTP code 404) no such container - No such image: texlive/texlive:latest-full ... 

Parece que as configurações atualizadas em variables.env não estão surtindo efeito. A compilação ainda tenta executar a imagem texlive/texlive:latest-full, e não a nova imagem.

Tentei reiniciar, excluir os contêineres e executar novamente, mas o problema continua o mesmo.

Alguma solução?

Devido a algumas limitações técnicas, se você configurar apenas uma única imagem Docker do TeXLive, como texlive-fullA:latest

ALL_TEX_LIVE_DOCKER_IMAGES=texlive/texliveA:latest-full
ALL_TEX_LIVE_DOCKER_IMAGE_NAMES=TeXLiveA
TEX_LIVE_DOCKER_IMAGE=texlive/texliveA:latest-full

E, depois de executar sua instância do Overleaf por um tempo, você pode querer alterar a imagem do TeXLive para texlive-fullB:latest. Então, verá que seus usuários não conseguem compilar nenhum projeto.

ALL_TEX_LIVE_DOCKER_IMAGES=texlive/texliveA:latest-full
ALL_TEX_LIVE_DOCKER_IMAGE_NAMES=TeXLiveA
TEX_LIVE_DOCKER_IMAGE=texlive/texliveA:latest-full

Isso acontece porque o nome da imagem TeXLive-Full (para a compilação em sandbox) de cada projeto é persistido no banco de dados. Somente quando o usuário troca a versão do TeXLive do seu projeto, por exemplo, de 2024 para 2025, o nome da imagem é alterado no banco de dados.

Quando o CLSI compila um projeto, ele usa o nome da imagem do contêiner encontrado no banco de dados para compilar o projeto diretamente.

Se você fornecer apenas uma imagem Docker, os usuários não poderão alterar a imagem usada para compilar o projeto. Nesse caso, você precisará escrever um script para modificar manualmente a imagem do TeXLive de todos os projetos dos usuários no mongoDB.

​

Depuração e relato de problemas

Execute o seguinte comando para verificar o log do clsi a partir do Toolkit:

bin/logs clsi

Se você encontrar algum problema ao compilar com as imagens do TeX Live, envie uma issue aqui:

https://github.com/ayaka-notes/texlive-full/issues/new?template=texlive-image-bug.yml

Para nos ajudar a reproduzir e solucionar o problema, poderemos pedir que você envie seu projeto para o Overleaf. Em seguida, baixaremos o projeto e executaremos testes de compilação com o GitHub Action.