> For the complete documentation index, see [llms.txt](https://overleaf-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://overleaf-pro.ayaka.space/on-premises/pt/configuracao/overleaf-toolkit/compilacoes-em-ambiente-sandbox.md). # Compilações em ambiente sandbox O Overleaf Pro inclui a opção de executar compilações num ambiente sandbox seguro para segurança empresarial. Faz isso ao executar 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 a muitos documentos LaTeX exigirem/tendo a capacidade de executar comandos de shell arbitrários como parte do processo de compilação de PDF. Se usar Compilações em sandbox, cada compilação é executada num contêiner Docker separado com capacidades limitadas que não são partilhadas com qualquer 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 juntamente com outras compilações concorrentes dentro do contêiner Docker principal e os utilizadores têm acesso total de leitura e escrita aos `sharelatex` recursos do contêiner (sistema de ficheiros, rede e variáveis de ambiente) ao executar 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 do 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 de quais versões do TeX Live os utilizadores podem escolher no seu projeto, bem como definir uma versão predefinida da imagem TeX Live para novos projetos. {% hint style="info" %} Se tentar executar o Overleaf Pro sem Compilações em sandbox, a sua instância ficará por predefinição a usar uma versão de esquema básico do TeX Live para as 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 arquitetado para funcionar offline, não existe uma forma automatizada de integrar modelos da galeria do overleaf.com na sua instalação local; no entanto, é 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://overleaf-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` contêiner tenha acesso ao socket Docker na máquina anfitriã (via montagem bind) para que possa gerir estes contêineres irmãos de compilação. {% endhint %} ## Como funciona Quando as Compilações em sandbox estão ativadas, o socket Docker será montado da máquina anfitriã para o `sharelatex` contêiner, para que o serviço de compilação no contêiner possa criar novos contêineres 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: * Escrever os ficheiros do projeto numa localização dentro do `OVERLEAF_DATA_PATH`. * Usar o socket Docker montado para criar um novo `texlive` contêiner para a execução da compilação. * Fazer com que o `texlive` contêiner leia os dados do projeto a partir da localização em `OVERLEAF_DATA_PATH`. * Compilar o projeto dentro do `texlive` contentor. ### Ativar as Compilações em sandbox #### Para utilizadores do Toolkit Para ativar compilações em sandbox (também conhecidas como contêineres 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 utilizadores do Docker Compose {% hint style="danger" %} A partir do Overleaf CE/Server Pro `5.0.3` as variáveis de ambiente foram renomeadas de `SHARELATEX_*` para `OVERLEAF_*`. {% endhint %} Se você estiver usando uma `4.x` versão (ou anterior), certifique-se de que as variáveis têm o prefixo adequado (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 quais imagens TeX Live utilizar para as Compilações em sandbox: * `TEX_LIVE_DOCKER_IMAGE` **(obrigatório),** A imagem TeX Live predefinida usada para compilar novos projetos. Esta imagem tem de estar incluída em `ALL_TEX_LIVE_DOCKER_IMAGES`. * `ALL_TEX_LIVE_DOCKER_IMAGE_NAMES` **(obrigatório),** Uma lista de nomes amigáveis das imagens, separados por vírgulas, usada para opções na interface. * `ALL_TEX_LIVE_DOCKER_IMAGES` **(obrigatório),** Uma lista de imagens TeX Live, separadas por vírgulas, a usar. Se o Overleaf Toolkit for usado para a implementação, estas imagens serão descarregadas ou atualizadas. Para ignorar o descarregamento, defina `SIBLING_CONTAINERS_PULL=false` em `config/overleaf.rc`. Ao iniciar a sua instância do Overleaf Pro usando o `bin/up` comando, o Toolkit irá obter automaticamente todas as imagens listadas em `ALL_TEX_LIVE_DOCKER_IMAGES`. Aqui está um exemplo em que usamos por predefinição o TeX Live 2025 para novos projetos e mantemos 2024 em uso para projetos existentes. {% code title="config/variables.env" overflow="wrap" %} ```dotenv ALL_TEX_LIVE_DOCKER_IMAGES=ghcr.io/ayaka-notes/texlive-full:2025.1, ghcr.io/ayaka-notes/texlive-full:2024.1 ALL_TEX_LIVE_DOCKER_IMAGE_NAMES=Texlive 2025, Texlive 2024 TEX_LIVE_DOCKER_IMAGE=ghcr.io/ayaka-notes/texlive-full:2025.1 ``` {% endcode %} {% hint style="danger" %} É altamente recomendável 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, e também podem ser adicionadas a `TEX_LIVE_DOCKER_IMAGE` e `ALL_TEX_LIVE_DOCKER_IMAGES`: * `ghcr.io/ayaka-notes/texlive-full:2025.1` (Também `mais recente` tag) * `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 rigoroso relativamente à 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 de correção). {% endhint %} ### Posso usar outro registo de imagens > Algumas pessoas podem perguntar-se se posso substituir `ghcr.io` por outro site espelho, ou trocar o texlive por outra imagem do Docker Hub? Não, não o recomendamos porque a configuração é relativamente complicada. Se estiver a transferir 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, precisa 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 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á juntado 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 predefinida 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 > Usar `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, descarreguei 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 produzir efeito. A compilação continua a tentar executar a `texlive/texlive:latest-full` imagem, e não a nova imagem. > > Tentei reiniciar, eliminar os contêineres e voltar a executar, mas o problema continua. > > 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 do Overleaf durante algum tempo, poderá querer alterar 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 deve-se ao facto de o nome da imagem TeXLive-Full (para compilação em sandbox) em cada projeto ficar persistido na base de dados. *Só quando o utilizador mudar 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 contêiner 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 de 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://overleaf-pro.ayaka.space/on-premises/pt/configuracao/overleaf-toolkit/compilacoes-em-ambiente-sandbox.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.