Sandboxed Compiles

Ayakaleaf Pro biedt de mogelijkheid om compilaties uit te voeren in een beveiligde sandboxomgeving, voor beveiliging op enterpriseniveau. Dit gebeurt door elk project in een eigen beveiligde Docker-omgeving te draaien.

​

Verbeterde beveiliging

Sandboxed Compiles zijn de aanbevolen aanpak voor Ayakaleaf Pro, omdat veel LaTeX-documenten tijdens het compileren naar pdf willekeurige shellcommando’s moeten of kunnen uitvoeren. Als je Sandboxed Compiles gebruikt, draait elke compilatie in een aparte Docker-container met beperkte rechten, die niet wordt gedeeld met andere gebruikers of projecten en geen toegang heeft tot externe resources zoals het hostnetwerk.

Als je Ayakaleaf Pro zonder Sandboxed Compiles probeert te draaien, wordt de compilatie samen met andere gelijktijdige compilaties uitgevoerd in de hoofdcontainer van Docker, en hebben gebruikers tijdens het compileren van LaTeX volledige lees- en schrijftoegang tot de resources van de sharelatex-container (bestandssysteem, netwerk en omgevingsvariabelen).

​

Eenvoudiger pakketbeheer

Om te voorkomen dat je pakketten handmatig moet installeren, raden we aan Sandboxed Compiles in te schakelen. Dit is een configureerbare instelling binnen Server Pro die je gebruikers toegang geeft tot dezelfde TeX Live-omgeving als op overleaf.com, maar dan binnen je eigen on-premise installatie. De TeX Live-images die door Sandboxed Compiles worden gebruikt, bevatten de populairste pakketten en lettertypen, getest met onze galerijsjablonen, wat zorgt voor maximale compatibiliteit met on-premise projecten.

Door Sandboxed Compiles in te schakelen, kun je bepalen uit welke TeX Live-versies gebruikers binnen hun project kunnen kiezen, en kun je een standaardversie van de TeX Live-image instellen voor nieuwe projecten.

Als je Ayakaleaf Pro zonder Sandboxed Compiles probeert te draaien, gebruikt je instantie standaard een basisschemaversie van TeX Live voor compilaties. Deze basisversie is lichtgewicht en bevat slechts een zeer beperkte subset van LaTeX-pakketten, wat waarschijnlijk leidt tot fouten over ontbrekende pakketten bij je gebruikers, vooral als ze kant-en-klare sjablonen proberen te gebruiken.

Omdat Ayakaleaf Pro is ontworpen om offline te werken, is er geen geautomatiseerde manier om galerijsjablonen van overleaf.com in je on-premise installatie te integreren; het is echter wel mogelijk om dit handmatig per sjabloon te doen. Raadpleeg voor meer informatie onze handleiding over het overzetten van sjablonen van overleaf.com: #transferring-templates-from-overleaf.com.

Sandboxed Compiles vereist dat de sharelatex-container toegang heeft tot de Docker-socket op de hostmachine (via een bind mount), zodat deze de naastgelegen compilatiecontainers kan beheren.

​

Hoe het werkt

Wanneer Sandboxed Compiles is ingeschakeld, wordt de Docker-socket van de hostmachine in de sharelatex-container gemount, zodat de compilerservice in de container nieuwe Docker-containers op de host kan aanmaken. Vervolgens doet de LaTeX-compilerservice (CLSI) bij elke compilatie van elk project het volgende:

• De projectbestanden wegschrijven naar een locatie binnen OVERLEAF_DATA_PATH.
• Via de gemounte Docker-socket een nieuwe texlive-container aanmaken voor de compilatie.
• De texlive-container de projectgegevens laten lezen vanaf de locatie onder OVERLEAF_DATA_PATH.
• Het project compileren binnen de texlive-container.

​

Sandboxed Compiles inschakelen

​

Voor Toolkit-gebruikers

Om Sandboxed Compiles (ook wel Sibling containers genoemd) in te schakelen, stel je de volgende configuratieopties in overleaf-toolkit/config/overleaf.rc in:

config/overleaf.rc

SERVER_PRO=true
SIBLING_CONTAINERS_ENABLED=true

​

Voor Docker Compose-gebruikers

Vanaf Overleaf CE/Server Pro 5.0.3 zijn omgevingsvariabelen hernoemd van SHARELATEX_* naar OVERLEAF_*.

Als je een 4.x-versie (of ouder) gebruikt, zorg er dan voor dat de variabelen het juiste voorvoegsel hebben (bijv. SHARELATEX_MONGO_URL in plaats van 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"
            #...
        #...

​

De TeX Live-image instellen

Gebruikers op het Chinese vasteland kunnen ghcr.io vervangen door ghcr.nju.edu.cn om het downloaden te versnellen. Gebruik ghcr.nju.edu.cn echter NIET rechtstreeks in de omgevingsinstellingen van je Toolkit. Houd ghcr.io als enige keuze aan.

Ayakaleaf Pro gebruikt drie omgevingsvariabelen om te bepalen welke TeX Live-images voor Sandboxed Compiles worden gebruikt:

• TEX_LIVE_DOCKER_IMAGE (verplicht), De standaard TeX Live-image voor het compileren van nieuwe projecten. Deze image moet zijn opgenomen in ALL_TEX_LIVE_DOCKER_IMAGES.
• ALL_TEX_LIVE_DOCKER_IMAGE_NAMES (verplicht), Een kommagescheiden lijst met gebruiksvriendelijke namen voor de images, gebruikt voor de opties in de frontend.
• ALL_TEX_LIVE_DOCKER_IMAGES (verplicht), Een kommagescheiden lijst met te gebruiken TeX Live-images. Als de Overleaf Toolkit voor de deployment wordt gebruikt, worden deze images gedownload of bijgewerkt. Stel SIBLING_CONTAINERS_PULL=false in config/overleaf.rc in om het downloaden over te slaan.

Wanneer je je Ayakaleaf Pro-instantie start met het commando bin/up, pullt de Toolkit automatisch alle images die in ALL_TEX_LIVE_DOCKER_IMAGES staan.

Hier is een voorbeeld waarin we voor nieuwe projecten standaard TeX Live 2026 gebruiken en 2025 behouden voor oude projecten.

Minimale installatie

De volgende configuratie installeert alle volledige TeX Live Docker-images van 2025 tot en met 2026. We raden aan minimaal 64 GB vrije opslagruimte te hebben voordat je deze configuratie gebruikt.

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

Volledige installatie

De volgende configuratie installeert alle volledige TeX Live Docker-images van 2020 tot en met 2026. We raden aan minimaal 150 GB vrije opslagruimte te hebben voordat je deze configuratie gebruikt.

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

Het wordt sterk aanbevolen om minimaal 2 texlive-full-images in te stellen. Zie #known-issues voor de gedetailleerde reden.

​

Beschikbare TeX Live-images

Dit is een reeks TeX Live-images die speciaal voor Overleaf zijn geoptimaliseerd en die ook aan TEX_LIVE_DOCKER_IMAGE en ALL_TEX_LIVE_DOCKER_IMAGES kunnen worden toegevoegd:

• ghcr.io/ayaka-notes/texlive-full:2026.1 (ook de 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

Er geldt een strikt schema voor hoe images getagd moeten worden (de volgende regex is van toepassing: ^[0-9]+.[0-9]+, waarbij het eerste getal het TeX Live-jaar bepaalt en het tweede de patchversie).

​

Kan ik een andere image-registry gebruiken?

Sommigen vragen zich misschien af of ze ghcr.io kunnen vervangen door een andere mirrorsite, of texlive kunnen vervangen door een andere image van Docker Hub?

Nee, dat raden we niet aan, omdat de configuratie relatief ingewikkeld is. Als je vanaf een mirrorsite downloadt, kun je je image hernoemen naar ghcr.io/ayaka-notes/texlive-full.

Maar als je echt je eigen image-registry wilt gebruiken, voeg dan het volgende toe:

config/variables.env

IMAGE_ROOT=hub.your.com/your-repo

Vervolgens moet je ervoor zorgen dat alle texlive-images in your-repo staan, zoals

• hub.your.com/your-repo/texlive-full:2025.1
• hub.your.com/your-repo/texlive-full:2024.1

Lees voor meer informatie de onderstaande broncode om te begrijpen hoe we je omgevingsvariabele parsen:

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
}

​

Geautomatiseerde synchronisatie van TeX Live-images

Om te voorkomen dat je je instantie elke keer handmatig met bin/up moet bijwerken, kun je updates van je TeX Live-image automatiseren. Zie updating-tex-live-full-images-automatically.md.

​

Bekende problemen

Dit is een echte casus uit de Overleaf-community:

Met 6.0.1-ext-v3.3 heb ik deze instellingen in variables.env:

TEX_LIVE_DOCKER_IMAGE=texlive/texlive:latest-full
ALL_TEX_LIVE_DOCKER_IMAGES=texlive/texlive:latest-full

Dit werkt prima met texlive/texlive:latest-full. Ik heb echter een andere texlive-image danteev/texlive:2025-10-15 gepulld en beide variabelen gewijzigd naar de nieuwe imagenaam, maar het werkt niet:

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

In de logs zie ik het volgende:

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

Het lijkt erop dat de bijgewerkte instellingen in variables.env niet worden toegepast. De compilatie probeert nog steeds de image texlive/texlive:latest-full te draaien, niet de nieuwe image.

Ik heb geprobeerd opnieuw op te starten, de containers te verwijderen en opnieuw te starten, maar het probleem blijft hetzelfde.

Heeft iemand een oplossing?

Door enkele technische beperkingen geldt het volgende: als je slechts één Docker TeXLive-image instelt, zoals 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

En je na een tijdje met je Overleaf-instantie te hebben gewerkt de TeXLive-image wilt wijzigen naar texlive-fullB:latest, dan zul je merken dat je gebruikers geen enkel project meer kunnen compileren.

ALL_TEX_LIVE_DOCKER_IMAGES=texlive/texliveA:latest-full
ALL_TEX_LIVE_DOCKER_IMAGE_NAMES=TeXLiveA
TEX_LIVE_DOCKER_IMAGE=texlive/texliveA:latest-full

Dit komt doordat de naam van de TeXLive-Full-image (voor sandbox-compilatie) van elk project in de database wordt opgeslagen. Alleen wanneer een gebruiker de TeXLive-versie van zijn project wijzigt, bijvoorbeeld van 2024 naar 2025, wordt de imagenaam in de database aangepast.

Wanneer CLSI een project compileert, gebruikt het de containerimagenaam uit de database om het project direct te compileren.

Als je slechts één Docker-image aanbiedt, kunnen gebruikers de image waarmee hun project wordt gecompileerd niet wijzigen. In dat geval moet je een script schrijven om de TeXLive-image voor alle gebruikersprojecten in MongoDB handmatig aan te passen.

​

Debuggen en melden

Voer het volgende commando uit om de clsi-log vanuit de Toolkit te bekijken:

bin/logs clsi

Als je problemen ondervindt bij het compileren met de TeX Live-images, meld dan hier een issue:

https://github.com/ayaka-notes/texlive-full/issues/new?template=texlive-image-bug.yml

Om ons te helpen het probleem te reproduceren en op te lossen, kan je worden gevraagd je project naar Overleaf te uploaden. We pullen het project dan en voeren compilatietests uit met GitHub Action.