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.

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

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).

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.

Installazione minima

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

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

Installazione completa

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.

config/variables.env

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

​

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

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:

sandboxed-compiles/index.mjs

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.

​

Problemi noti

Questo è un caso reale tratto dalla community di Overleaf:

Usando 6.0.1-ext-v3.3, ho queste impostazioni in variables.env:

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:

TEX_LIVE_DOCKER_IMAGE=danteev/texlive:2025-10-15
ALL_TEX_LIVE_DOCKER_IMAGES=danteev/texlive:2025-10-15

Nei log vedo quanto segue:

{"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

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.

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:

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

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.