Naar hoofdinhoud gaan

Vereisten

Overleaf is een typisch open-sourceproject met een microservice-architectuur, waarbij alle services in Docker draaien. Om een Overleaf-ontwikkelomgeving op te zetten heb je een krachtige server nodig; een configuratie van minimaal 8 cores en 16 GB RAM wordt aanbevolen, omdat je meer dan 20 containers tegelijk moet draaien.
Omdat servers met 8 of meer CPU-cores doorgaans duur zijn, raden we ten zeerste aan om je lokale computer te gebruiken voor ontwikkeling.
Als ontwikkelaar ga je er ondertussen van uit dat je al bekend bent met de installatie van Docker. We raden sterk aan om een recente en stabiele Ubuntu LTS (bijv. Ubuntu 24.04 in 2025–2026) en de nieuwste Docker te gebruiken voor ontwikkeling, omdat dit de kans op onverwachte fouten verkleint. Samengevat heb je het volgende nodig:
  • 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 map develop, 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 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
Het heeft 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:
bash
Zodra de services draaien, open je http://localhost/launchpad om het eerste beheerdersaccount aan te maken. Voeg de poort toe als je 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.
De lokale volumes en RustFS zijn aparte opslag: een project dat is aangemaakt met S3_ENABLED=true heeft na het overschakelen naar false geen geschiedenis of binaire bestanden, en omgekeerd. Om de bestanden van een omgeving die al draaide voordat S3_ENABLED bestond naar RustFS te kopiëren, volg je ‘Moving existing data into RustFS’ in develop/README.md.

Poorten

De site, de RustFS-console en Hoppscotch luisteren op 127.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:
Zie Sandbox-compilaties instellen voor de details.
Een project dat is aangemaakt terwijl SANDBOXED_COMPILES uit stond, heeft geen TeX Live-image. Het compileert nog steeds met de standaardimage, maar springen tussen de code en de PDF mislukt met ‘That didn’t work. Recompile and try again.’ Geef zulke projecten één keer de image van TEX_LIVE_DOCKER_IMAGE; zonder --commit toont het script alleen wat het zou wijzigen:
dev.env zet ook Pandoc-conversies aan met PANDOC_IMAGE=overleaf-pandoc:local. Bouw die image één keer vanuit de root van de repository:
Om op een macOS-host te compileren, moet je mogelijk het pad naar de Docker-socket overschrijven door in de map develop een .env-bestand aan te maken met DOCKER_SOCKET_PATH=/var/run/docker.sock.raw

Ontwikkeling

Om te voorkomen dat je na elke codewijziging bin/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:
Hiermee worden alle services gestart met 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.
Als er geen services worden opgegeven, starten alle services in ontwikkelmodus. Voer na het toevoegen van een vertaling of het wisselen van branch 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 op 127.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 script bin/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.
Of je kunt direct het volgende uitvoeren:
Gebruik 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.

Overige tools

Zodra je alles hebt gedaan, kun je de volgende sectie raadplegen om enkele debugtools toe te voegen aan je Overleaf-ontwikkelomgeving.
Laatst gewijzigd op 20 november 2026