Vereisten
Overleaf is een typisch open-sourceproject met een microservice-architectuur, waarbij alle services in Docker draaien.- De broncode van de officiële Community Edition staat op GitHub Overleaf Official.
- De broncode van Overleaf-CEP is beschikbaar op GitHub Yu-i-i/Overleaf.
- Ayakaleaf Pro is beschikbaar op GitHub ayaka-notes/ayakaleaf-pro.
Omdat servers met 8 of meer CPU-cores doorgaans duur zijn, raden we ten zeerste aan om je lokale computer te gebruiken voor ontwikkeling.
- Een krachtige server/desktop om op te ontwikkelen
- Een recente en stabiele Ubuntu LTS (bijv. Ubuntu 24.04)
- Een Docker- en Git-omgeving
Configuratiehandleiding
Hier gebruiken we Ayakaleaf Pro om te laten zien hoe je een Overleaf-ontwikkelomgeving opzet. Alle commando’s hieronder draaien in de mapdevelop, tenzij anders vermeld.
1
De broncode ophalen
Laten we eerst de repository klonen:
bash
2
yarn.lock synchroniseren
De repository gebruikt Yarn 4 (
packageManager in de package.json in de root), en de yarn.lock kan niet synchroon lopen met de package.json-bestanden. Synchroniseer hem na de eerste clone en na elke wijziging van een package.json:bash
bin/sync voert yarn install --mode=update-lockfile uit in een node:24.18.1-container, dus je hebt geen Node.js op de host nodig. Commit de gewijzigde yarn.lock niet.3
Ontwikkelimage bouwen
Bouw de services:
bash
Als Docker onvoldoende RAM heeft tijdens het parallel bouwen van de services, maak dan in deze map een
.env-bestand aan met daarin COMPOSE_PARALLEL_LIMIT=1.4
De vertalingen toepassen
De modules van Ayakaleaf Pro bewaren hun vertalingen in Het heeft
services/web/locales/locales_patches/, die niet in de gecommitte locale-bestanden staan. Pas ze één keer toe vóór de eerste start, anders tonen de pagina’s van deze modules sleutels zoals about_to_permanently_delete_accounts in plaats van tekst:bash
jq nodig op de host. Voer het opnieuw uit na het toevoegen van een vertaling of het wisselen van branch, zie i18n-vertalingen bijwerken.5
Alle microservices starten
Start vervolgens de services:Zodra de services draaien, open je http://localhost/launchpad om het eerste beheerdersaccount aan te maken. Voeg de poort toe als je
bash
OVERLEAF_PORT hebt gewijzigd (zie hieronder).LDAP staat standaard aan (
LDAP_ENABLED=true in dev.rc). Het launchpad toont dan het LDAP-beheerdersformulier: het vraagt alleen om een e-mailadres, en die beheerder logt daarna in via LDAP, bijvoorbeeld als professor / professor (professor@planetexpress.com). De testgebruikers staan in develop/authentication/README.md. Zet LDAP_ENABLED=false en SAML_ENABLED=false om in plaats daarvan een lokale beheerder met wachtwoord aan te maken.develop/dev.env zet al ADMIN_PRIVILEGE_AVAILABLE=true, dus beheerders kunnen het beheerpaneel openen zonder extra instellingen.Configuratie (dev.rc)
develop/dev.rc, naast dev.env, bevat de schakelaars van de ontwikkelomgeving, zoals overleaf.rc in de Overleaf Toolkit. Wijzig een waarde en voer bin/dev opnieuw uit om hem toe te passen; een uitgeschakelde functie stopt ook haar containers.
Elke functie bewaart haar
docker-compose.yml en andere bestanden in een eigen map: authentication/ldap, authentication/saml, mail, s3, hoppscotch en grafana. Een functie die een web-instelling zonder omgevingsvariabele nodig heeft, koppelt een bestand in /etc/overleaf/settings.d/, en develop/settings.dev-env.cjs voegt ze allemaal samen. Alle bin/*-scripts lopen via bin/docker-compose, dat de bestanden van de ingeschakelde functies toevoegt. Gebruik bin/docker-compose in plaats van docker compose als je zelf een compose-commando nodig hebt.
Poorten
De site, de RustFS-console en Hoppscotch luisteren op127.0.0.1 van de host; stuur op een externe machine eerst hun poorten door, bijvoorbeeld met ssh -L 9001:localhost:9001 <host>. De site gebruikt OVERLEAF_PORT uit dev.rc, dus voeg de poort toe aan de adressen hieronder als je die hebt gewijzigd.
Mailpit, Grafana, Mongo Express en RedisInsight worden door de site op eigen paden aangeboden, via webpack-dev-server, dus ze hebben geen eigen poort nodig. Zodra je bent ingelogd, linkt het menu Dev tools in de navigatiebalk van de site ernaar; een pagina waarvan de functie in
dev.rc uitstaat, wordt weggelaten. Ontwikkeltools instellen laat zien wat elk ervan doet.
De S3-API (poort 9000) en SMTP (poort 1025) zijn alleen binnen het Docker-netwerk bereikbaar. Mongo (27017), Redis (6379), Mongo Express (8081), RedisInsight (5540) en git-bridge (8000) worden alleen op 127.0.0.1 van de host gepubliceerd.
TeX Live
Sandbox-compilaties staan standaard aan:develop/dev.env zet SANDBOXED_COMPILES=true en de images ghcr.io/ayaka-notes/texlive-full:2026.1 en ghcr.io/ayaka-notes/texlive-full:2025.1. clsi haalt zelf geen images op, dus haal ze één keer op:
dev.env zet ook Pandoc-conversies aan met PANDOC_IMAGE=overleaf-pandoc:local. Bouw die image één keer vanuit de root van de repository:
develop een .env-bestand aan te maken met DOCKER_SOCKET_PATH=/var/run/docker.sock.raw
Ontwikkeling
Om te voorkomen dat je na elke codewijzigingbin/build && bin/up moet uitvoeren, kun je Overleaf Community Edition in ontwikkelmodus draaien, waarbij services automatisch worden bijgewerkt bij codewijzigingen.
Gebruik hiervoor het meegeleverde script bin/dev:
node --watch, dat de code automatisch in de gaten houdt en de services zo nodig herstart. Voer het opnieuw uit na het wijzigen van dev.rc.
Om de prestaties te verbeteren, kun je slechts een deel van de services in ontwikkelmodus starten door een door spaties gescheiden lijst mee te geven aan het script bin/dev:
Als je de service
web in ontwikkelmodus start, wordt de service web alleen bijgewerkt bij wijzigingen in de backendcode. Om ook de frontendcode automatisch bij te werken, moet je ook de service webpack in ontwikkelmodus starten.bin/i18n uit, zie i18n-vertalingen bijwerken.
Debuggen
In ontwikkelmodus stellen de meeste services een debugpoort beschikbaar waaraan je een debugger kunt koppelen, zoals de inspector in de Dev Tools van Chrome of een debugger in een IDE. De volgende tabel toont de poort die voor elke service op127.0.0.1 van de hostmachine beschikbaar is:
Om met remote debugging van Chrome aan een service te koppelen, ga je naar chrome://inspect/ en zorg je dat Discover network targets is aangevinkt. Klik vervolgens op Configure… en voeg een item
localhost:[service port] toe voor elke service waaraan je een debugger wilt koppelen.
Na het toevoegen van een item verschijnt de service als een Remote Target die je kunt inspecteren en debuggen.
Logging
Het scriptbin/logs volgt de logs en formatteert ze met bunyan. Het heeft ook ggrep nodig, de naam van GNU grep wanneer die met Homebrew op macOS is geïnstalleerd; Ubuntu heeft geen ggrep-commando.
bin/docker-compose in plaats van docker compose, zodat ook de services van de functies in dev.rc (mailpit, rustfs, ldap, saml, hoppscotch, en grafana met Prometheus, Loki en de exporters) worden gevonden.
Met GRAFANA_ENABLED=true staan de logs van elke container ook in Grafana, waar ze op service, niveau en tekst gefilterd kunnen worden, zie Ontwikkeltools instellen.

