Ayakaleaf Pro prend en charge la mise à l’échelle horizontale. Nous avons testé et vérifié qu’il fonctionne correctement avec plusieurs réplicas.
Prérequis

Stockage de données externe et centralisé
Le stockage des données dans Ayakaleaf Pro peut être réparti en quatre magasins de données :-
MongoDB
- La plupart des données sont persistées dans MongoDB.
- Nous prenons en charge une instance locale ou une instance externe, comme MongoDB Atlas (un service MongoDB entièrement géré qui s’exécute au sein de l’infrastructure AWS).
-
Redis
- Redis stocke des données temporaires, comme les mises à jour de documents en attente avant leur écriture dans MongoDB.
- Redis sert à communiquer les mises à jour de documents entre les différents services et à notifier l’éditeur des changements d’état d’un projet donné.
- Redis sert à stocker les sessions utilisateur.
- Nous prenons en charge une instance locale ou une instance externe.
-
Fichiers de projet et fichiers d’historique
- Les fichiers de projet non modifiables sont stockés en dehors de MongoDB. Le système d’historique des projets stocke également l’historique en dehors de MongoDB.
- Pour les petites instances uniques, nous prenons en charge un système de fichiers local (qui peut reposer sur un SSD local, NFS ou EBS) ou un système de stockage de données compatible S3.
-
Pour la mise à l’échelle horizontale, nous prenons en charge uniquement les systèmes de stockage de données compatibles S3.
-
Fichiers éphémères
- Les compilations LaTeX doivent s’exécuter sur des disques locaux rapides pour des performances optimales. Le résultat de la compilation n’a pas besoin d’être persisté ni sauvegardé.
- La mise en mémoire tampon des nouveaux fichiers téléversés et la création des archives zip de projets bénéficient également d’un disque local.
Nous vous conseillons vivement d’utiliser un disque local. L’utilisation de tout type de disque réseau (comme NFS ou EBS) peut entraîner des erreurs de compilation inattendues et d’autres problèmes de performances.
Git-bridge
Les dépôts git sont stockés localement sur disque. Aucune option de réplication n’est disponible. Git-bridge doit être exécuté en tant que singleton. Pour des performances optimales, nous conseillons d’utiliser un disque local pour les données de git-bridge. Le disque de données de git-bridge doit être sauvegardé régulièrement. Pour le stockage des données avec mise à l’échelle horizontale, vous avez besoin de :- une instance MongoDB centrale accessible depuis toutes les instances Ayakaleaf Pro
- une instance Redis centrale accessible depuis toutes les instances Ayakaleaf Pro
- un backend de stockage central compatible S3 pour les fichiers de projet et d’historique
- un disque local sur chaque instance pour les fichiers éphémères
- un disque local sur l’instance qui héberge le conteneur git-bridge pour les données de git-bridge
Exigences pour le répartiteur de charge
-
Routage persistant, par exemple à l’aide d’un cookie
Cette exigence découle des composants suivants :
- La fonctionnalité d’édition en temps réel d’Ayakaleaf Pro utilise des WebSockets avec un repli sur le polling XHR. Chaque session d’édition possède un état local côté serveur, et les requêtes d’une session d’édition donnée doivent toujours être routées vers la même instance Ayakaleaf Pro. La fonctionnalité de collaboration utilise le Pub/Sub de Redis pour partager les mises à jour entre plusieurs instances Ayakaleaf Pro.
- La compilation LaTeX conserve localement le résultat et le cache de compilation pour optimiser les performances. Après l’envoi d’une requête de compilation à une instance Ayakaleaf Pro, les requêtes de téléchargement du PDF/du journal qui suivent doivent être routées vers la même instance Ayakaleaf Pro.
- Délais d’expiration des requêtes longs pour permettre la compilation de documents LaTeX volumineux
- Prise en charge des WebSockets pour des performances optimales
- Taille de charge utile POST de 50 Mo
-
Le délai keep-alive doit être inférieur au délai keep-alive d’Ayakaleaf Pro
Le délai keep-alive d’Ayakaleaf Pro peut être configuré à l’aide de la variable d’environnement
NGINX_KEEPALIVE_TIMEOUT. La valeur par défaut est de 65 s. Avec la valeur par défaut, un délai keep-alive de 60 s dans le répartiteur de charge fonctionne. AvecNGINX_KEEPALIVE_TIMEOUT=120, le répartiteur de charge pourrait utiliser 115 s. -
Adresses IP des clients
Définissez l’en-tête de requête
X-Forwarded-Forsur l’adresse IP du client. -
Lors de la terminaison SSL
Le répartiteur de charge doit ajouter l’en-tête de requête
X-Forwarded-Proto: https.
Exemple de configuration HAProxy
Exemple de configuration HAProxy
Configuration d’Ayakaleaf Pro
Secrets Les instances Ayakaleaf Pro doivent partager les mêmes secrets :WEB_API_PASSWORD(authentification de l’API web)STAGING_PASSWORDetV1_HISTORY_PASSWORDavec la même valeur (authentification de l’historique)CRYPTO_RANDOM(pour le cookie de session)OT_JWT_AUTH_KEY(authentification de l’historique)OVERLEAF_INVITE_TOKEN_SECRET(jetons de partage par lien, obligatoire : sans lui, Ayakaleaf Pro refuse de démarrer)
/dev/urandom (256 bits aléatoires).
OVERLEAF_MONGO_URL vers l’instance MongoDB centrale.
Redis
Faites pointer OVERLEAF_REDIS_HOST et REDIS_HOST vers l’instance Redis centrale.
Stockage compatible S3 pour les fichiers de projet et d’historique
Consultez la documentation sur le stockage compatible S3 pour plus de détails.
Fichiers éphémères
Le montage par défaut (bind-mount) d’un SSD local sur /var/lib/overleaf suffit. Veillez à faire pointer SANDBOXED_COMPILES_HOST_DIR vers le point de montage sur l’hôte.
Nous vous conseillons vivement d’utiliser un disque local. L’utilisation de tout type de disque réseau (comme NFS ou EBS) peut entraîner des erreurs de compilation inattendues et d’autres problèmes de performances.
- Définissez
OVERLEAF_TRUSTED_PROXY_IPSsurloopbacksuivi des adresses IP des répartiteurs de charge, par exempleloopback,198.18.0.1, pour obtenir les adresses IP exactes des clients. Plusieurs adresses IP ou CIDR peuvent être indiqués, séparés par une virgule.
-
Définissez
GIT_BRIDGE_ENABLEDsur'true' -
Définissez
GIT_BRIDGE_HOSTsur<git-bridge container name>, par exemplegit-bridge -
Définissez
GIT_BRIDGE_PORTsur8000 -
Définissez
V1_HISTORY_URLsurhttp://<server-pro sibling container name>:3100/api. Remarque : ceci n’est nécessaire que sur le conteneur voisin du conteneur git-bridge. Les autres instances peuvent utiliser une URL localhost, qui est la valeur par défaut.
- Définissez
GIT_BRIDGE_API_BASE_URLsurhttp://<server-pro sibling container name>/api/v0, par exemplehttp://server-pro-ha-1/api/v0 - Définissez
GIT_BRIDGE_OAUTH2_SERVERsurhttp://<server-pro sibling container name>, par exemplehttp://server-pro-ha-1 - Définissez
GIT_BRIDGE_POSTBACK_BASE_URLsurhttp://<git-bridge container name>:8000, par exemplehttp://git-bridge:8000 - Définissez
GIT_BRIDGE_ROOT_DIRsur le disque de données git-bridge monté, par exemple/data/git-bridge
Exemple de configuration docker-compose.yml
Exemple de configuration docker-compose.yml
La configuration suivante présente une installation autonome. Pour que la démo fonctionne, vous devez fournir une clé et un certificat SSL valides et ajuster
OVERLEAF_SITE_URL. Pour une installation réelle, vous devez remplacer les secrets factices par de vrais secrets, comme indiqué dans les commentaires. Pour une installation réelle, vous devez également déplacer chaque conteneur sur des nœuds dédiés et adapter les adresses IP à la configuration de votre réseau local.Les compilations s’exécutent dans des conteneurs TeX Live à côté de chaque instance Ayakaleaf Pro. Récupérez d’abord l’image TeX Live sur chaque hôte Ayakaleaf Pro, par exemple docker pull ghcr.io/ayaka-notes/texlive-full:2026.1.Matériel
Nous recommandons d’utiliser les mêmes spécifications matérielles pour toutes les instances Ayakaleaf Pro participant à la mise à l’échelle horizontale. Les recommandations générales sur les spécifications matérielles des instances Ayakaleaf Pro s’appliquent.Mettre à niveau Ayakaleaf Pro
Dans le cadre du processus de mise à niveau, Ayakaleaf Pro exécute automatiquement des migrations de base de données. Ces migrations ne sont pas conçues pour être exécutées en parallèle depuis plusieurs instances. Les migrations doivent être terminées avant le démarrage de l’application web proprement dite. Vous pouvez soit rechercher l’entréeFinished migrations dans les journaux, soit attendre que l’application accepte du trafic.
La procédure de mise à niveau se déroule comme suit :
- Planifiez une fenêtre de maintenance
- Arrêtez toutes les instances d’Ayakaleaf Pro
- Effectuez une sauvegarde cohérente comme décrit dans la documentation
- Démarrez une seule instance d’Ayakaleaf Pro avec la nouvelle version
- Vérifiez que la nouvelle instance fonctionne comme prévu
- Démarrez les autres instances avec la nouvelle version

