Sandboxed Compiles

Ayakaleaf Pro giver mulighed for at køre kompileringer i et sikret sandkassemiljø for at opnå sikkerhed på virksomhedsniveau. Det sker ved at køre hvert projekt i sit eget sikrede Docker-miljø.

​

Forbedret sikkerhed

Sandboxed Compiles er den anbefalede tilgang for Ayakaleaf Pro, fordi mange LaTeX-dokumenter kræver eller har mulighed for at udføre vilkårlige shell-kommandoer som en del af PDF-kompileringsprocessen. Hvis du bruger Sandboxed Compiles, kører hver kompilering i en separat Docker-container med begrænsede rettigheder, som ikke deles med nogen anden bruger eller noget andet projekt, og som ikke har adgang til eksterne ressourcer såsom værtens netværk.

Hvis du forsøger at køre Ayakaleaf Pro uden Sandboxed Compiles, kører kompileringen side om side med andre samtidige kompileringer i den primære Docker-container, og brugerne har fuld læse- og skriveadgang til sharelatex-containerens ressourcer (filsystem, netværk og miljøvariabler), når de kører LaTeX-kompileringer.

​

Nemmere pakkehåndtering

For at undgå manuel installation af pakker anbefaler vi at aktivere Sandboxed Compiles. Dette er en konfigurerbar indstilling i Server Pro, som giver dine brugere adgang til det samme TeX Live-miljø som på overleaf.com, men i din egen on-premises-installation. TeX Live-images, der bruges af Sandboxed Compiles, indeholder de mest populære pakker og skrifttyper, testet mod vores galleriskabeloner, hvilket sikrer maksimal kompatibilitet med on-premises-projekter.

Når Sandboxed Compiles er aktiveret, kan du konfigurere, hvilke TeX Live-versioner brugerne kan vælge mellem i deres projekt, samt angive en standardversion af TeX Live-imaget til nye projekter.

Hvis du forsøger at køre Ayakaleaf Pro uden Sandboxed Compiles, vil din instans som standard bruge en TeX Live-version med det grundlæggende skema (basic scheme) til kompileringer. Denne grundlæggende version er let og indeholder kun et meget begrænset udvalg af LaTeX-pakker, hvilket højst sandsynligt vil resultere i fejl om manglende pakker for dine brugere, især hvis de forsøger at bruge færdigbyggede skabeloner.

Da Ayakaleaf Pro er designet til at fungere offline, findes der ingen automatiseret måde at integrere galleriskabeloner fra overleaf.com i din on-premises-installation; det er dog muligt at gøre det manuelt skabelon for skabelon. Se vores vejledning om overførsel af skabeloner fra overleaf.com for at få flere oplysninger om, hvordan det fungerer: #transferring-templates-from-overleaf.com.

Sandboxed Compiles kræver, at sharelatex-containeren har adgang til Docker-socketten på værtsmaskinen (via en bind mount), så den kan administrere disse søskende-kompileringscontainere.

​

Sådan fungerer det

Når Sandboxed Compiles er aktiveret, monteres Docker-socketten fra værtsmaskinen ind i sharelatex-containeren, så kompileringstjenesten i containeren kan oprette nye Docker-containere på værten. For hver kørsel af kompileren i hvert projekt gør LaTeX-kompileringstjenesten (CLSI) derefter følgende:

• Skriver projektfilerne til en placering inden for OVERLEAF_DATA_PATH.
• Bruger den monterede Docker-socket til at oprette en ny texlive-container til kompileringskørslen.
• Lader texlive-containeren læse projektdataene fra placeringen under OVERLEAF_DATA_PATH.
• Kompilerer projektet inde i texlive-containeren.

​

Aktivering af Sandboxed Compiles

​

For Toolkit-brugere

For at aktivere Sandboxed Compiles (også kendt som Sibling containers) skal du sætte følgende konfigurationsindstillinger i overleaf-toolkit/config/overleaf.rc:

config/overleaf.rc

SERVER_PRO=true
SIBLING_CONTAINERS_ENABLED=true

​

For Docker Compose-brugere

Fra og med Overleaf CE/Server Pro 5.0.3 er miljøvariablerne blevet omdøbt fra SHARELATEX_* til OVERLEAF_*.

Hvis du bruger en 4.x-version (eller tidligere), skal du sørge for, at variablerne har det tilsvarende præfiks (f.eks. SHARELATEX_MONGO_URL i stedet for 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"
            #...
        #...

​

Opsætning af TeX Live-imaget

Brugere i det kinesiske fastland kan erstatte ghcr.io med ghcr.nju.edu.cn for at gøre download hurtigere. Men brug IKKE ghcr.nju.edu.cn direkte i dine miljøindstillinger for Toolkit. Du skal beholde ghcr.io som dit eneste valg.

Ayakaleaf Pro bruger tre miljøvariabler til at bestemme, hvilke TeX Live-images der skal bruges til Sandboxed Compiles:

• TEX_LIVE_DOCKER_IMAGE (påkrævet), Standard-TeX Live-imaget, der bruges til at kompilere nye projekter. Dette image skal være inkluderet i ALL_TEX_LIVE_DOCKER_IMAGES.
• ALL_TEX_LIVE_DOCKER_IMAGE_NAMES (påkrævet), En kommasepareret liste over brugervenlige navne til imagesne, som bruges til valgmulighederne i frontend.
• ALL_TEX_LIVE_DOCKER_IMAGES (påkrævet), En kommasepareret liste over TeX Live-images, der skal bruges. Hvis Overleaf Toolkit bruges til udrulning, bliver disse images downloadet eller opdateret. For at springe download over skal du sætte SIBLING_CONTAINERS_PULL=false i config/overleaf.rc.

Når du starter din Ayakaleaf Pro-instans med kommandoen bin/up, henter Toolkit automatisk alle de images, der er angivet i ALL_TEX_LIVE_DOCKER_IMAGES.

Her er et eksempel, hvor vi som standard bruger TeX Live 2026 til nye projekter og beholder 2025 til gamle projekter.

Minimal installation

Følgende konfiguration installerer alle fulde TeX Live Docker-images fra 2025 til 2026. Vi anbefaler at have mindst 64 GB ledig lagerplads, før du bruger denne konfiguration.

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

Fuld installation

Følgende konfiguration installerer alle fulde TeX Live Docker-images fra 2020 til 2026. Vi anbefaler at have mindst 150 GB ledig lagerplads, før du bruger denne konfiguration.

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

Det anbefales kraftigt at angive mindst 2 texlive-full-images. Se #known-issues for den detaljerede begrundelse.

​

Tilgængelige TeX Live-images

Dette er en række TeX Live-images, der er specielt optimeret til Overleaf, og som også kan tilføjes til TEX_LIVE_DOCKER_IMAGE og ALL_TEX_LIVE_DOCKER_IMAGES:

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

Der er et strengt skema for, hvordan images skal tagges (følgende regulære udtryk gælder: ^[0-9]+.[0-9]+, hvor det første tal angiver TeX Live-året og det andet patch-versionen).

​

Kan jeg bruge et andet image-registry?

Nogle spekulerer måske på, om man kan erstatte ghcr.io med et andet spejlwebsted eller skifte texlive til et andet image fra Docker Hub?

Nej, det anbefaler vi ikke, da konfigurationen er forholdsvis kompliceret. Hvis du downloader fra et spejlwebsted, kan du omdøbe dit image til ghcr.io/ayaka-notes/texlive-full.

Men hvis du virkelig vil bruge dit eget image-registry, skal du tilføje:

config/variables.env

IMAGE_ROOT=hub.your.com/your-repo

Derefter skal du sikre dig, at alle texlive-images ligger i your-repo, f.eks.

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

For detaljerede oplysninger kan du læse kildekoden nedenfor for at forstå, hvordan vi fortolker dine miljøvariabler:

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
}

​

Automatisk synkronisering af TeX Live-images

For at undgå manuelt at skulle opdatere din instans med bin/up hver gang, kan du automatisere opdateringer af dit TeX Live-image. Se updating-tex-live-full-images-automatically.md.

​

Kendte problemer

Dette er et virkeligt tilfælde fra Overleaf-fællesskabet:

Jeg bruger 6.0.1-ext-v3.3 og har disse indstillinger i variables.env:

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

Det fungerer fint med texlive/texlive:latest-full. Men jeg hentede et andet texlive-image, danteev/texlive:2025-10-15, og ændrede begge variabler til det nye imagenavn, men det virker ikke:

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

I logfilerne ser jeg følgende:

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

Det ser ud til, at de opdaterede indstillinger i variables.env ikke træder i kraft. Kompileringen forsøger stadig at køre texlive/texlive:latest-full-imaget og ikke det nye image.

Jeg har prøvet at genstarte, slette containerne og køre igen, men problemet er det samme.

Er der nogen løsninger?

På grund af visse tekniske begrænsninger gælder det, at hvis du kun opsætter ét enkelt Docker TeXLive-image, såsom 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

og efter at have kørt din Overleaf-instans et stykke tid vil ændre TeXLive-imaget til texlive-fullB:latest, så vil du opleve, at dine brugere ikke kan kompilere nogen projekter.

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

Det skyldes, at navnet på TeXLive-Full-imaget (til sandkassekompilering) for hvert projekt gemmes i databasen. Kun når brugeren skifter sit projekts TeXLive-version, for eksempel fra 2024 til 2025, ændres imagenavnet i databasen.

Når CLSI kompilerer et projekt, bruger den containerimagenavnet fra databasen til direkte at kompilere projektet.

Hvis du kun angiver ét Docker-image, kan brugerne ikke ændre det image, der bruges til at kompilere projektet. I så fald skal du skrive et script, der manuelt ændrer TeXLive-imaget for alle brugerprojekter i MongoDB.

​

Fejlfinding og rapportering

Kør følgende kommando for at se CLSI-loggen fra Toolkit:

bin/logs clsi

Hvis du støder på problemer med at kompilere med TeX Live-imagesne, så opret venligst en issue her:

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

For at hjælpe os med at genskabe og fejlsøge problemet kan du blive bedt om at uploade dit projekt til Overleaf. Vi henter derefter projektet og kører kompileringstest med GitHub Action.