> ## 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 Ayakaleaf Pro offre la possibilità di eseguire le compilazioni in un ambiente sandbox protetto, per una sicurezza di livello enterprise. Per farlo, esegue ogni progetto nel proprio ambiente Docker isolato e protetto. ### Sicurezza migliorata Le Sandboxed Compiles sono l'approccio consigliato per Ayakaleaf Pro, perché molti documenti LaTeX richiedono o hanno la possibilità di eseguire comandi shell arbitrari durante il processo di compilazione del PDF. Se usi le Sandboxed Compiles, ogni compilazione viene eseguita in un container Docker separato con capacità limitate, non condiviso con altri utenti o progetti e senza accesso a risorse esterne come la rete dell'host. Se provi a eseguire Ayakaleaf Pro **senza** le Sandboxed Compiles, la compilazione viene eseguita insieme alle altre compilazioni simultanee all'interno del container Docker principale e, durante le compilazioni LaTeX, gli utenti hanno pieno accesso in lettura e scrittura alle risorse del container `sharelatex` (file system, rete e variabili d'ambiente). ### Gestione dei pacchetti semplificata Per evitare di installare i pacchetti manualmente, consigliamo di abilitare le Sandboxed Compiles. Si tratta di un'impostazione configurabile di Server Pro che offre ai tuoi utenti lo stesso ambiente TeX Live di overleaf.com, ma all'interno della tua installazione on-premises. Le immagini TeX Live usate dalle Sandboxed Compiles contengono i pacchetti e i font più diffusi, testati con i template della nostra galleria, garantendo la massima compatibilità con i progetti on-premises. Abilitando le Sandboxed Compiles puoi configurare quali versioni di TeX Live gli utenti possono scegliere nei propri progetti e impostare una versione predefinita dell'immagine TeX Live per i nuovi progetti. Se provi a eseguire Ayakaleaf Pro senza le Sandboxed Compiles, la tua istanza userà per impostazione predefinita una versione di TeX Live con schema basic per le compilazioni. Questa versione basic è leggera e contiene solo un sottoinsieme molto limitato di pacchetti LaTeX, il che con ogni probabilità causerà errori di pacchetti mancanti per i tuoi utenti, soprattutto se provano a usare template predefiniti. Poiché Ayakaleaf Pro è stato progettato per funzionare offline, non esiste un modo automatico per integrare i template della galleria di overleaf.com nella tua installazione on-premises; è comunque possibile farlo manualmente, un template alla volta. Per maggiori informazioni su come funziona, consulta la nostra guida al trasferimento dei template da overleaf.com: [#transferring-templates-from-overleaf.com](/it/on-premises/configuration/overleaf-toolkit/templates#transferring-templates-from-overleaf.com "mention"). Le Sandboxed Compiles richiedono che il container `sharelatex` abbia accesso al socket Docker della macchina host (tramite un bind mount), in modo da poter gestire questi container di compilazione affiancati. ## Come funziona Quando le Sandboxed Compiles sono abilitate, il socket Docker viene montato dalla macchina host nel container `sharelatex`, così che il servizio di compilazione nel container possa creare nuovi container Docker sull'host. Quindi, per ogni esecuzione del compilatore in ciascun progetto, il servizio di compilazione LaTeX (CLSI) esegue le seguenti operazioni: * Scrive i file del progetto in una posizione all'interno di `OVERLEAF_DATA_PATH`. * Usa il socket Docker montato per creare un nuovo container `texlive` per l'esecuzione della compilazione. * Fa leggere al container `texlive` i dati del progetto dalla posizione in `OVERLEAF_DATA_PATH`. * Compila il progetto all'interno del container `texlive`. ### Abilitare le Sandboxed Compiles #### Per gli utenti del Toolkit Per abilitare le Sandboxed Compiles (note anche come Sibling containers), imposta le seguenti opzioni di configurazione in `overleaf-toolkit/config/overleaf.rc`: ```dotenv title="config/overleaf.rc" theme={null} SERVER_PRO=true SIBLING_CONTAINERS_ENABLED=true ``` #### Per gli utenti di Docker Compose A partire da Overleaf CE/Server Pro `5.0.3`, le variabili d'ambiente sono state rinominate da `SHARELATEX_*` a `OVERLEAF_*`. Se usi una versione `4.x` (o precedente), assicurati che le variabili abbiano il prefisso corretto (ad es. `SHARELATEX_MONGO_URL` invece di `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" #... #... ``` ### Configurare l'immagine TeX Live Gli utenti della Cina continentale possono sostituire `ghcr.io` con `ghcr.nju.edu.cn` per velocizzare il download. Tuttavia, **NON** usare `ghcr.nju.edu.cn` direttamente nelle impostazioni d'ambiente del Toolkit: devi mantenere `ghcr.io` come unica scelta. Ayakaleaf Pro usa tre variabili d'ambiente per stabilire quali immagini TeX Live usare per le Sandboxed Compiles: * `TEX_LIVE_DOCKER_IMAGE` (obbligatoria): 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` (obbligatoria): un elenco separato da virgole di nomi descrittivi per le immagini, usati per le opzioni nel frontend. * `ALL_TEX_LIVE_DOCKER_IMAGES` (obbligatoria): un elenco separato da virgole delle immagini TeX Live da usare. Se per la distribuzione si usa l'Overleaf Toolkit, queste immagini verranno scaricate o aggiornate. Per saltare il download, imposta `SIBLING_CONTAINERS_PULL=false` in `config/overleaf.rc`. Quando avvii l'istanza di Ayakaleaf Pro con il comando `bin/up`, il Toolkit scarica automaticamente tutte le immagini elencate in `ALL_TEX_LIVE_DOCKER_IMAGES`. Ecco un esempio in cui usiamo TeX Live 2026 come predefinito per i nuovi progetti e manteniamo la 2025 per i progetti esistenti. La seguente configurazione installa tutte le immagini Docker TeX Live complete dal 2025 al 2026. Prima di usare questa configurazione, ti consigliamo di avere almeno **64 GB** di spazio di archiviazione disponibile. ```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 ``` La seguente configurazione installa tutte le immagini Docker TeX Live complete dal 2020 al 2026. Prima di usare questa configurazione, ti consigliamo di avere almeno **150 GB** di spazio di archiviazione disponibile. ```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 ``` Ti consigliamo vivamente di impostare **almeno 2 immagini texlive-full**. Per il motivo dettagliato, consulta [#known-issues](/it/on-premises/configuration/overleaf-toolkit/sandboxed-compiles#known-issues "mention") ### Immagini TeX Live disponibili Questa è una serie di immagini TeX Live ottimizzate appositamente per Overleaf, che possono essere aggiunte anche a `TEX_LIVE_DOCKER_IMAGE` e `ALL_TEX_LIVE_DOCKER_IMAGES`: * `ghcr.io/ayaka-notes/texlive-full:2026.1` (anche con 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` Esiste uno schema rigoroso per il modo in cui le immagini **devono** essere taggate (si applica l'espressione regolare `^[0-9]+.[0-9]+`, in cui il primo numero indica l'anno di TeX Live e il secondo la versione della patch). ### Posso usare un altro registry di immagini? > Alcuni si chiedono se sia possibile sostituire `ghcr.io` con un altro sito mirror, oppure passare a un'altra immagine texlive da Docker Hub. No, non lo consigliamo, perché la configurazione è relativamente complessa. Se scarichi da un sito mirror, puoi rinominare la tua immagine in `ghcr.io/ayaka-notes/texlive-full`. Se però vuoi davvero usare il tuo registry di immagini, aggiungi: ```dotenv title="config/variables.env" wrap theme={null} IMAGE_ROOT=hub.your.com/your-repo ``` Poi devi assicurarti che tutte le immagini texlive si trovino in `your-repo`, ad esempio * `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 le tue variabili d'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 } ``` ### Sincronizzazione automatica delle immagini TeX Live Per evitare di aggiornare manualmente la tua istanza con `bin/up` ogni volta, puoi automatizzare gli aggiornamenti delle immagini TeX Live. Consulta [updating-tex-live-full-images-automatically.md](/it/on-premises/maintenance/updating-tex-live-full-images-automatically "mention"). ### Problemi noti Questo è un caso reale tratto dalla community di Overleaf: > Usando `6.0.1-ext-v3.3`, ho queste impostazioni in `variables.env`: > > ```dotenv theme={null} > TEX_LIVE_DOCKER_IMAGE=texlive/texlive:latest-full > ALL_TEX_LIVE_DOCKER_IMAGES=texlive/texlive:latest-full > ``` > > Funziona correttamente 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 nome della nuova immagine, ma non funziona: > > ```dotenv theme={null} > TEX_LIVE_DOCKER_IMAGE=danteev/texlive:2025-10-15 > ALL_TEX_LIVE_DOCKER_IMAGES=danteev/texlive:2025-10-15 > ``` > > Nei log vedo quanto segue: > > ```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 ... > ``` > > Sembra che le impostazioni aggiornate in `variables.env` non abbiano effetto. La compilazione cerca ancora di usare l'immagine `texlive/texlive:latest-full` e non quella nuova. > > Ho provato a riavviare, a eliminare i container e a rieseguirli, ma il problema persiste. > > Qualche soluzione? A causa di alcune limitazioni tecniche, se configuri una sola immagine Docker di TeX Live, ad esempio `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, dopo aver usato la tua istanza Overleaf per un po' di tempo, decidi di cambiare l'immagine TeX Live in `texlive-fullB:latest`, noterai che i tuoi utenti non riescono più a compilare alcun progetto. ```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 ``` Questo accade perché il nome dell'immagine TeX Live completa (per la compilazione in sandbox) di ogni progetto viene memorizzato nel database. *Il nome dell'immagine nel database cambia solo quando l'utente modifica la versione di TeX Live del proprio progetto, ad esempio dalla 2024 alla 2025*. Quando CLSI compila un progetto, usa direttamente il nome dell'immagine del container presente nel database. Se fornisci una sola immagine Docker, gli utenti non potranno modificare l'immagine usata per compilare il progetto. In questo caso, dovrai scrivere uno script per **modificare manualmente** l'immagine TeX Live di tutti i progetti degli utenti in MongoDB. ### Debug e segnalazioni Esegui il seguente comando per controllare il log di clsi dal Toolkit: ```bash wrap theme={null} bin/logs clsi ``` Se riscontri problemi durante la compilazione con le immagini TeX Live, apri una issue qui: [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) Per aiutarci a riprodurre e analizzare il problema, potrebbe esserti chiesto di caricare il tuo progetto su Overleaf. Noi scaricheremo quindi il progetto ed eseguiremo test di compilazione con GitHub Action. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.