> 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/it/configurazione/overleaf-toolkit/compilazioni-in-sandbox.md). # Compilazioni in sandbox Overleaf Pro include l'opzione di eseguire le compilazioni in un ambiente sandbox protetto per la sicurezza aziendale. Lo fa eseguendo ogni progetto nel proprio ambiente Docker protetto. ### Sicurezza migliorata Le compilazioni in sandbox sono l'approccio consigliato per Server Pro, poiché molti documenti LaTeX richiedono/possono eseguire comandi shell arbitrari come parte del processo di compilazione del PDF. Se usi le compilazioni in sandbox, ogni compilazione viene eseguita in un contenitore Docker separato con funzionalità limitate, non condivise con nessun altro utente o progetto, e non ha accesso a risorse esterne come la rete dell'host. {% hint style="warning" %} Se provi a eseguire Overleaf Pro **senza** le compilazioni in sandbox, la compilazione viene eseguita insieme ad altre compilazioni concorrenti all'interno del contenitore Docker principale e gli utenti hanno pieno accesso in lettura e scrittura alle `sharelatex` risorse del contenitore (filesystem, rete e variabili d'ambiente) quando eseguono compilazioni LaTeX. {% endhint %} ### Gestione dei pacchetti più semplice Per evitare di installare manualmente i pacchetti, consigliamo di abilitare le compilazioni in sandbox. Si tratta di un'impostazione configurabile all'interno di Server Pro che fornirà ai tuoi utenti l'accesso allo stesso ambiente TeX Live presente su overleaf.com, ma all'interno della tua installazione on-premise. Le immagini TeX Live usate dalle compilazioni in sandbox contengono i pacchetti e i font più popolari, testati con i nostri modelli della galleria, garantendo la massima compatibilità con i progetti on-premise. L'abilitazione delle compilazioni in sandbox ti consente di configurare quali versioni di TeX Live gli utenti possono scegliere all'interno del proprio progetto, oltre a impostare una versione immagine TeX Live predefinita per i nuovi progetti. {% hint style="info" %} Se provi a eseguire Overleaf Pro senza compilazioni in sandbox, la tua istanza userà per impostazione predefinita una versione di schema base di TeX Live per le compilazioni. Questa versione base è leggera e contiene solo un insieme molto limitato di pacchetti LaTeX, il che molto probabilmente comporterà errori di pacchetti mancanti per i tuoi utenti, soprattutto se provano a usare modelli predefiniti. {% endhint %} Poiché Overleaf Pro è stato progettato per funzionare offline, non esiste un modo automatizzato per integrare i modelli della galleria di overleaf.com nella tua installazione on-premise; è tuttavia possibile farlo manualmente, modello per modello. Per maggiori informazioni su come funziona, consulta la nostra guida al trasferimento dei modelli da overleaf.com: [/pages/eb1978c02f24f71a098e804381c027156381766e#transferring-templates-from-overleaf.com](https://overleaf-pro.ayaka.space/on-premises/it/configurazione/overleaf-toolkit/pages/eb1978c02f24f71a098e804381c027156381766e#transferring-templates-from-overleaf.com "mention"). {% hint style="info" %} Le compilazioni in sandbox richiedono che il `sharelatex` contenitore abbia accesso al socket Docker sulla macchina host (tramite un bind mount) così da poter gestire questi contenitori di compilazione fratelli. {% endhint %} ## Come funziona Quando le compilazioni in sandbox sono abilitate, il socket Docker verrà montato dalla macchina host nel `sharelatex` contenitore, in modo che il servizio compilatore nel contenitore possa creare nuovi contenitori Docker sull'host. Quindi, per ogni esecuzione del compilatore in ciascun progetto, il servizio compilatore LaTeX (CLSI) eseguirà quanto segue: * Scrivere i file del progetto in una posizione all'interno del `OVERLEAF_DATA_PATH`. * Usare il socket Docker montato per creare un nuovo `texlive` contenitore per l'esecuzione della compilazione. * Far `texlive` leggere al contenitore i dati del progetto dalla posizione sotto `OVERLEAF_DATA_PATH`. * Compilare il progetto all'interno del `texlive` contenitore. ### Abilitare le compilazioni in sandbox #### Per gli utenti del Toolkit Per abilitare le compilazioni in sandbox (note anche come contenitori fratelli), imposta le seguenti opzioni di configurazione in `overleaf-toolkit/config/overleaf.rc`: {% code title="config/overleaf.rc" %} ```dotenv SERVER_PRO=true SIBLING_CONTAINERS_ENABLED=true ``` {% endcode %} #### Per gli utenti di Docker Compose {% hint style="danger" %} A partire da Overleaf CE/Server Pro `5.0.3` le variabili d'ambiente sono state rinominate da `SHARELATEX_*` a `OVERLEAF_*`. {% endhint %} Se stai usando una `4.x` versione (o precedente), assicurati che le variabili siano precedute dal prefisso corretto (ad es. `SHARELATEX_MONGO_URL` invece di `OVERLEAF_MONGO_URL`). 
version: '2'
servizi:
    sharelatex:
        #...
        volumi:
            - /data/overleaf_data:/var/lib/overleaf
            - /var/run/docker.sock:/var/run/docker.sock
        ambiente:
            #...
            DOCKER_RUNNER: "true"
            SANDBOXED_COMPILES: "true"
            SANDBOXED_COMPILES_HOST_DIR: "/data/overleaf_data/data/compiles"
            #...
        #...
### Cambiare l'immagine TexLive {% hint style="info" %} Per gli utenti della Cina continentale, puoi usare `ghcr.nju.edu.cn` per accelerare il download. {% endhint %} Overleaf Pro usa tre variabili d'ambiente per determinare quali immagini TeX Live usare per le compilazioni in sandbox: * `TEX_LIVE_DOCKER_IMAGE` **(obbligatorio),** L'immagine TeX Live predefinita usata per compilare i nuovi progetti. Questa immagine deve essere inclusa in `ALL_TEX_LIVE_DOCKER_IMAGES`. * `ALL_TEX_LIVE_DOCKER_IMAGE_NAMES` **(obbligatorio),** Un elenco separato da virgole di nomi leggibili delle immagini, usato per le opzioni del frontend. * `ALL_TEX_LIVE_DOCKER_IMAGES` **(obbligatorio),** Un elenco separato da virgole di immagini TeX Live da usare. Se il Toolkit di Overleaf viene usato per la distribuzione, queste immagini verranno scaricate o aggiornate. Per saltare il download, imposta `SIBLING_CONTAINERS_PULL=false` in `config/overleaf.rc`. Quando avvii la tua istanza Overleaf Pro usando il `bin/up` comando, il Toolkit scaricherà automaticamente tutte le immagini elencate in `ALL_TEX_LIVE_DOCKER_IMAGES`. Ecco un esempio in cui impostiamo TeX Live 2025 come predefinito per i nuovi progetti e manteniamo in uso il 2024 per i progetti esistenti. {% 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" %} Si consiglia vivamente di impostare **almeno 2 immagini texlive-full**. Per il motivo dettagliato, vedi [#known-issues](#known-issues "mention") {% endhint %} ### Immagini TeX Live disponibili Queste sono una serie di immagini TeX Live appositamente ottimizzate per Overleaf, e possono anche essere aggiunte a `TEX_LIVE_DOCKER_IMAGE` e `ALL_TEX_LIVE_DOCKER_IMAGES`: * `ghcr.io/ayaka-notes/texlive-full:2025.1` (Anche `latest` 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" %} Esiste uno schema rigoroso su come le immagini **devono** essere taggate (si applica la seguente regex `^[0-9]+.[0-9]+`, in cui il primo numero determina l'anno di TeX Live e il secondo la versione della patch). {% endhint %} ### Posso usare un altro registro di immagini > Alcuni potrebbero chiedersi se posso sostituire `ghcr.io` con un altro mirror, o passare texlive a un'altra immagine da Docker Hub? No, non lo consigliamo perché la configurazione è relativamente complicata. Se scarichi da un mirror, puoi rinominare la tua immagine in `ghcr.io/ayaka-notes/texlive-full`. Ma, se vuoi davvero usare il tuo registro di immagini, aggiungi: {% code title="config/variables.env" overflow="wrap" %} ```dotenv IMAGE_ROOT=hub.your.com/your-repo ``` {% endcode %} Poi devi assicurarti che tutte le immagini di texlive siano in `your-repo`, come * `hub.your.com/your-repo/texlive-full:2025.1` * `hub.your.com/your-repo/texlive-full:2024.1` Per informazioni dettagliate, leggi il codice sorgente qui sotto per capire come analizziamo la tua variabile d'ambiente: {% code title="sandboxed-compiles/index.mjs" overflow="wrap" expandable="true" %} ```mjs if (process.env.SANDBOXED_COMPILES === 'true') { // Imposta il root dell'immagine predefinito se non è fornito let imageRootPath = process.env.IMAGE_ROOT || "ghcr.io/ayaka-notes"; // Esporta imageRoot in Settings Settings.imageRoot = imageRootPath // allowedImageNames dovrebbe essere: // [ // { 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], })) // Alla fine, imageName verrà combinato con imageRoot per formare il percorso completo dell'immagine // Il nome completo sarà simile a: ghcr.io/ayaka-notes/texlive-2023:latest // Imposta il nome immagine predefinito se non è fornito if(!process.env.TEX_LIVE_DOCKER_IMAGE) { process.env.TEX_LIVE_DOCKER_IMAGE = imageRootPath + "/" + Settings.allowedImageNames[0].imageName } // Esporta currentImageName in Settings // Questo è il nome dell'immagine dei progetti appena creati Settings.currentImageName = process.env.TEX_LIVE_DOCKER_IMAGE } ``` {% endcode %} ### Problemi noti > Utilizzando `6.0.1-ext-v3.3`, ho queste impostazioni in `variables.env`: > > ```dotenv > TEX_LIVE_DOCKER_IMAGE=texlive/texlive:latest-full > ALL_TEX_LIVE_DOCKER_IMAGES=texlive/texlive:latest-full > ``` > > Questo funziona bene con `texlive/texlive:latest-full`. Tuttavia, ho scaricato un'altra immagine texlive `danteev/texlive:2025-10-15` e ho cambiato entrambe queste variabili con il nuovo nome dell'immagine, ma non funziona: > > ```dotenv > TEX_LIVE_DOCKER_IMAGE=danteev/texlive:2025-10-15 > ALL_TEX_LIVE_DOCKER_IMAGES=danteev/texlive:2025-10-15 > ``` > > Nei log vedo quanto segue: > > {% 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 %} > > Sembra che le impostazioni aggiornate in `variables.env` non stiano avendo effetto. La compilazione continua a provare a eseguire la `texlive/texlive:latest-full` immagine, non la nuova immagine. > > Ho provato a riavviare, eliminare i container e rieseguire, ma il problema è ancora lo stesso. > > Soluzioni? A causa di alcune limitazioni tecniche, se configuri una sola immagine Docker TeXLive, come ad esempio `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 dopo aver eseguito la tua istanza Overleaf per un po', potresti voler modificare l'immagine TeXLive in `texlive-fullB:latest`. Allora vedrai che i tuoi utenti non saranno in grado di compilare tutti i progetti. ``` ALL_TEX_LIVE_DOCKER_IMAGES=texlive/texliveA:latest-full ALL_TEX_LIVE_DOCKER_IMAGE_NAMES=TeXLiveA TEX_LIVE_DOCKER_IMAGE=texlive/texliveA:latest-full ``` Questo perché il nome dell'immagine TeXLive-Full (per la compilazione in sandbox) in ciascun progetto viene mantenuto nel database. *Solo quando l'utente cambia la versione TeXLive del proprio progetto, ad esempio da 2024 a 2025, il nome dell'immagine verrà modificato nel database*. Quando CLSI compila un progetto, usa il nome dell'immagine del container trovato nel database per compilare direttamente il progetto. Se fornisci una sola immagine Docker, gli utenti non potranno modificare l'immagine usata per compilare il progetto. In questo caso, devi scrivere uno script per **modificare manualmente** l'immagine TeXLive per tutti i progetti degli utenti in MongoDB. ### Debug Esegui il seguente comando per controllare il log di clsi dal 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/it/configurazione/overleaf-toolkit/compilazioni-in-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.