Configurare l'ambiente di sviluppo (locale)

Configura il tuo ambiente di sviluppo sul tuo server locale o sul tuo computer desktop.

​

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.
• Overleaf Pro Edition è disponibile su GitHub Ayaka-notes/overleaf-pro.

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 useremo overleaf-cep come esempio per mostrare come configurare un ambiente di sviluppo Overleaf.

1. Scaricare il codice sorgente

   Prima di tutto cloniamo il repository:

   bash

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

   Poiché Overleaf viene sviluppato in un repository interno, è molto probabile che il file package-lock.json non sia sincronizzato a causa di alcuni problemi di sviluppo. Dobbiamo eseguire il comando seguente per sincronizzarlo (se hai un ambiente nodejs locale):

   bash

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

   Se non hai nodejs installato, non preoccuparti: puoi usare direttamente docker per eseguire lo stesso comando. Eseguilo dalla radice del repository Overleaf:

   bash

   docker run --rm \
     -v "$(pwd)":/workspace \
     -w /workspace \
     node:22.18.0 \
     npm install --package-lock-only --ignore-scripts
   
3. Compilare l'immagine di sviluppo

   Overleaf fornisce una directory dedicata /develop per conservare gli script di sviluppo. Compila semplicemente i servizi:

   bash

   cd ./develop
   bin/build
   

   Se Docker esaurisce la RAM durante la compilazione parallela dei servizi, crea in questa directory un file .env contenente COMPOSE_PARALLEL_LIMIT=1.

4. Avviare tutti i microservizi

   Quindi avvia i servizi:

   bash

   bin/up
   

   Una volta che i servizi sono in esecuzione, apri http://localhost/launchpad per creare il primo account amministratore.

   Devi eseguire bin/up prima del comando bin/dev. In caso contrario potresti incontrare una serie di problemi di permessi.

Per impostazione predefinita i privilegi di amministratore non sono disponibili. Devi aggiungere quanto segue a develop/dev.env. Dopodiché potrai accedere al pannello di amministrazione.

ADMIN_PRIVILEGE_AVAILABLE=true

​

TeX Live

Per compilare un PDF è necessario creare un’immagine TeX Live che gestisca la compilazione all’interno di Docker:

docker build texlive -t texlive-full

Per compilare su un host macOS, potrebbe essere necessario sovrascrivere il percorso del socket Docker creando in questa directory un file .env contenente DOCKER_SOCKET_PATH=/var/run/docker.sock.raw

Puoi anche usare ayaka-notes/texlive-full; in tal caso puoi usare il tag base, che corrisponde alla versione minima di texlive.

​

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:

bin/dev

Questo avvierà tutti i servizi usando node --watch, che monitorerà automaticamente il codice e riavvierà i servizi quando necessario.

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:

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

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.

​

Debug

In modalità di 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 sulla macchina host per ciascun servizio:

Servizio	Porta
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

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

Nell’ambiente di sviluppo, Overleaf fornisce uno script bin/logs; tuttavia devi installare alcune dipendenze:

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

In alternativa, puoi eseguire direttamente:

docker compose logs -f [service name]

​

Altri strumenti

Una volta completato tutto, puoi consultare la sezione successiva per aggiungere alcuni strumenti di debug al tuo ambiente di sviluppo Overleaf.