Passer au contenu principal

Prérequis

Overleaf est un projet open source typique reposant sur une architecture de microservices, dont tous les services s’exécutent dans Docker. 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

Ici, nous utilisons Ayakaleaf Pro pour montrer comment mettre en place un environnement de développement Overleaf. Toutes les commandes ci-dessous s’exécutent dans le répertoire develop, sauf indication contraire.
1

Récupérer le code source

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

Synchroniser yarn.lock

Le dépôt utilise Yarn 4 (packageManager dans le package.json racine), et son yarn.lock peut être désynchronisé des fichiers package.json. Synchronisez-le après le premier clonage et après toute modification d’un package.json :
bash
bin/sync exécute yarn install --mode=update-lockfile dans un conteneur node:24.18.1, vous n’avez donc pas besoin de Node.js sur l’hôte. Ne commitez pas le yarn.lock modifié.
3

Construire l'image de développement

Construisez les services :
bash
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

Appliquer les traductions

Les modules d’Ayakaleaf Pro conservent leurs traductions dans services/web/locales/locales_patches/, que les fichiers de locales commités ne contiennent pas. Appliquez-les une fois avant le premier démarrage, sinon les pages de ces modules affichent des clés comme about_to_permanently_delete_accounts au lieu du texte :
bash
Il nécessite jq sur l’hôte. Relancez-le après avoir ajouté une traduction ou changé de branche, voir Mettre à jour les traductions i18n.
5

Démarrer tous les microservices

Démarrez ensuite les services :
bash
Une fois les services lancés, ouvrez http://localhost/launchpad pour créer le premier compte administrateur. Ajoutez le port si vous avez modifié OVERLEAF_PORT (voir ci-dessous).
LDAP est activé par défaut (LDAP_ENABLED=true dans dev.rc). Le launchpad affiche alors le formulaire d’administrateur LDAP : il ne demande qu’une adresse e-mail, et cet administrateur se connecte ensuite via LDAP, par exemple en tant que professor / professor (professor@planetexpress.com). Les utilisateurs de test sont listés dans develop/authentication/README.md. Définissez LDAP_ENABLED=false et SAML_ENABLED=false pour créer plutôt un administrateur local avec un mot de passe.
develop/dev.env définit déjà ADMIN_PRIVILEGE_AVAILABLE=true, donc les administrateurs peuvent ouvrir le panneau d’administration sans configuration supplémentaire.

Configuration (dev.rc)

develop/dev.rc, à côté de dev.env, contient les interrupteurs de l’environnement de développement, comme overleaf.rc dans l’Overleaf Toolkit. Modifiez une valeur et relancez bin/dev pour l’appliquer ; une fonctionnalité désactivée arrête aussi ses conteneurs. Chaque fonctionnalité garde son docker-compose.yml et ses autres fichiers dans son propre dossier : authentication/ldap, authentication/saml, mail, s3, hoppscotch et grafana. Une fonctionnalité qui a besoin d’un réglage de web sans variable d’environnement monte un fichier dans /etc/overleaf/settings.d/, et develop/settings.dev-env.cjs les fusionne tous. Tous les scripts bin/* passent par bin/docker-compose, qui ajoute les fichiers des fonctionnalités activées. Appelez bin/docker-compose au lieu de docker compose quand vous avez besoin vous-même d’une commande compose.
Les volumes locaux et RustFS sont des stockages séparés : un projet créé avec S3_ENABLED=true n’a ni historique ni fichiers binaires après le passage à false, et inversement. Pour copier dans RustFS les fichiers d’un environnement qui fonctionnait avant l’existence de S3_ENABLED, suivez « Moving existing data into RustFS » dans develop/README.md.

Ports

Le site, la console RustFS et Hoppscotch écoutent sur 127.0.0.1 de l’hôte ; sur une machine distante, redirigez d’abord leurs ports, par exemple ssh -L 9001:localhost:9001 <host>. Le site utilise OVERLEAF_PORT de dev.rc, ajoutez donc le port aux adresses ci-dessous si vous l’avez modifié. Mailpit, Grafana, Mongo Express et RedisInsight sont servis par le site sur leurs propres chemins, via webpack-dev-server, ils n’ont donc pas besoin de port propre. Une fois connecté, le menu Dev tools de la barre de navigation du site y renvoie ; une page dont la fonctionnalité est désactivée dans dev.rc est omise. Installer les outils de développement montre ce que fait chacun d’eux. L’API S3 (port 9000) et SMTP (port 1025) ne sont accessibles qu’à l’intérieur du réseau Docker. Mongo (27017), Redis (6379), Mongo Express (8081), RedisInsight (5540) et git-bridge (8000) ne sont publiés que sur 127.0.0.1 de l’hôte.

TeX Live

Les compilations en sandbox sont activées par défaut : develop/dev.env définit SANDBOXED_COMPILES=true et les images ghcr.io/ayaka-notes/texlive-full:2026.1 et ghcr.io/ayaka-notes/texlive-full:2025.1. clsi ne récupère pas les images lui-même, alors récupérez-les une fois :
Voir Configurer les compilations en sandbox pour les détails.
Un projet créé alors que SANDBOXED_COMPILES était désactivé n’a pas d’image TeX Live. Il compile toujours avec l’image par défaut, mais le passage entre le code et le PDF échoue avec « That didn’t work. Recompile and try again. » Attribuez une fois à ces projets l’image de TEX_LIVE_DOCKER_IMAGE ; sans --commit, le script affiche seulement ce qu’il changerait :
dev.env active aussi les conversions Pandoc avec PANDOC_IMAGE=overleaf-pandoc:local. Construisez cette image une fois, depuis la racine du dépôt :
Pour compiler sur un hôte macOS, vous devrez peut-être remplacer le chemin du socket Docker en créant un fichier .env dans le répertoire develop, contenant DOCKER_SOCKET_PATH=/var/run/docker.sock.raw

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 :
Cela démarre tous les services avec node --watch, qui surveille automatiquement le code et redémarre les services si nécessaire. Relancez-le après avoir modifié dev.rc. 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 :
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. Après avoir ajouté une traduction ou changé de branche, exécutez bin/i18n, voir Mettre à jour les traductions i18n.

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 Dev Tools de Chrome ou celui intégré à un IDE. Le tableau suivant indique le port exposé sur 127.0.0.1 de la machine hôte pour chaque service : 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

Le script bin/logs suit les logs et les formate avec bunyan. Il a aussi besoin de ggrep, le nom de GNU grep lorsqu’il est installé avec Homebrew sur macOS ; Ubuntu n’a pas de commande ggrep.
Vous pouvez aussi exécuter directement :
Utilisez bin/docker-compose plutôt que docker compose, afin que les services des fonctionnalités de dev.rc (mailpit, rustfs, ldap, saml, hoppscotch, et grafana avec Prometheus, Loki et les exporteurs) soient aussi trouvés. Avec GRAFANA_ENABLED=true, les logs de chaque conteneur sont aussi dans Grafana, où ils peuvent être filtrés par service, niveau et texte, voir Installer les outils de développement.

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.
Dernière modification le 20 novembre 2026