Ontwikkelomgeving opzetten (lokaal)

Zet je ontwikkelomgeving op met je lokale server of desktop.

​

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.
• Overleaf Pro Edition is beschikbaar op GitHub Ayaka-notes/overleaf-pro.

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 overleaf-cep als voorbeeld om te laten zien hoe je een Overleaf-ontwikkelomgeving configureert.

1. De broncode ophalen

   Laten we eerst de repository klonen:

   bash

   git clone https://github.com/ayaka-notes/overleaf-pro.git
   cd overleaf-pro
   
2. package-lock.json synchroniseren

   Omdat Overleaf wordt ontwikkeld in een interne repository, is de kans groot dat het bestand package-lock.json door bepaalde ontwikkelproblemen niet meer synchroon loopt. We moeten de volgende opdracht uitvoeren om het te synchroniseren (als je een lokale Node.js-omgeving hebt).

   bash

   npm install --package-lock-only --ignore-scripts
   

   Als je Node.js niet hebt geïnstalleerd, geen zorgen: je kunt dezelfde opdracht direct met docker uitvoeren. Voer het uit vanuit de root van de Overleaf-repository:

   bash

   docker run --rm \
     -v "$(pwd)":/workspace \
     -w /workspace \
     node:22.18.0 \
     npm install --package-lock-only --ignore-scripts
   
3. Ontwikkelimage bouwen

   Overleaf biedt een speciale map /develop voor het opslaan van ontwikkelscripts. Bouw gewoon de services:

   bash

   cd ./develop
   bin/build
   

   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. Alle microservices starten

   Start vervolgens de services:

   bash

   bin/up
   

   Zodra de services draaien, open je http://localhost/launchpad om het eerste beheerdersaccount aan te maken.

   Je moet bin/up uitvoeren voordat je de opdracht bin/dev uitvoert. Anders kun je een reeks problemen met rechten tegenkomen.

Standaard zijn beheerdersrechten niet beschikbaar. Je moet het volgende toevoegen aan develop/dev.env. Daarna heb je toegang tot het beheerpaneel.

ADMIN_PRIVILEGE_AVAILABLE=true

​

TeX Live

Voor het compileren van een PDF moet je een TeX Live-image bouwen die de compilatie binnen Docker afhandelt:

docker build texlive -t texlive-full

Om op een macOS-host te compileren, moet je mogelijk het pad naar de Docker-socket overschrijven door in deze map een .env-bestand aan te maken met daarin DOCKER_SOCKET_PATH=/var/run/docker.sock.raw

Je kunt ook ayaka-notes/texlive-full gebruiken; daarbij kun je de tag base gebruiken, de minimale versie van TeX Live.

​

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:

bin/dev

Hiermee worden alle services gestart met node --watch, dat de code automatisch in de gaten houdt en de services zo nodig herstart.

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:

bin/dev [service1] [service2] ... [serviceN]

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.

​

Debuggen

Wanneer ze in ontwikkelmodus draaien, 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 die in een IDE is geïntegreerd. De volgende tabel toont de poort die voor elke service op de hostmachine beschikbaar is:

Service	Poort
web	9229
clsi	9230
chat	9231
contacts	9232
docstore	9233
document-updater	9234
filestore	9235
notifications	9236
real-time	9237
references	9238
history-v1	9239
project-history	9240
linked-url-proxy	9241

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

In de ontwikkelomgeving biedt Overleaf een script bin/logs, maar je moet daarvoor enkele afhankelijkheden installeren:

sudo npm install -g bunyan
# Or sudo apt install node-bunyan 

Of je kunt direct het volgende uitvoeren:

docker compose logs -f [service name]

​

Overige tools

Zodra je alles hebt gedaan, kun je de volgende sectie raadplegen om enkele debugtools toe te voegen aan je Overleaf-ontwikkelomgeving.