> For the complete documentation index, see [llms.txt](https://ayakaleaf-pro.ayaka.space/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ayakaleaf-pro.ayaka.space/on-premises/pt/configuracao/overleaf-toolkit/sandboxed-compiles.md). # Compilações em sandbox O Overleaf Pro inclui a opção de executar compilações num ambiente sandbox seguro para segurança empresarial. Faz isso executando cada projeto no seu próprio ambiente Docker seguro. ### Segurança melhorada As Compilações em Sandbox são a abordagem recomendada para o Server Pro devido ao facto de muitos documentos LaTeX necessitarem de/terem a capacidade de executar comandos arbitrários da shell como parte do processo de compilação do PDF. Se utilizar Compilações em Sandbox, cada compilação é executada num contentor Docker separado com capacidades limitadas que não são partilhadas com nenhum outro utilizador ou projeto e não tem acesso a recursos externos, como a rede do anfitrião. {% hint style="warning" %} Se tentar executar o Overleaf Pro **sem** Compilações em Sandbox, a compilação é executada em paralelo com outras compilações concorrentes dentro do contentor Docker principal e os utilizadores têm acesso total de leitura e escrita aos recursos do `sharelatex` (sistema de ficheiros, rede e variáveis de ambiente) quando executam compilações LaTeX. {% endhint %} ### Gestão de pacotes mais fácil Para evitar instalar pacotes manualmente, recomendamos ativar as Compilações em Sandbox. Esta é uma definição configurável no Server Pro que fornecerá aos seus utilizadores acesso ao mesmo ambiente TeX Live que o de overleaf.com, mas dentro da sua própria instalação local. As imagens TeX Live usadas pelas Compilações em Sandbox contêm os pacotes e tipos de letra mais populares testados com os nossos modelos da galeria, garantindo a máxima compatibilidade com projetos locais. Ativar as Compilações em Sandbox permite-lhe configurar quais as versões do TeX Live que os utilizadores podem escolher no respetivo projeto, bem como definir uma versão da imagem TeX Live predefinida para novos projetos. {% hint style="info" %} Se tentar executar o Overleaf Pro sem Compilações em Sandbox, a sua instância passará por predefinição a utilizar uma versão de esquema básico do TeX Live para compilações. Esta 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 em falta para os seus utilizadores, especialmente se tentarem usar modelos pré-construídos. {% endhint %} Como o Overleaf Pro foi concebido para funcionar offline, não existe uma forma automatizada de integrar os modelos da galeria do overleaf.com na sua instalação local; contudo, é possível fazê-lo manualmente, modelo a modelo. Para mais informações sobre como isto funciona, consulte o nosso guia de transferência de modelos do overleaf.com: [/pages/2ed0f7aa1221fc81a456160ce850c3c542495118#transferring-templates-from-overleaf.com](https://ayakaleaf-pro.ayaka.space/on-premises/pt/configuracao/overleaf-toolkit/pages/2ed0f7aa1221fc81a456160ce850c3c542495118#transferring-templates-from-overleaf.com "mention"). {% hint style="info" %} As Compilações em Sandbox requerem que o `sharelatex` contentor tenha acesso ao socket Docker na máquina anfitriã (através de uma montagem bind) para que possa gerir estes contentores de compilação irmãos. {% endhint %} ## Como funciona Quando as Compilações em Sandbox estão ativadas, o socket Docker será montado da máquina anfitriã no `sharelatex` contentor, para que o serviço de compilação no contentor possa criar novos contentores Docker no anfitrião. Depois, para cada execução do compilador em cada projeto, o serviço de compilação LaTeX (CLSI) fará o seguinte: * Escreva os ficheiros do projeto para uma localização dentro do `OVERLEAF_DATA_PATH`. * Use o socket Docker montado para criar um novo `texlive` contentor para a execução da compilação. * Faça com que o `texlive` contentor leia os dados do projeto a partir da localização em `OVERLEAF_DATA_PATH`. * Compile o projeto dentro do `texlive` contentor. ### Ativar as Compilações em Sandbox #### Para utilizador do Toolkit Para ativar as compilações em sandbox (também conhecidas como contentores irmãos), defina as seguintes opções de configuração em `overleaf-toolkit/config/overleaf.rc`: {% code title="config/overleaf.rc" %} ```dotenv SERVER_PRO=true SIBLING_CONTAINERS_ENABLED=true ``` {% endcode %} #### Para utilizador do Docker Compose {% hint style="danger" %} A partir do Overleaf CE/Server Pro `5.0.3` as variáveis de ambiente foram rebatizadas de `SHARELATEX_*` para `OVERLEAF_*`. {% endhint %} Se estiver a usar uma versão `4.x` (ou anterior), certifique-se de que as variáveis têm 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"
            #...
        #...
### Alterar a imagem TexLive {% hint style="info" %} Para utilizadores da China continental, pode usar `ghcr.nju.edu.cn` para acelerar a sua transferência. {% endhint %} O Overleaf Pro usa três variáveis de ambiente para determinar que imagens TeX Live usar nas Compilações em Sandbox: * `TEX_LIVE_DOCKER_IMAGE` **(obrigatório),** A imagem predefinida do TeX Live usada para compilar novos projetos. Esta imagem tem de ser incluída em `ALL_TEX_LIVE_DOCKER_IMAGES`. * `ALL_TEX_LIVE_DOCKER_IMAGE_NAMES` **(obrigatório),** Uma lista separada por vírgulas de nomes amigáveis para as imagens, usada para opções da interface. * `ALL_TEX_LIVE_DOCKER_IMAGES` **(obrigatório),** Uma lista separada por vírgulas de imagens TeX Live a utilizar. Se o Overleaf Toolkit for usado para a implementação, estas imagens serão transferidas ou atualizadas. Para ignorar a transferência, defina `SIBLING_CONTAINERS_PULL=false` em `config/overleaf.rc`. Ao iniciar a sua instância Overleaf Pro usando o `bin/up` comando, o Toolkit irá transferir automaticamente todas as imagens listadas em `ALL_TEX_LIVE_DOCKER_IMAGES`. Aqui está um exemplo em que a predefinição é TeX Live 2025 para novos projetos e mantemos 2024 em uso para projetos existentes. {% tabs %} {% tab title="instalação comum" %} A seguinte configuração instala todas as imagens Docker completas do TeX Live de 2025 a 2026. Recomendamos ter pelo menos 80 GB de armazenamento disponível antes de usar esta configuração. {% code title="config/variables.env" overflow="wrap" %} ```dotenv 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 ``` {% endcode %} {% endtab %} {% tab title="instalação completa" %} A seguinte configuração instala todas as imagens Docker completas do TeX Live de 2020 a 2026. Recomendamos ter pelo menos 256 GB de armazenamento disponível antes de usar esta configuração. {% code title="config/variables.env" overflow="wrap" %} ```dotenv 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 ``` {% endcode %} {% endtab %} {% endtabs %} {% hint style="danger" %} É altamente recomendado definir **pelo menos 2 imagens texlive-full**. Para uma explicação detalhada, consulte [#known-issues](#known-issues "mention") {% endhint %} ### Imagens TeX Live disponíveis Estas são uma série de imagens 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 `latest` tag) * `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` {% hint style="warning" %} Existe um esquema estrito relativo à forma como as imagens **devem** ser etiquetadas (aplica-se a seguinte regex `^[0-9]+.[0-9]+`, em que o primeiro número determina o ano do TeX Live e o segundo a versão da correção). {% endhint %} ### Posso usar outro registo de imagens > Algumas pessoas podem perguntar-se se posso substituir `ghcr.io` por outro site espelho, ou mudar o texlive para outra imagem do Docker Hub? Não, não o recomendamos porque a configuração é relativamente complicada. Se estiver a transferir a partir de um site espelho, pode renomear a sua imagem para `ghcr.io/ayaka-notes/texlive-full`. Mas, se realmente quiser usar o seu próprio Registo de Imagens, adicione: {% code title="config/variables.env" overflow="wrap" %} ```dotenv IMAGE_ROOT=hub.your.com/your-repo ``` {% endcode %} Depois, tem de garantir que todas as imagens do texlive estão 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 compreender como analisamos a sua variável de ambiente: {% code title="sandboxed-compiles/index.mjs" overflow="wrap" expandable="true" %} ```mjs if (process.env.SANDBOXED_COMPILES === 'true') { // Definir a raiz da imagem predefinida se não for fornecida let imageRootPath = process.env.IMAGE_ROOT || "ghcr.io/ayaka-notes"; // Exportar imageRoot para Settings Settings.imageRoot = imageRootPath // allowedImageNames deve ser: // [ // { 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], })) // No final, imageName será combinado com imageRoot para formar o caminho completo da imagem // O nome completo será algo como: ghcr.io/ayaka-notes/texlive-2023:latest // Definir o nome da imagem predefinido se não for fornecido if(!process.env.TEX_LIVE_DOCKER_IMAGE) { process.env.TEX_LIVE_DOCKER_IMAGE = imageRootPath + "/" + Settings.allowedImageNames[0].imageName } // Exportar currentImageName para Settings // Este é o nome da imagem dos projetos recém-criados Settings.currentImageName = process.env.TEX_LIVE_DOCKER_IMAGE } ``` {% endcode %} ### Problemas conhecidos Este é um caso real da comunidade Overleaf: > Usando `6.0.1-ext-v3.3`, tenho estas definições em `variables.env`: > > ```dotenv > TEX_LIVE_DOCKER_IMAGE=texlive/texlive:latest-full > ALL_TEX_LIVE_DOCKER_IMAGES=texlive/texlive:latest-full > ``` > > Isto funciona bem com `texlive/texlive:latest-full`. No entanto, fiz pull de outra imagem texlive `danteev/texlive:2025-10-15` e alterei ambas estas variáveis para o novo nome da imagem, mas não funciona: > > ```dotenv > TEX_LIVE_DOCKER_IMAGE=danteev/texlive:2025-10-15 > ALL_TEX_LIVE_DOCKER_IMAGES=danteev/texlive:2025-10-15 > ``` > > Nos registos, vejo o seguinte: > > {% code overflow="wrap" %} > > ``` > {"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 ... > ``` > > {% endcode %} > > Parece que as definições atualizadas em `variables.env` não estão a ter efeito. A compilação continua a tentar executar a `texlive/texlive:latest-full` imagem, e não a nova imagem. > > Tentei reiniciar, apagar os contentores e voltar a executar, mas continua o mesmo problema. > > Alguma solução? Devido a algumas limitações técnicas, se configurar apenas uma única imagem Docker 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 a sua instância overleaf durante algum tempo, poderá querer modificar a imagem TeXLive para `texlive-fullB:latest`. Então, verá que os seus utilizadores não conseguem compilar todos os projetos. ``` ALL_TEX_LIVE_DOCKER_IMAGES=texlive/texliveA:latest-full ALL_TEX_LIVE_DOCKER_IMAGE_NAMES=TeXLiveA TEX_LIVE_DOCKER_IMAGE=texlive/texliveA:latest-full ``` Isto acontece porque o nome da imagem TeXLive-Full (para compilação em sandbox) em cada projeto é persistido na base de dados. *Só quando o utilizador muda a versão TeXLive do seu projeto, por exemplo, de 2024 para 2025, é que o nome da imagem será alterado na base de dados*. Quando o CLSI compila um projeto, usa o nome da imagem do contentor encontrado na base de dados para compilar o projeto diretamente. Se fornecer apenas uma imagem Docker, os utilizadores não poderão modificar a imagem usada para compilar o projeto. Neste caso, precisa de escrever um script para **modificar manualmente** a imagem TeXLive para todos os projetos dos utilizadores na MongoDB. ### Depuração Execute o seguinte comando para verificar o registo do clsi a partir do toolkit: {% code overflow="wrap" %} ```bash bin/logs clsi ``` {% endcode %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://ayakaleaf-pro.ayaka.space/on-premises/pt/configuracao/overleaf-toolkit/sandboxed-compiles.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.