Vai al contenuto principale

Prerequisiti

Overleaf è un tipico progetto open source con architettura a microservizi, in cui tutti i servizi vengono eseguiti in Docker. Per configurare un ambiente di sviluppo Overleaf ti servirà un server potente; si consiglia una configurazione di almeno 8 core e 16 GB di RAM, poiché dovrai eseguire più di 20 container contemporaneamente.
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.
Inoltre, in quanto sviluppatore, riteniamo che tu abbia già familiarità con l’installazione di Docker. Ti consigliamo vivamente di usare una versione Ubuntu LTS recente e stabile (ad es. Ubuntu 24.04 nel 2025–2026) e l’ultima versione di Docker per lo sviluppo, in modo da ridurre la possibilità di incontrare errori imprevisti. In sintesi, ti servirà:
  • 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 directory develop, 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 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
Richiede 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:
bash
Una volta che i servizi sono in esecuzione, apri http://localhost/launchpad per creare il primo account amministratore. Aggiungi la porta se hai cambiato 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.
I volumi locali e RustFS sono archivi separati: un progetto creato con S3_ENABLED=true non ha cronologia né file binari dopo il passaggio a false, e viceversa. Per copiare in RustFS i file di un ambiente che girava prima che esistesse S3_ENABLED, segui «Moving existing data into RustFS» in develop/README.md.

Porte

Il sito, la console di RustFS e Hoppscotch sono in ascolto su 127.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:
Vedi Configurare le Sandbox Compiles per i dettagli.
Un progetto creato mentre SANDBOXED_COMPILES era disattivato non ha un’immagine TeX Live. Compila comunque con l’immagine predefinita, ma il passaggio tra codice e PDF fallisce con «That didn’t work. Recompile and try again.» Assegna una volta a questi progetti l’immagine di TEX_LIVE_DOCKER_IMAGE; senza --commit, lo script mostra solo cosa cambierebbe:
dev.env attiva anche le conversioni Pandoc con PANDOC_IMAGE=overleaf-pandoc:local. Costruisci quell’immagine una volta, dalla radice del repository:
Per compilare su un host macOS, potrebbe essere necessario sovrascrivere il percorso del socket Docker creando un file .env nella directory develop con DOCKER_SOCKET_PATH=/var/run/docker.sock.raw

Sviluppo

Per evitare di eseguire bin/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:
Questo avvierà tutti i servizi usando 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.
Se non viene indicato alcun servizio, tutti i servizi verranno avviati in modalità di sviluppo. Dopo aver aggiunto una traduzione o cambiato branch, esegui 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 su 127.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 script bin/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.
In alternativa, puoi eseguire direttamente:
Usa 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.

Altri strumenti

Una volta completato tutto, puoi consultare la sezione successiva per aggiungere alcuni strumenti di debug al tuo ambiente di sviluppo Overleaf.
Ultima modifica il 20 novembre 2026