Sandboxed Compiles

Ayakaleaf Pro bietet die Möglichkeit, Kompilierungen für Sicherheit auf Unternehmensniveau in einer abgesicherten Sandbox-Umgebung auszuführen. Dazu wird jedes Projekt in einer eigenen, abgesicherten Docker-Umgebung ausgeführt.

​

Verbesserte Sicherheit

Sandboxed Compiles sind der empfohlene Ansatz für Ayakaleaf Pro, da viele LaTeX-Dokumente im Rahmen des PDF-Kompiliervorgangs beliebige Shell-Befehle ausführen müssen bzw. dazu in der Lage sind. Wenn Sie Sandboxed Compiles verwenden, läuft jede Kompilierung in einem separaten Docker-Container mit eingeschränkten Fähigkeiten, der mit keinem anderen Benutzer oder Projekt geteilt wird und keinen Zugriff auf externe Ressourcen wie das Host-Netzwerk hat.

Wenn Sie Ayakaleaf Pro ohne Sandboxed Compiles betreiben, läuft die Kompilierung zusammen mit anderen gleichzeitigen Kompilierungen im Haupt-Docker-Container, und Benutzer haben beim Ausführen von LaTeX-Kompilierungen vollen Lese- und Schreibzugriff auf die Ressourcen des sharelatex-Containers (Dateisystem, Netzwerk und Umgebungsvariablen).

​

Einfachere Paketverwaltung

Um Pakete nicht manuell installieren zu müssen, empfehlen wir, Sandboxed Compiles zu aktivieren. Dies ist eine konfigurierbare Einstellung in Server Pro, die Ihren Benutzern Zugriff auf dieselbe TeX Live-Umgebung wie auf overleaf.com bietet, jedoch innerhalb Ihrer eigenen On-Premises-Installation. Die von Sandboxed Compiles verwendeten TeX Live-Images enthalten die beliebtesten Pakete und Schriftarten, die mit unseren Galerievorlagen getestet wurden, und gewährleisten so maximale Kompatibilität mit On-Premises-Projekten.

Durch das Aktivieren von Sandboxed Compiles können Sie festlegen, aus welchen TeX Live-Versionen Benutzer in ihrem Projekt wählen können, und eine Standardversion des TeX Live-Images für neue Projekte festlegen.

Wenn Sie Ayakaleaf Pro ohne Sandboxed Compiles betreiben, verwendet Ihre Instanz für Kompilierungen standardmäßig eine TeX Live-Version mit dem Basisschema. Diese Basisversion ist schlank und enthält nur eine sehr begrenzte Auswahl an LaTeX-Paketen, was bei Ihren Benutzern höchstwahrscheinlich zu Fehlern wegen fehlender Pakete führt, insbesondere wenn sie vorgefertigte Vorlagen verwenden.

Da Ayakaleaf Pro für den Offline-Betrieb konzipiert ist, gibt es keine automatisierte Möglichkeit, Galerievorlagen von overleaf.com in Ihre On-Premises-Installation zu integrieren; es ist jedoch möglich, dies manuell für jede einzelne Vorlage durchzuführen. Weitere Informationen dazu finden Sie in unserer Anleitung zum Übertragen von Vorlagen von overleaf.com: #transferring-templates-from-overleaf.com.

Sandboxed Compiles erfordern, dass der sharelatex-Container (über einen Bind-Mount) Zugriff auf den Docker-Socket des Host-Rechners hat, damit er diese benachbarten Kompilier-Container verwalten kann.

​

Funktionsweise

Wenn Sandboxed Compiles aktiviert sind, wird der Docker-Socket vom Host-Rechner in den sharelatex-Container eingebunden, sodass der Compiler-Dienst im Container neue Docker-Container auf dem Host erstellen kann. Bei jedem Compiler-Durchlauf in jedem Projekt führt der LaTeX-Compiler-Dienst (CLSI) dann Folgendes aus:

• Schreiben der Projektdateien an einen Speicherort innerhalb von OVERLEAF_DATA_PATH.
• Verwenden des eingebundenen Docker-Sockets, um einen neuen texlive-Container für den Kompilierdurchlauf zu erstellen.
• Einlesen der Projektdaten aus dem Speicherort unter OVERLEAF_DATA_PATH durch den texlive-Container.
• Kompilieren des Projekts im texlive-Container.

​

Sandboxed Compiles aktivieren

​

Für Toolkit-Benutzer

Um Sandboxed Compiles (auch als Sibling-Container bekannt) zu aktivieren, setzen Sie die folgenden Konfigurationsoptionen in overleaf-toolkit/config/overleaf.rc:

config/overleaf.rc

SERVER_PRO=true
SIBLING_CONTAINERS_ENABLED=true

​

Für Docker Compose-Benutzer

Ab Overleaf CE/Server Pro 5.0.3 wurden die Umgebungsvariablen von SHARELATEX_* in OVERLEAF_* umbenannt.

Wenn Sie eine Version 4.x (oder älter) verwenden, stellen Sie bitte sicher, dass die Variablen das entsprechende Präfix haben (z. B. SHARELATEX_MONGO_URL statt 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"
            #...
        #...

​

TeX Live-Image einrichten

Benutzer in Festlandchina können ghcr.io durch ghcr.nju.edu.cn ersetzen, um den Download zu beschleunigen. Verwenden Sie ghcr.nju.edu.cn jedoch NICHT direkt in den Umgebungseinstellungen Ihres Toolkit. Behalten Sie dort ausschließlich ghcr.io bei.

Ayakaleaf Pro verwendet drei Umgebungsvariablen, um festzulegen, welche TeX Live-Images für Sandboxed Compiles verwendet werden:

• TEX_LIVE_DOCKER_IMAGE (erforderlich): Das Standard-TeX Live-Image zum Kompilieren neuer Projekte. Dieses Image muss in ALL_TEX_LIVE_DOCKER_IMAGES enthalten sein.
• ALL_TEX_LIVE_DOCKER_IMAGE_NAMES (erforderlich): Eine kommagetrennte Liste von Anzeigenamen für die Images, die für die Auswahloptionen im Frontend verwendet werden.
• ALL_TEX_LIVE_DOCKER_IMAGES (erforderlich): Eine kommagetrennte Liste der zu verwendenden TeX Live-Images. Wenn das Overleaf Toolkit für die Bereitstellung verwendet wird, werden diese Images heruntergeladen oder aktualisiert. Um den Download zu überspringen, setzen Sie SIBLING_CONTAINERS_PULL=false in config/overleaf.rc.

Wenn Sie Ihre Ayakaleaf Pro-Instanz mit dem Befehl bin/up starten, lädt das Toolkit automatisch alle in ALL_TEX_LIVE_DOCKER_IMAGES aufgeführten Images herunter.

Hier ist ein Beispiel, in dem für neue Projekte standardmäßig TeX Live 2026 verwendet wird und 2025 für ältere Projekte weiterhin im Einsatz bleibt.

Minimale Installation

Die folgende Konfiguration installiert alle vollständigen TeX Live-Docker-Images von 2025 bis 2026. Wir empfehlen, vor der Verwendung dieser Konfiguration mindestens 64 GB freien Speicherplatz bereitzuhalten.

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

Vollständige Installation

Die folgende Konfiguration installiert alle vollständigen TeX Live-Docker-Images von 2020 bis 2026. Wir empfehlen, vor der Verwendung dieser Konfiguration mindestens 150 GB freien Speicherplatz bereitzuhalten.

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

Es wird dringend empfohlen, mindestens 2 texlive-full-Images einzurichten. Den genauen Grund finden Sie unter #known-issues

​

Verfügbare TeX Live-Images

Dies ist eine Reihe von TeX Live-Images, die speziell für Overleaf optimiert sind und auch zu TEX_LIVE_DOCKER_IMAGE und ALL_TEX_LIVE_DOCKER_IMAGES hinzugefügt werden können:

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

Es gilt ein striktes Schema dafür, wie Images getaggt werden müssen (es gilt der reguläre Ausdruck ^[0-9]+.[0-9]+, wobei die erste Zahl das TeX Live-Jahr und die zweite die Patch-Version angibt).

​

Kann ich eine andere Image-Registry verwenden?

Manche fragen sich vielleicht, ob man ghcr.io durch eine andere Mirror-Seite ersetzen oder texlive auf ein anderes Image von Docker Hub umstellen kann.

Nein, davon raten wir ab, da die Konfiguration relativ kompliziert ist. Wenn Sie von einer Mirror-Seite herunterladen, können Sie Ihr Image in ghcr.io/ayaka-notes/texlive-full umbenennen.

Wenn Sie aber unbedingt Ihre eigene Image-Registry verwenden möchten, fügen Sie Folgendes hinzu:

config/variables.env

IMAGE_ROOT=hub.your.com/your-repo

Anschließend müssen Sie sicherstellen, dass sich alle texlive-Images in your-repo befinden, zum Beispiel:

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

Für detaillierte Informationen lesen Sie den folgenden Quellcode, um zu verstehen, wie wir Ihre Umgebungsvariablen auswerten:

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
}

​

Automatische Synchronisierung der TeX Live-Images

Damit Sie Ihre Instanz nicht jedes Mal manuell mit bin/up aktualisieren müssen, können Sie die Aktualisierung Ihrer TeX Live-Images automatisieren. Siehe updating-tex-live-full-images-automatically.md.

​

Bekannte Probleme

Dies ist ein realer Fall aus der Overleaf-Community:

Ich verwende 6.0.1-ext-v3.3 und habe folgende Einstellungen in variables.env:

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

Mit texlive/texlive:latest-full funktioniert das einwandfrei. Ich habe dann jedoch ein anderes texlive-Image danteev/texlive:2025-10-15 heruntergeladen und beide Variablen auf den neuen Image-Namen geändert, aber es funktioniert nicht:

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

In den Logs sehe ich Folgendes:

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

Es scheint, dass die geänderten Einstellungen in variables.env nicht wirksam werden. Beim Kompilieren wird weiterhin versucht, das Image texlive/texlive:latest-full statt des neuen Images auszuführen.

Ich habe neu gestartet, die Container gelöscht und erneut gestartet, aber das Problem besteht weiterhin.

Gibt es eine Lösung?

Aufgrund technischer Einschränkungen gilt Folgendes: Wenn Sie nur ein einziges Docker-TeXLive-Image einrichten, zum Beispiel 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

und Ihre Overleaf-Instanz eine Weile betreiben, möchten Sie das TeXLive-Image vielleicht auf texlive-fullB:latest ändern. Dann werden Sie feststellen, dass Ihre Benutzer keines ihrer Projekte mehr kompilieren können.

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

Das liegt daran, dass der Name des TeXLive-Full-Images (für die Sandbox-Kompilierung) für jedes Projekt in der Datenbank gespeichert wird. Nur wenn ein Benutzer die TeXLive-Version seines Projekts wechselt, zum Beispiel von 2024 auf 2025, wird der Image-Name in der Datenbank geändert.

Wenn CLSI ein Projekt kompiliert, verwendet es direkt den in der Datenbank gespeicherten Container-Image-Namen.

Wenn Sie nur ein einziges Docker-Image bereitstellen, können Benutzer das für die Kompilierung ihres Projekts verwendete Image nicht ändern. In diesem Fall müssen Sie ein Skript schreiben, um das TeXLive-Image für alle Benutzerprojekte in MongoDB manuell zu ändern.

​

Debugging und Fehlerberichte

Führen Sie den folgenden Befehl aus, um das clsi-Log über das Toolkit zu prüfen:

bin/logs clsi

Wenn beim Kompilieren mit den TeX Live-Images Probleme auftreten, reichen Sie bitte hier ein Issue ein:

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

Damit wir das Problem reproduzieren und beheben können, werden Sie möglicherweise gebeten, Ihr Projekt in Overleaf hochzuladen. Wir laden das Projekt dann herunter und führen Kompilierungstests mit GitHub Action durch.