Configurer l'environnement de développement (local)

Configurez votre environnement de développement sur votre serveur local ou votre ordinateur de bureau.

​

Prérequis

Overleaf est un projet open source typique reposant sur une architecture de microservices, dont tous les services s’exécutent dans Docker.

• Le code source officiel de la Community Edition est disponible sur GitHub Overleaf Official.
• Le code source d’Overleaf-CEP est disponible sur GitHub Yu-i-i/Overleaf.
• Overleaf Pro Edition est disponible sur GitHub Ayaka-notes/overleaf-pro.

Pour mettre en place un environnement de développement Overleaf, vous aurez besoin d’un serveur puissant ; une configuration d’au moins 8 cœurs et 16 Go de RAM est recommandée, car vous devrez exécuter plus de 20 conteneurs simultanément.

Les serveurs dotés de 8 cœurs CPU ou plus étant généralement coûteux, nous vous recommandons vivement d’utiliser votre ordinateur local pour le développement.

Par ailleurs, en tant que développeur, vous devriez déjà être familiarisé avec l’installation de Docker. Nous vous conseillons fortement d’utiliser une version Ubuntu LTS récente et stable (par exemple Ubuntu 24.04 en 2025–2026) ainsi que la dernière version de Docker pour le développement, afin de réduire le risque de rencontrer des erreurs inattendues.

En résumé, vous aurez besoin de :

• Un serveur ou un ordinateur de bureau puissant pour développer
• Une version Ubuntu LTS récente et stable (par exemple Ubuntu 24.04)
• Un environnement Docker et Git

​

Tutoriel de configuration

Nous utiliserons ici overleaf-cep comme exemple pour montrer comment configurer un environnement de développement Overleaf.

1. Récupérer le code source

   Tout d’abord, clonons le dépôt :

   bash

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

   Overleaf étant développé dans un dépôt interne, le fichier package-lock.json risque fort d’être désynchronisé en raison de certains aléas de développement. Nous devons exécuter la commande suivante pour le synchroniser (si vous disposez d’un environnement Node.js local) :

   bash

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

   Si Node.js n’est pas installé, pas d’inquiétude : vous pouvez utiliser directement docker pour exécuter la même commande. Exécutez-la depuis la racine du dépôt Overleaf :

   bash

   docker run --rm \
     -v "$(pwd)":/workspace \
     -w /workspace \
     node:22.18.0 \
     npm install --package-lock-only --ignore-scripts
   
3. Construire l'image de développement

   Overleaf fournit un répertoire dédié /develop contenant les scripts de développement. Il suffit de construire les services :

   bash

   cd ./develop
   bin/build
   

   Si Docker manque de RAM lors de la construction parallèle des services, créez un fichier .env dans ce répertoire contenant COMPOSE_PARALLEL_LIMIT=1.

4. Démarrer tous les microservices

   Démarrez ensuite les services :

   bash

   bin/up
   

   Une fois les services lancés, ouvrez http://localhost/launchpad pour créer le premier compte administrateur.

   Vous devez exécuter bin/up avant la commande bin/dev. Sinon, vous risquez de rencontrer une série de problèmes de permissions.

Par défaut, les privilèges d’administrateur ne sont pas disponibles. Vous devez ajouter la ligne suivante à develop/dev.env. Vous aurez ensuite accès au panneau d’administration.

ADMIN_PRIVILEGE_AVAILABLE=true

​

TeX Live

La compilation d’un PDF nécessite de construire une image TeX Live pour gérer la compilation dans Docker :

docker build texlive -t texlive-full

Pour compiler sur un hôte macOS, vous devrez peut-être remplacer le chemin du socket Docker en créant un fichier .env dans ce répertoire, contenant DOCKER_SOCKET_PATH=/var/run/docker.sock.raw

Vous pouvez également utiliser ayaka-notes/texlive-full, avec le tag base, qui correspond à la version minimale de TeX Live.

​

Développement

Pour éviter d’exécuter bin/build && bin/up après chaque modification du code, vous pouvez exécuter Overleaf Community Edition en mode développement, dans lequel les services se mettent automatiquement à jour lors des modifications du code.

Pour cela, utilisez le script bin/dev fourni :

bin/dev

Cela démarre tous les services avec node --watch, qui surveille automatiquement le code et redémarre les services si nécessaire.

Pour améliorer les performances, vous pouvez ne démarrer qu’une partie des services en mode développement en passant une liste séparée par des espaces au script bin/dev :

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

Démarrer le service web en mode développement ne mettra à jour le service web que lors des modifications du code backend. Pour mettre également à jour automatiquement le code frontend, veillez à démarrer aussi le service webpack en mode développement.

Si aucun service n’est indiqué, tous les services démarrent en mode développement.

​

Débogage

En mode développement, la plupart des services exposent un port de débogage auquel vous pouvez attacher un débogueur, comme l’inspecteur des Chrome Dev Tools ou celui intégré à un IDE. Le tableau suivant indique le port exposé sur la machine hôte pour chaque service :

Service	Port
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

Pour vous attacher à un service via le débogage à distance de Chrome, rendez-vous sur chrome://inspect/ et assurez-vous que l’option Discover network targets est cochée. Cliquez ensuite sur Configure… et ajoutez une entrée localhost:[service port] pour chacun des services auxquels vous souhaitez attacher un débogueur.

Après l’ajout d’une entrée, le service apparaît comme Remote Target, que vous pouvez inspecter et déboguer.

​

Journalisation

Dans l’environnement de développement, Overleaf fournit un script bin/logs ; vous devez toutefois installer une dépendance :

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

Vous pouvez aussi exécuter directement :

docker compose logs -f [service name]

​

Autres outils

Une fois tout cela terminé, vous pouvez consulter la section suivante pour ajouter des outils de débogage à votre environnement de développement Overleaf.