Saltar para o conteúdo principal
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 Ayakaleaf 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
Para desativá-las, defina SIBLING_CONTAINERS_ENABLED=false e execute bin/up. As compilações passam então a ser executadas dentro do contêiner sharelatex com o TeX Live básico dele.

Para usuários do Docker Compose

Configurar a imagem do TeX Live

Para usuários da China continental, é possível baixar as imagens do espelho ghcr.nju.edu.cn para acelerar o download e depois marcá-las com o nome ghcr.io:
NÃO use ghcr.nju.edu.cn nas configurações de ambiente do Toolkit: mantenha ali os nomes ghcr.io. Para impedir que o bin/up baixe as imagens do ghcr.io novamente, defina SIBLING_CONTAINERS_PULL=false em config/overleaf.rc. Para manter as imagens atualizadas por meio do espelho, consulte Atualizar as imagens TeX Live Full automaticamente.
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 (opcional), A imagem do TeX Live usada por novos projetos. Ela deve ser uma das imagens em ALL_TEX_LIVE_DOCKER_IMAGES. Se não for definida, os novos projetos usam a primeira imagem de ALL_TEX_LIVE_DOCKER_IMAGES.
  • ALL_TEX_LIVE_DOCKER_IMAGE_NAMES (opcional), Uma lista separada por vírgulas de nomes para as imagens, na mesma ordem, exibidos nas configurações do compilador. Se não for definida, ou se for menor que a lista de imagens, a imagem é exibida pela sua tag, por exemplo 2026.1.
  • 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.
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
É 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
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

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:
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:
Nos logs, vejo o seguinte:
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
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.
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:
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.

Q&A

Resposta: Os contêineres e os arquivos de compilação são, após um intervalo; as imagens do TeX Live não.
  • Contêineres de compilação (project-<project id>-<hash>) são reutilizados entre compilações do mesmo projeto, por isso permanecem após uma compilação. Uma verificação é executada a cada hora e remove os que têm mais de uma hora e cujo projeto não foi compilado na última hora. Um contêiner normalmente desaparece de uma a duas horas após a última compilação. Reiniciar o Overleaf não os remove; a próxima verificação horária, sim.
  • Contêineres de contagem de palavras, SyncTeX e conversão são removidos assim que terminam.
  • Arquivos de compilação (data/overleaf/data/compiles e output) são removidos quando um projeto não é usado há um dia, com verificação a cada 10 minutos. Quando o espaço em disco fica baixo, esse período é reduzido gradualmente, até meio dia.
  • Imagens do TeX Live nunca são removidas, pois toda compilação precisa delas. Para liberar espaço depois de remover uma imagem de ALL_TEX_LIVE_DOCKER_IMAGES, exclua-a com docker image rm <image>.
Não é necessário excluir esses contêineres manualmente.
Resposta: Não. Cada contêiner de compilação monta apenas o diretório de compilação do próprio projeto, em /compile, e não tem rede, e não há nenhuma configuração para montar outros diretórios do host nele. Em vez disso, envie para o projeto os arquivos de que ele precisa.
Resposta: Sim. ghcr.io/ayaka-notes/texlive-basic:<year>.1 (2020.1 a 2026.1) tem o esquema básico do TeX Live mais alguns pacotes, como latexmk, xetex e fontspec, sem o conjunto completo de fontes. Ela é muito menor que a texlive-full, mas projetos que usam outros pacotes recebem erros de pacote ausente. Para o TeX Live 2025 básico:
config/variables.env
ghcr.io/ayaka-notes/texlive-full:base não é uma imagem básica: ela não contém o TeX Live e não consegue compilar.
Resposta: O editor não mostra essa informação, e o log do clsi só a registra no nível de depuração. Ainda assim, toda requisição de compilação a retorna: abra as ferramentas de desenvolvedor do navegador, vá até a aba Network, recompile e selecione a requisição compile. Sua resposta JSON contém timings em milissegundos, onde compileE2E é a compilação inteira no serviço de compilação e compile é a própria execução do LaTeX.
Última modificação em 13 de novembro de 2026