> ## Documentation Index > Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 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](/pt/on-premises/configuration/overleaf-toolkit/templates#transferring-templates-from-overleaf.com "mention"). 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`: ```dotenv title="config/overleaf.rc" theme={null} 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`). ```yml theme={null} 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. 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. ```dotenv title="config/variables.env" wrap theme={null} 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 ``` 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. ```dotenv title="config/variables.env" wrap theme={null} 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](/pt/on-premises/configuration/overleaf-toolkit/sandboxed-compiles#known-issues "mention") ### 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: ```dotenv title="config/variables.env" wrap theme={null} 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: ```mjs title="sandboxed-compiles/index.mjs" wrap expandable theme={null} 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](/pt/on-premises/maintenance/updating-tex-live-full-images-automatically "mention"). ### 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`: > > ```dotenv theme={null} > 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: > > ```dotenv theme={null} > TEX_LIVE_DOCKER_IMAGE=danteev/texlive:2025-10-15 > ALL_TEX_LIVE_DOCKER_IMAGES=danteev/texlive:2025-10-15 > ``` > > Nos logs, vejo o seguinte: > > ```text wrap theme={null} > {"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` ```text theme={null} 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. ```text theme={null} 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: ```bash wrap theme={null} 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](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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.