Vai al contenuto principale
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 Ayakaleaf 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.
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:
config/overleaf.rc
Per disattivarle, imposta SIBLING_CONTAINERS_ENABLED=false ed esegui bin/up. Le compilazioni vengono quindi eseguite all’interno del container sharelatex con il suo TeX Live di base.

Per gli utenti di Docker Compose

Configurare l’immagine TeX Live

Gli utenti della Cina continentale possono scaricare le immagini dal mirror ghcr.nju.edu.cn per velocizzare il download, quindi assegnare loro il nome ghcr.io con un tag:
NON usare ghcr.nju.edu.cn nelle impostazioni d’ambiente del Toolkit: lì mantieni i nomi ghcr.io. Per evitare che bin/up scarichi di nuovo le immagini da ghcr.io, imposta SIBLING_CONTAINERS_PULL=false in config/overleaf.rc. Per mantenere le immagini aggiornate tramite il mirror, vedi Aggiornare automaticamente le immagini TeX Live Full.
Ayakaleaf Pro usa tre variabili d’ambiente per stabilire quali immagini TeX Live usare per le Sandboxed Compiles:
  • TEX_LIVE_DOCKER_IMAGE (facoltativa): l’immagine TeX Live usata dai nuovi progetti. Deve essere una delle immagini presenti in ALL_TEX_LIVE_DOCKER_IMAGES. Se non è impostata, i nuovi progetti usano la prima immagine di ALL_TEX_LIVE_DOCKER_IMAGES.
  • ALL_TEX_LIVE_DOCKER_IMAGE_NAMES (facoltativa): un elenco separato da virgole di nomi per le immagini, nello stesso ordine, mostrati nelle impostazioni del compilatore. Se non è impostata, o è più corta dell’elenco delle immagini, un’immagine viene mostrata con il suo tag, ad esempio 2026.1.
  • 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.
config/variables.env
Ti consigliamo vivamente di impostare almeno 2 immagini texlive-full. Per il motivo dettagliato, consulta #known-issues

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:
config/variables.env
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:
sandboxed-compiles/index.mjs

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.

Problemi noti

Questo è un caso reale tratto dalla community di Overleaf:
Usando 6.0.1-ext-v3.3, ho queste impostazioni in variables.env:
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:
Nei log vedo quanto segue:
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
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.
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:
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 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.

Q&A

Risposta: I container e i file di compilazione sì, dopo un certo intervallo; le immagini TeX Live no.
  • I container di compilazione (project-<project id>-<hash>) vengono riutilizzati tra le compilazioni dello stesso progetto, quindi restano dopo una compilazione. Un controllo eseguito ogni ora rimuove quelli più vecchi di un’ora il cui progetto non è stato compilato nell’ultima ora. Di solito un container scompare da una a due ore dopo l’ultima compilazione. Il riavvio di Overleaf non li rimuove; lo fa il successivo controllo orario.
  • I container per il conteggio delle parole, SyncTeX e la conversione vengono rimossi non appena terminano.
  • I file di compilazione (data/overleaf/data/compiles e output) vengono rimossi quando un progetto non viene usato da un giorno, con un controllo ogni 10 minuti. Quando lo spazio su disco scarseggia, questo periodo viene ridotto gradualmente, fino a mezza giornata.
  • Le immagini TeX Live non vengono mai rimosse, poiché ogni compilazione ne ha bisogno. Per liberare spazio dopo aver rimosso un’immagine da ALL_TEX_LIVE_DOCKER_IMAGES, eliminala con docker image rm <image>.
Non è necessario eliminare manualmente questi container.
Risposta: No. Ogni container di compilazione monta solo la directory di compilazione del proprio progetto, in /compile, e non ha accesso alla rete; non esiste alcuna impostazione per montarvi altre directory dell’host. Carica invece nel progetto i file di cui ha bisogno.
Risposta: Sì. ghcr.io/ayaka-notes/texlive-basic:<year>.1 (da 2020.1 a 2026.1) contiene lo schema basic di TeX Live più alcuni pacchetti come latexmk, xetex e fontspec, senza il set completo di font. È molto più piccola di texlive-full, ma i progetti che usano altri pacchetti riceveranno errori di pacchetti mancanti. Per TeX Live 2025 basic:
config/variables.env
ghcr.io/ayaka-notes/texlive-full:base non è un’immagine basic: non contiene TeX Live e non può compilare.
Risposta: L’editor non lo mostra, e il log di clsi lo registra solo a livello di debug. Tuttavia ogni richiesta di compilazione lo restituisce: apri gli strumenti per sviluppatori del browser, vai alla scheda Network, ricompila e seleziona la richiesta compile. La sua risposta JSON contiene timings in millisecondi, dove compileE2E è l’intera compilazione nel servizio di compilazione e compile è l’esecuzione di LaTeX vera e propria.
Ultima modifica il 13 novembre 2026