Zum Hauptinhalt springen

Voraussetzungen

Overleaf ist ein typisches Open-Source-Projekt mit Microservice-Architektur, bei dem alle Dienste in Docker laufen. Um eine Overleaf-Entwicklungsumgebung einzurichten, benötigen Sie einen leistungsstarken Server; empfohlen wird eine Konfiguration mit mindestens 8 Kernen und 16 GB RAM, da Sie mehr als 20 Container gleichzeitig ausführen müssen.
Da Server mit 8 oder mehr CPU-Kernen in der Regel teuer sind, wird dringend empfohlen, für die Entwicklung Ihren lokalen Computer zu verwenden.
Als Entwickler sollten Sie außerdem bereits mit der Docker-Installation vertraut sein. Wir empfehlen dringend, ein aktuelles und stabiles Ubuntu LTS (z. B. Ubuntu 24.04 in 2025–2026) und die neueste Docker-Version für die Entwicklung zu verwenden, da dies die Wahrscheinlichkeit unerwarteter Fehler verringert. Zusammengefasst benötigen Sie:
  • Einen leistungsstarken Server/Desktop-Rechner für die Entwicklung
  • Ein aktuelles und stabiles Ubuntu LTS (z. B. Ubuntu 24.04)
  • Eine Docker- und Git-Umgebung

Konfigurationsanleitung

Hier zeigen wir am Beispiel von Ayakaleaf Pro, wie eine Overleaf-Entwicklungsumgebung eingerichtet wird. Alle folgenden Befehle laufen im Verzeichnis develop, sofern nicht anders angegeben.
1

Quellcode abrufen

Klonen Sie zunächst das Repository:
bash
2

yarn.lock synchronisieren

Das Repository verwendet Yarn 4 (packageManager in der package.json im Stammverzeichnis), und seine yarn.lock kann mit den package.json-Dateien nicht synchron sein. Synchronisieren Sie sie nach dem ersten Klonen und nach jeder Änderung an einer package.json:
bash
bin/sync führt yarn install --mode=update-lockfile in einem node:24.18.1-Container aus, sodass Sie Node.js auf dem Host nicht benötigen. Committen Sie die geänderte yarn.lock nicht.
3

Entwicklungs-Image bauen

Bauen Sie die Dienste:
bash
Falls Docker beim parallelen Bauen der Dienste nicht genügend RAM hat, erstellen Sie in diesem Verzeichnis eine .env-Datei mit dem Inhalt COMPOSE_PARALLEL_LIMIT=1.
4

Die Übersetzungen anwenden

Die Module von Ayakaleaf Pro speichern ihre Übersetzungen in services/web/locales/locales_patches/, die in den committeten Locale-Dateien nicht enthalten sind. Wenden Sie sie einmal vor dem ersten Start an, sonst zeigen die Seiten dieser Module Schlüssel wie about_to_permanently_delete_accounts statt Text:
bash
Es benötigt jq auf dem Host. Führen Sie es erneut aus, nachdem Sie eine Übersetzung hinzugefügt oder den Branch gewechselt haben, siehe i18n-Übersetzungen aktualisieren.
5

Alle Microservices starten

Starten Sie anschließend die Dienste:
bash
Sobald die Dienste laufen, öffnen Sie http://localhost/launchpad, um das erste Administratorkonto anzulegen. Ergänzen Sie den Port, wenn Sie OVERLEAF_PORT geändert haben (siehe unten).
LDAP ist standardmäßig aktiviert (LDAP_ENABLED=true in dev.rc). Das Launchpad zeigt dann das LDAP-Admin-Formular: Es fragt nur nach einer E-Mail-Adresse, und dieser Admin meldet sich danach über LDAP an, zum Beispiel als professor / professor (professor@planetexpress.com). Die Testbenutzer sind in develop/authentication/README.md aufgeführt. Setzen Sie LDAP_ENABLED=false und SAML_ENABLED=false, um stattdessen einen lokalen Admin mit Passwort anzulegen.
develop/dev.env setzt bereits ADMIN_PRIVILEGE_AVAILABLE=true, sodass Admins das Admin-Panel ohne weitere Einrichtung öffnen können.

Konfiguration (dev.rc)

develop/dev.rc neben dev.env enthält die Schalter der Entwicklungsumgebung, wie overleaf.rc im Overleaf Toolkit. Ändern Sie einen Wert und führen Sie bin/dev erneut aus, um ihn anzuwenden; eine ausgeschaltete Funktion stoppt auch ihre Container. Jede Funktion hat ihre docker-compose.yml und weitere Dateien in einem eigenen Ordner: authentication/ldap, authentication/saml, mail, s3, hoppscotch und grafana. Eine Funktion, die eine web-Einstellung ohne Umgebungsvariable benötigt, bindet eine Datei in /etc/overleaf/settings.d/ ein, und develop/settings.dev-env.cjs führt alle zusammen. Alle bin/*-Skripte laufen über bin/docker-compose, das die Dateien der eingeschalteten Funktionen hinzufügt. Rufen Sie bin/docker-compose statt docker compose auf, wenn Sie selbst einen Compose-Befehl brauchen.
Die lokalen Volumes und RustFS sind getrennte Speicher: Ein mit S3_ENABLED=true angelegtes Projekt hat nach dem Umschalten auf false keinen Verlauf und keine Binärdateien, und umgekehrt. Um die Dateien einer Umgebung, die schon vor S3_ENABLED lief, nach RustFS zu kopieren, folgen Sie „Moving existing data into RustFS“ in develop/README.md.

Ports

Die Website, die RustFS-Konsole und Hoppscotch lauschen auf 127.0.0.1 des Hosts; leiten Sie auf einem entfernten Rechner zuerst ihre Ports weiter, zum Beispiel mit ssh -L 9001:localhost:9001 <host>. Die Website verwendet OVERLEAF_PORT aus dev.rc; ergänzen Sie den Port in den Adressen unten, wenn Sie ihn geändert haben. Mailpit, Grafana, Mongo Express und RedisInsight werden von der Website unter eigenen Pfaden über webpack-dev-server bereitgestellt und brauchen daher keinen eigenen Port. Sobald Sie angemeldet sind, verlinkt das Menü Dev tools in der Navigationsleiste der Website auf sie; eine Seite, deren Funktion in dev.rc ausgeschaltet ist, fehlt dort. Entwicklungswerkzeuge einrichten zeigt, was jedes Tool tut. Die S3-API (Port 9000) und SMTP (Port 1025) sind nur innerhalb des Docker-Netzwerks erreichbar. Mongo (27017), Redis (6379), Mongo Express (8081), RedisInsight (5540) und git-bridge (8000) sind nur auf 127.0.0.1 des Hosts veröffentlicht.

TeX Live

Sandbox-Kompilierungen sind standardmäßig aktiviert: develop/dev.env setzt SANDBOXED_COMPILES=true und die Images ghcr.io/ayaka-notes/texlive-full:2026.1 und ghcr.io/ayaka-notes/texlive-full:2025.1. clsi lädt Images nicht selbst herunter, laden Sie sie daher einmal herunter:
Details finden Sie unter Sandbox-Kompilierung einrichten.
Ein Projekt, das angelegt wurde, während SANDBOXED_COMPILES ausgeschaltet war, hat kein TeX-Live-Image. Es kompiliert weiterhin mit dem Standard-Image, aber das Springen zwischen Code und PDF schlägt mit „That didn’t work. Recompile and try again.“ fehl. Weisen Sie solchen Projekten einmal das Image von TEX_LIVE_DOCKER_IMAGE zu; ohne --commit zeigt das Skript nur an, was es ändern würde:
dev.env schaltet außerdem Pandoc-Konvertierungen mit PANDOC_IMAGE=overleaf-pandoc:local ein. Bauen Sie dieses Image einmal, vom Stammverzeichnis des Repositorys aus:
Um auf einem macOS-Host zu kompilieren, müssen Sie möglicherweise den Pfad zum Docker-Socket überschreiben, indem Sie im Verzeichnis develop eine .env-Datei mit dem Inhalt DOCKER_SOCKET_PATH=/var/run/docker.sock.raw anlegen.

Entwicklung

Damit Sie nicht nach jeder Codeänderung bin/build && bin/up ausführen müssen, können Sie die Overleaf Community Edition im Entwicklungsmodus betreiben, in dem sich die Dienste bei Codeänderungen automatisch aktualisieren. Verwenden Sie dazu das mitgelieferte Skript bin/dev:
Dadurch werden alle Dienste mit node --watch gestartet, das den Code automatisch überwacht und die Dienste bei Bedarf neu startet. Führen Sie es nach einer Änderung an dev.rc erneut aus. Zur Verbesserung der Performance können Sie nur eine Teilmenge der Dienste im Entwicklungsmodus starten, indem Sie dem Skript bin/dev eine durch Leerzeichen getrennte Liste übergeben:
Wenn Sie den Dienst web im Entwicklungsmodus starten, wird web nur bei Änderungen am Backend-Code aktualisiert. Damit auch der Frontend-Code automatisch aktualisiert wird, starten Sie zusätzlich den Dienst webpack im Entwicklungsmodus.
Wenn keine Dienste angegeben werden, starten alle Dienste im Entwicklungsmodus. Führen Sie nach dem Hinzufügen einer Übersetzung oder einem Branch-Wechsel bin/i18n aus, siehe i18n-Übersetzungen aktualisieren.

Debugging

Im Entwicklungsmodus stellen die meisten Dienste einen Debugging-Port bereit, an den Sie einen Debugger anhängen können, etwa den Inspector in den Chrome Dev Tools oder einen in eine IDE integrierten Debugger. Die folgende Tabelle zeigt den Port, der für jeden Dienst auf 127.0.0.1 des Host-Rechners bereitgestellt wird: Um sich über das Remote Debugging von Chrome mit einem Dienst zu verbinden, öffnen Sie chrome://inspect/ und stellen Sie sicher, dass Discover network targets aktiviert ist. Klicken Sie dann auf Configure… und fügen Sie für jeden Dienst, an den Sie einen Debugger anhängen möchten, einen Eintrag localhost:[service port] hinzu. Nach dem Hinzufügen eines Eintrags erscheint der Dienst als Remote Target, das Sie untersuchen und debuggen können.

Logging

Das Skript bin/logs folgt den Logs und formatiert sie mit bunyan. Es benötigt außerdem ggrep, so heißt GNU grep, wenn es unter macOS mit Homebrew installiert wird; Ubuntu hat keinen Befehl ggrep.
Alternativ können Sie die Logs direkt so anzeigen:
Verwenden Sie bin/docker-compose statt docker compose, damit auch die Dienste der Funktionen in dev.rc (mailpit, rustfs, ldap, saml, hoppscotch und grafana mit Prometheus, Loki und den Exportern) gefunden werden. Mit GRAFANA_ENABLED=true liegen die Logs aller Container auch in Grafana, wo sie nach Dienst, Level und Text gefiltert werden können, siehe Entwicklungswerkzeuge einrichten.

Weitere Tools

Wenn Sie alles erledigt haben, finden Sie im nächsten Abschnitt Hinweise, wie Sie Ihrer Overleaf-Entwicklung einige Debugging-Tools hinzufügen.
Zuletzt geändert am 20. November 2026