Sandlådekompilering

Ayakaleaf Pro har möjlighet att köra kompileringar i en säker sandlådemiljö för säkerhet på företagsnivå. Det sker genom att varje projekt körs i en egen säker Docker-miljö.

​

Förbättrad säkerhet

Sandboxed Compiles är det rekommenderade tillvägagångssättet för Ayakaleaf Pro, eftersom många LaTeX-dokument kräver eller har möjlighet att köra godtyckliga skalkommandon som en del av PDF-kompileringen. Om du använder Sandboxed Compiles körs varje kompilering i en separat Docker-container med begränsade rättigheter som inte delas med någon annan användare eller något annat projekt och som inte har åtkomst till externa resurser, till exempel värdens nätverk.

Om du försöker köra Ayakaleaf Pro utan Sandboxed Compiles körs kompileringen tillsammans med andra samtidiga kompileringar i huvudcontainern för Docker, och användarna har full läs- och skrivåtkomst till resurserna i containern sharelatex (filsystem, nätverk och miljövariabler) när de kör LaTeX-kompileringar.

​

Enklare pakethantering

För att slippa installera paket manuellt rekommenderar vi att du aktiverar Sandboxed Compiles. Detta är en konfigurerbar inställning i Server Pro som ger dina användare tillgång till samma TeX Live-miljö som på overleaf.com, men i din egen lokala installation. TeX Live-imagarna som används av Sandboxed Compiles innehåller de populäraste paketen och typsnitten, testade mot våra galleri-mallar, vilket säkerställer maximal kompatibilitet med lokala projekt.

När Sandboxed Compiles är aktiverat kan du konfigurera vilka TeX Live-versioner användarna kan välja mellan i sina projekt, samt ange en standardversion av TeX Live-imagen för nya projekt.

Om du försöker köra Ayakaleaf Pro utan Sandboxed Compiles använder din instans som standard en version av TeX Live med basic-schemat för kompileringar. Denna grundversion är lättviktig och innehåller bara en mycket begränsad delmängd av LaTeX-paket, vilket med största sannolikhet leder till fel om saknade paket för dina användare, särskilt om de försöker använda färdiga mallar.

Eftersom Ayakaleaf Pro är byggt för att fungera offline finns det inget automatiskt sätt att integrera galleri-mallar från overleaf.com i din lokala installation; det är dock möjligt att göra det manuellt mall för mall. Mer information om hur det fungerar finns i vår guide om att överföra mallar från overleaf.com: #transferring-templates-from-overleaf.com.

Sandboxed Compiles kräver att containern sharelatex har åtkomst till Docker-socketen på värddatorn (via en bind-montering) så att den kan hantera dessa syskoncontainrar för kompilering.

​

Hur det fungerar

När Sandboxed Compiles är aktiverat monteras Docker-socketen från värddatorn in i containern sharelatex, så att kompileringstjänsten i containern kan skapa nya Docker-containrar på värden. För varje körning av kompilatorn i varje projekt gör sedan LaTeX-kompileringstjänsten (CLSI) följande:

• Skriver ut projektfilerna till en plats inom OVERLEAF_DATA_PATH.
• Använder den monterade Docker-socketen för att skapa en ny texlive-container för kompileringen.
• Låter texlive-containern läsa projektdata från platsen under OVERLEAF_DATA_PATH.
• Kompilerar projektet inuti texlive-containern.

​

Aktivera Sandboxed Compiles

​

För Toolkit-användare

För att aktivera sandlådekompilering (även kallat syskoncontainrar, Sibling containers) ställer du in följande konfigurationsalternativ i overleaf-toolkit/config/overleaf.rc:

config/overleaf.rc

SERVER_PRO=true
SIBLING_CONTAINERS_ENABLED=true

​

För Docker Compose-användare

Från och med Overleaf CE/Server Pro 5.0.3 har miljövariablerna bytt namn från SHARELATEX_* till OVERLEAF_*.

Om du använder version 4.x (eller tidigare), se till att variablerna har rätt prefix (t.ex. SHARELATEX_MONGO_URL i stället för 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"
            #...
        #...

​

Konfigurera TeX Live-imagen

Användare i Kina (fastlandet) kan ersätta ghcr.io med ghcr.nju.edu.cn för att snabba upp nedladdningen. Men använd INTE ghcr.nju.edu.cn direkt i miljöinställningarna för Toolkit. Du ska behålla ghcr.io som det enda alternativet.

Ayakaleaf Pro använder tre miljövariabler för att avgöra vilka TeX Live-images som ska användas för Sandboxed Compiles:

• TEX_LIVE_DOCKER_IMAGE (obligatorisk), Standard-imagen för TeX Live som används för att kompilera nya projekt. Imagen måste finnas med i ALL_TEX_LIVE_DOCKER_IMAGES.
• ALL_TEX_LIVE_DOCKER_IMAGE_NAMES (obligatorisk), En kommaseparerad lista med läsbara namn för imagarna, som används för alternativen i gränssnittet.
• ALL_TEX_LIVE_DOCKER_IMAGES (obligatorisk), En kommaseparerad lista med TeX Live-images som ska användas. Om Overleaf Toolkit används för driftsättningen laddas dessa images ner eller uppdateras. För att hoppa över nedladdningen, ställ in SIBLING_CONTAINERS_PULL=false i config/overleaf.rc.

När du startar din Ayakaleaf Pro-instans med kommandot bin/up hämtar Toolkit automatiskt alla images som listas i ALL_TEX_LIVE_DOCKER_IMAGES.

Här är ett exempel där vi använder TeX Live 2026 som standard för nya projekt och behåller 2025 för gamla projekt.

Minimal installation

Följande konfiguration installerar alla fullständiga TeX Live Docker-images från 2025 till 2026. Vi rekommenderar att du har minst 64 GB ledigt lagringsutrymme innan du använder den här konfigurationen.

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

Fullständig installation

Följande konfiguration installerar alla fullständiga TeX Live Docker-images från 2020 till 2026. Vi rekommenderar att du har minst 150 GB ledigt lagringsutrymme innan du använder den här konfigurationen.

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

Vi rekommenderar starkt att du konfigurerar minst 2 texlive-full-images. Den detaljerade orsaken finns i #known-issues

​

Tillgängliga TeX Live-images

Detta är en serie TeX Live-images som är särskilt optimerade för Overleaf och som även kan läggas till i TEX_LIVE_DOCKER_IMAGE och ALL_TEX_LIVE_DOCKER_IMAGES:

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

Det finns ett strikt schema för hur images måste taggas (följande reguljära uttryck gäller: ^[0-9]+.[0-9]+, där den första siffran anger TeX Live-året och den andra patchversionen).

​

Kan jag använda ett annat image-register?

Vissa undrar kanske om man kan ersätta ghcr.io med en annan spegelsajt, eller byta texlive till en annan image från Docker Hub?

Nej, vi rekommenderar det inte eftersom konfigurationen är relativt komplicerad. Om du laddar ner från en spegelsajt kan du byta namn på din image till ghcr.io/ayaka-notes/texlive-full.

Men om du verkligen vill använda ditt eget image-register, lägg till:

config/variables.env

IMAGE_ROOT=hub.your.com/your-repo

Sedan måste du se till att alla texlive-images finns i your-repo, till exempel

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

För mer detaljerad information, läs källkoden nedan för att förstå hur vi tolkar din miljövariabel:

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 av TeX Live-images

För att slippa uppdatera din instans manuellt med bin/up varje gång kan du automatisera uppdateringarna av din TeX Live-image. Se updating-tex-live-full-images-automatically.md.

​

Kända problem

Detta är ett verkligt fall från Overleaf-communityn:

Jag använder 6.0.1-ext-v3.3 och har följande inställningar i variables.env:

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

Detta fungerar bra med texlive/texlive:latest-full. Men jag hämtade en annan texlive-image, danteev/texlive:2025-10-15, och ändrade båda variablerna till det nya imagenamnet, och då fungerar det inte:

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

I loggarna ser jag följande:

{"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 verkar som att de uppdaterade inställningarna i variables.env inte får effekt. Kompileringen försöker fortfarande köra imagen texlive/texlive:latest-full, inte den nya imagen.

Jag har provat att starta om, ta bort containrarna och köra igen, men problemet kvarstår.

Några lösningar?

På grund av vissa tekniska begränsningar gäller följande: om du bara konfigurerar en enda Docker-image för TeXLive, till exempel 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

och efter att ha kört din Overleaf-instans ett tag vill ändra TeXLive-imagen till texlive-fullB:latest, kommer du att se att dina användare inte kan kompilera några projekt.

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 beror på att namnet på TeXLive-Full-imagen (för sandlådekompilering) för varje projekt sparas i databasen. Imagenamnet ändras i databasen endast när användaren byter TeXLive-version för sitt projekt, till exempel från 2024 till 2025.

När CLSI kompilerar ett projekt använder den containerimagenamnet som finns i databasen för att kompilera projektet direkt.

Om du bara tillhandahåller en Docker-image kan användarna inte ändra vilken image som används för att kompilera projektet. I så fall måste du skriva ett skript som manuellt ändrar TeXLive-imagen för alla användarprojekt i MongoDB.

​

Felsökning och rapportering

Kör följande kommando för att kontrollera CLSI-loggen från Toolkit:

bin/logs clsi

Om du stöter på problem vid kompilering med TeX Live-imagarna, skicka in ett ärende här:

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

För att hjälpa oss att återskapa och felsöka problemet kan du bli ombedd att ladda upp ditt projekt till Overleaf. Vi hämtar sedan projektet och kör kompileringstester med GitHub Action.