Prerequisiti
Overleaf è un tipico progetto open source con architettura a microservizi, in cui tutti i servizi vengono eseguiti in Docker.- Il codice sorgente ufficiale della Community Edition si trova su GitHub Overleaf Official.
- Il codice sorgente di Overleaf-CEP è disponibile su GitHub Yu-i-i/Overleaf.
- Ayakaleaf Pro è disponibile su GitHub ayaka-notes/ayakaleaf-pro.
Poiché i server con 8 o più core CPU sono in genere costosi, si consiglia vivamente di usare il tuo computer locale per lo sviluppo.
- Un server/desktop potente per lo sviluppo
- Una versione Ubuntu LTS recente e stabile (ad es. Ubuntu 24.04)
- Un ambiente con Docker e Git
Guida alla configurazione
Qui usiamo Ayakaleaf Pro per mostrare come configurare un ambiente di sviluppo di Overleaf. Tutti i comandi seguenti vengono eseguiti nella directorydevelop, salvo diversa indicazione.
1
Scaricare il codice sorgente
Prima di tutto cloniamo il repository:
bash
2
Sincronizzare yarn.lock
Il repository usa Yarn 4 (
packageManager nel package.json principale), e il suo yarn.lock può non essere sincronizzato con i file package.json. Sincronizzalo dopo il primo clone e dopo ogni modifica a un package.json:bash
bin/sync esegue yarn install --mode=update-lockfile in un container node:24.18.1, quindi non ti serve Node.js sull’host. Non committare il yarn.lock modificato.3
Compilare l'immagine di sviluppo
Costruisci i servizi:
bash
Se Docker esaurisce la RAM durante la compilazione parallela dei servizi, crea in questa directory un file
.env contenente COMPOSE_PARALLEL_LIMIT=1.4
Applicare le traduzioni
I moduli di Ayakaleaf Pro conservano le loro traduzioni in Richiede
services/web/locales/locales_patches/, che i file delle localizzazioni committati non contengono. Applicale una volta prima del primo avvio, altrimenti le pagine di questi moduli mostrano chiavi come about_to_permanently_delete_accounts invece del testo:bash
jq sull’host. Eseguilo di nuovo dopo aver aggiunto una traduzione o cambiato branch, vedi Aggiornare le traduzioni i18n.5
Avviare tutti i microservizi
Quindi avvia i servizi:Una volta che i servizi sono in esecuzione, apri http://localhost/launchpad per creare il primo account amministratore. Aggiungi la porta se hai cambiato
bash
OVERLEAF_PORT (vedi sotto).LDAP è attivo per impostazione predefinita (
LDAP_ENABLED=true in dev.rc). Il launchpad mostra quindi il modulo di amministratore LDAP: chiede solo un’email, e quell’amministratore accede poi tramite LDAP, per esempio come professor / professor (professor@planetexpress.com). Gli utenti di test sono elencati in develop/authentication/README.md. Imposta LDAP_ENABLED=false e SAML_ENABLED=false per creare invece un amministratore locale con password.develop/dev.env imposta già ADMIN_PRIVILEGE_AVAILABLE=true, quindi gli amministratori possono aprire il pannello di amministrazione senza configurazioni aggiuntive.Configurazione (dev.rc)
develop/dev.rc, accanto a dev.env, contiene gli interruttori dell’ambiente di sviluppo, come overleaf.rc nell’Overleaf Toolkit. Modifica un valore ed esegui di nuovo bin/dev per applicarlo; una funzionalità disattivata ferma anche i suoi container.
Ogni funzionalità tiene il suo
docker-compose.yml e gli altri file in una cartella propria: authentication/ldap, authentication/saml, mail, s3, hoppscotch e grafana. Una funzionalità che richiede un’impostazione di web senza variabile d’ambiente monta un file in /etc/overleaf/settings.d/, e develop/settings.dev-env.cjs li unisce tutti. Tutti gli script bin/* passano da bin/docker-compose, che aggiunge i file delle funzionalità attive. Usa bin/docker-compose invece di docker compose quando ti serve un comando compose.
Porte
Il sito, la console di RustFS e Hoppscotch sono in ascolto su127.0.0.1 dell’host; su una macchina remota, inoltra prima le loro porte, per esempio ssh -L 9001:localhost:9001 <host>. Il sito usa OVERLEAF_PORT di dev.rc, quindi aggiungi la porta agli indirizzi sotto se l’hai cambiata.
Mailpit, Grafana, Mongo Express e RedisInsight sono serviti dal sito sui propri percorsi, tramite webpack-dev-server, quindi non serve loro una porta propria. Dopo l’accesso, il menu Dev tools nella barra di navigazione del sito vi rimanda; una pagina la cui funzionalità è disattivata in
dev.rc viene omessa. Configurare gli strumenti di sviluppo mostra cosa fa ciascuno.
L’API S3 (porta 9000) e SMTP (porta 1025) sono raggiungibili solo dentro la rete Docker. Mongo (27017), Redis (6379), Mongo Express (8081), RedisInsight (5540) e git-bridge (8000) sono pubblicati solo su 127.0.0.1 dell’host.
TeX Live
Le compilazioni in sandbox sono attive per impostazione predefinita:develop/dev.env imposta SANDBOXED_COMPILES=true e le immagini ghcr.io/ayaka-notes/texlive-full:2026.1 e ghcr.io/ayaka-notes/texlive-full:2025.1. clsi non scarica le immagini da solo, quindi scaricale una volta:
dev.env attiva anche le conversioni Pandoc con PANDOC_IMAGE=overleaf-pandoc:local. Costruisci quell’immagine una volta, dalla radice del repository:
.env nella directory develop con DOCKER_SOCKET_PATH=/var/run/docker.sock.raw
Sviluppo
Per evitare di eseguirebin/build && bin/up dopo ogni modifica al codice, puoi eseguire Overleaf Community Edition in modalità di sviluppo, in cui i servizi si aggiornano automaticamente quando il codice cambia.
Per farlo, usa lo script incluso bin/dev:
node --watch, che monitorerà automaticamente il codice e riavvierà i servizi quando necessario. Eseguilo di nuovo dopo aver modificato dev.rc.
Per migliorare le prestazioni, puoi avviare in modalità di sviluppo solo un sottoinsieme dei servizi, passando allo script bin/dev un elenco separato da spazi:
Avviare il servizio
web in modalità di sviluppo aggiornerà il servizio web solo quando cambia il codice backend. Per aggiornare automaticamente anche il codice frontend, assicurati di avviare in modalità di sviluppo anche il servizio webpack.bin/i18n, vedi Aggiornare le traduzioni i18n.
Debug
In modalità sviluppo la maggior parte dei servizi espone una porta di debug a cui puoi collegare un debugger, come l’inspector dei Dev Tools di Chrome o uno integrato in un IDE. La tabella seguente mostra la porta esposta su127.0.0.1 della macchina host per ogni servizio:
Per collegarti a un servizio tramite il remote debugging di Chrome, vai su chrome://inspect/ e assicurati che l’opzione Discover network targets sia selezionata. Quindi fai clic su Configure… e aggiungi una voce
localhost:[service port] per ciascuno dei servizi a cui vuoi collegare un debugger.
Dopo aver aggiunto una voce, il servizio comparirà come Remote Target che potrai ispezionare ed eseguire in debug.
Log
Lo scriptbin/logs segue i log e li formatta con bunyan. Richiede anche ggrep, il nome di GNU grep quando è installato con Homebrew su macOS; Ubuntu non ha un comando ggrep.
bin/docker-compose invece di docker compose, così vengono trovati anche i servizi delle funzionalità in dev.rc (mailpit, rustfs, ldap, saml, hoppscotch e grafana con Prometheus, Loki e gli exporter).
Con GRAFANA_ENABLED=true, i log di ogni container sono anche in Grafana, dove si possono filtrare per servizio, livello e testo, vedi Configurare gli strumenti di sviluppo.

