Passer au contenu principal
Ayakaleaf Pro offre la possibilité d’exécuter les compilations dans un environnement isolé et sécurisé (sandbox), pour une sécurité de niveau entreprise. Pour cela, chaque projet est exécuté dans son propre environnement Docker sécurisé.

Sécurité renforcée

Les compilations isolées sont l’approche recommandée pour Ayakaleaf Pro, car de nombreux documents LaTeX nécessitent ou ont la possibilité d’exécuter des commandes shell arbitraires lors de la compilation du PDF. Avec les compilations isolées, chaque compilation s’exécute dans un conteneur Docker distinct aux capacités limitées, qui n’est partagé avec aucun autre utilisateur ni projet et n’a pas accès aux ressources extérieures telles que le réseau de l’hôte.
Si vous essayez d’exécuter Ayakaleaf Pro sans compilations isolées, la compilation s’exécute en parallèle des autres compilations simultanées dans le conteneur Docker principal, et les utilisateurs disposent d’un accès complet en lecture et en écriture aux ressources du conteneur sharelatex (système de fichiers, réseau et variables d’environnement) lors des compilations LaTeX.

Gestion simplifiée des packages

Pour éviter d’installer manuellement des packages, nous recommandons d’activer les compilations isolées. Il s’agit d’un paramètre configurable d’Ayakaleaf Pro qui offre à vos utilisateurs le même environnement TeX Live que sur overleaf.com, mais au sein de votre propre installation sur site. Les images TeX Live utilisées par les compilations isolées contiennent les packages et polices les plus populaires, testés avec les modèles de notre galerie, ce qui garantit une compatibilité maximale avec les projets sur site. L’activation des compilations isolées vous permet de configurer les versions de TeX Live parmi lesquelles les utilisateurs peuvent choisir dans leur projet, ainsi que de définir une version d’image TeX Live par défaut pour les nouveaux projets.
Si vous essayez d’exécuter Ayakaleaf Pro sans compilations isolées, votre instance utilisera par défaut une version de TeX Live avec le schéma basic pour les compilations. Cette version de base est légère et ne contient qu’un sous-ensemble très limité de packages LaTeX, ce qui entraînera très probablement des erreurs de packages manquants pour vos utilisateurs, en particulier s’ils essaient d’utiliser des modèles prédéfinis.
Comme Ayakaleaf Pro a été conçu pour fonctionner hors ligne, il n’existe aucun moyen automatisé d’intégrer les modèles de la galerie d’overleaf.com à votre installation sur site ; il est toutefois possible de le faire manuellement, modèle par modèle. Pour en savoir plus, consultez notre guide sur le transfert de modèles depuis overleaf.com : #transferring-templates-from-overleaf.com.
Les compilations isolées nécessitent que le conteneur sharelatex ait accès au socket Docker de la machine hôte (via un bind mount) afin de pouvoir gérer ces conteneurs de compilation frères.

Fonctionnement

Lorsque les compilations isolées sont activées, le socket Docker de la machine hôte est monté dans le conteneur sharelatex, afin que le service de compilation du conteneur puisse créer de nouveaux conteneurs Docker sur l’hôte. Ensuite, pour chaque exécution du compilateur dans chaque projet, le service de compilation LaTeX (CLSI) procède comme suit :
  • Il écrit les fichiers du projet à un emplacement situé dans OVERLEAF_DATA_PATH.
  • Il utilise le socket Docker monté pour créer un nouveau conteneur texlive pour cette compilation.
  • Le conteneur texlive lit les données du projet depuis l’emplacement situé sous OVERLEAF_DATA_PATH.
  • Le projet est compilé à l’intérieur du conteneur texlive.

Activer les compilations isolées

Pour les utilisateurs du Toolkit

Pour activer les compilations isolées (également appelées conteneurs frères, ou « sibling containers »), définissez les options de configuration suivantes dans overleaf-toolkit/config/overleaf.rc :
config/overleaf.rc
Pour les désactiver, définissez SIBLING_CONTAINERS_ENABLED=false et exécutez bin/up. Les compilations s’exécutent alors dans le conteneur sharelatex avec son TeX Live de base.

Pour les utilisateurs de Docker Compose

Configurer l’image TeX Live

Pour les utilisateurs en Chine continentale, vous pouvez récupérer les images depuis le miroir ghcr.nju.edu.cn pour accélérer le téléchargement, puis les étiqueter avec leur nom ghcr.io :
N’UTILISEZ PAS ghcr.nju.edu.cn dans les paramètres d’environnement de votre Toolkit : conservez-y les noms ghcr.io. Pour empêcher bin/up de récupérer à nouveau les images depuis ghcr.io, définissez SIBLING_CONTAINERS_PULL=false dans config/overleaf.rc. Pour maintenir les images à jour via le miroir, consultez Mettre à jour automatiquement les images TeX Live Full.
Ayakaleaf Pro utilise trois variables d’environnement pour déterminer quelles images TeX Live utiliser pour les compilations isolées :
  • TEX_LIVE_DOCKER_IMAGE (facultative) : l’image TeX Live utilisée par les nouveaux projets. Elle doit faire partie des images de ALL_TEX_LIVE_DOCKER_IMAGES. Si elle n’est pas définie, les nouveaux projets utilisent la première image de ALL_TEX_LIVE_DOCKER_IMAGES.
  • ALL_TEX_LIVE_DOCKER_IMAGE_NAMES (facultative) : une liste, séparée par des virgules, de noms pour les images, dans le même ordre, affichés dans les paramètres du compilateur. Si elle n’est pas définie, ou si elle est plus courte que la liste des images, une image est affichée par son tag, par exemple 2026.1.
  • ALL_TEX_LIVE_DOCKER_IMAGES (obligatoire) : une liste, séparée par des virgules, des images TeX Live à utiliser. Si l’Overleaf Toolkit est utilisé pour le déploiement, ces images seront téléchargées ou mises à jour. Pour ignorer le téléchargement, définissez SIBLING_CONTAINERS_PULL=false dans config/overleaf.rc.
Lorsque vous démarrez votre instance Ayakaleaf Pro avec la commande bin/up, le Toolkit récupère automatiquement toutes les images listées dans ALL_TEX_LIVE_DOCKER_IMAGES. Voici un exemple dans lequel TeX Live 2026 est utilisé par défaut pour les nouveaux projets, tandis que 2025 reste disponible pour les anciens projets.
La configuration suivante installe toutes les images Docker TeX Live complètes de 2025 à 2026. Nous recommandons de disposer d’au moins 64 Go d’espace de stockage libre avant d’utiliser cette configuration.
config/variables.env
Il est fortement recommandé de configurer au moins 2 images texlive-full. Pour en connaître la raison, consultez #known-issues

Images TeX Live disponibles

Voici une série d’images TeX Live spécialement optimisées pour Overleaf, qui peuvent être ajoutées à TEX_LIVE_DOCKER_IMAGE et ALL_TEX_LIVE_DOCKER_IMAGES :
  • ghcr.io/ayaka-notes/texlive-full:2026.1 (également disponible sous le tag latest)
  • ghcr.io/ayaka-notes/texlive-full:2025.1
  • ghcr.io/ayaka-notes/texlive-full:2024.1
  • ghcr.io/ayaka-notes/texlive-full:2023.1
  • ghcr.io/ayaka-notes/texlive-full:2022.1
  • ghcr.io/ayaka-notes/texlive-full:2021.1
  • ghcr.io/ayaka-notes/texlive-full:2020.1
Le format des tags d’images est strictement défini et doit être respecté (l’expression régulière ^[0-9]+.[0-9]+ s’applique : le premier nombre détermine l’année de TeX Live et le second la version du correctif).

Puis-je utiliser un autre registre d’images ?

Certains se demandent peut-être s’il est possible de remplacer ghcr.io par un autre site miroir, ou d’utiliser une autre image texlive provenant de Docker Hub.
Non, nous ne le recommandons pas, car la configuration est relativement complexe. Si vous téléchargez depuis un site miroir, vous pouvez renommer votre image en ghcr.io/ayaka-notes/texlive-full. Cependant, si vous souhaitez vraiment utiliser votre propre registre d’images, ajoutez :
config/variables.env
Vous devez ensuite vous assurer que toutes les images texlive se trouvent dans your-repo, par exemple :
  • hub.your.com/your-repo/texlive-full:2025.1
  • hub.your.com/your-repo/texlive-full:2024.1
Pour plus de détails, lisez le code source ci-dessous afin de comprendre comment nous interprétons vos variables d’environnement :
sandboxed-compiles/index.mjs

Synchronisation automatique des images TeX Live

Pour éviter de devoir mettre à jour manuellement votre instance avec bin/up à chaque fois, vous pouvez automatiser les mises à jour de vos images TeX Live. Consultez updating-tex-live-full-images-automatically.md.

Problèmes connus

Voici un cas réel rencontré par la communauté Overleaf :
Avec 6.0.1-ext-v3.3, j’ai les paramètres suivants dans variables.env :
Cela fonctionne bien avec texlive/texlive:latest-full. Cependant, j’ai récupéré une autre image texlive, danteev/texlive:2025-10-15, et modifié ces deux variables avec le nom de la nouvelle image, mais cela ne fonctionne pas :
Dans les journaux, je vois ceci :
On dirait que les paramètres mis à jour dans variables.env ne sont pas pris en compte. La compilation essaie toujours d’utiliser l’image texlive/texlive:latest-full, et non la nouvelle image. J’ai essayé de redémarrer, de supprimer les conteneurs et de relancer, mais le problème persiste. Une solution ?
En raison de certaines limitations techniques, si vous ne configurez qu’une seule image Docker TeXLive, par exemple texlive-fullA:latest
puis qu’après avoir exploité votre instance Overleaf pendant un certain temps, vous souhaitez remplacer l’image TeXLive par texlive-fullB:latest, vous constaterez que vos utilisateurs ne parviennent plus à compiler aucun projet.
En effet, le nom de l’image TeXLive-Full (pour la compilation isolée) de chaque projet est enregistré dans la base de données. Le nom de l’image n’est modifié dans la base de données que lorsque l’utilisateur change la version TeXLive de son projet, par exemple de 2024 à 2025. Lorsque CLSI compile un projet, il utilise directement le nom d’image de conteneur trouvé dans la base de données. Si vous ne fournissez qu’une seule image Docker, les utilisateurs ne pourront pas modifier l’image utilisée pour compiler leur projet. Dans ce cas, vous devrez écrire un script pour modifier manuellement l’image TeXLive de tous les projets des utilisateurs dans MongoDB.

Débogage et signalement

Exécutez la commande suivante pour consulter le journal de clsi depuis le Toolkit :
Si vous rencontrez des problèmes de compilation avec les images TeX Live, veuillez soumettre une issue ici : https://github.com/ayaka-notes/texlive-full/issues/new?template=texlive-image-bug.yml Pour nous aider à reproduire et à diagnostiquer le problème, il pourra vous être demandé d’envoyer votre projet sur Overleaf. Nous récupérerons alors le projet et lancerons des tests de compilation avec GitHub Action.

Questions/réponses

Réponse : Les conteneurs et les fichiers de compilation le sont, après un certain délai ; les images TeX Live ne le sont pas.
  • Les conteneurs de compilation (project-<project id>-<hash>) sont réutilisés d’une compilation à l’autre pour un même projet ; ils sont donc conservés après une compilation. Une vérification s’exécute toutes les heures et supprime ceux qui ont plus d’une heure et dont le projet n’a pas été compilé au cours de la dernière heure. Un conteneur disparaît généralement une à deux heures après la dernière compilation. Redémarrer Overleaf ne les supprime pas ; c’est la vérification horaire suivante qui s’en charge.
  • Les conteneurs de comptage de mots, de SyncTeX et de conversion sont supprimés dès qu’ils ont terminé.
  • Les fichiers de compilation (data/overleaf/data/compiles et output) sont supprimés lorsqu’un projet n’a pas été utilisé depuis un jour, avec une vérification toutes les 10 minutes. Lorsque l’espace disque devient insuffisant, ce délai est réduit progressivement, jusqu’à une demi-journée.
  • Les images TeX Live ne sont jamais supprimées, car chaque compilation en a besoin. Pour libérer de l’espace après avoir retiré une image de ALL_TEX_LIVE_DOCKER_IMAGES, supprimez-la avec docker image rm <image>.
Il n’est pas nécessaire de supprimer ces conteneurs manuellement.
Réponse : Non. Chaque conteneur de compilation monte uniquement le répertoire de compilation de son propre projet, sur /compile, et n’a pas d’accès réseau ; aucun paramètre ne permet d’y monter d’autres répertoires de l’hôte. Téléversez plutôt dans le projet les fichiers dont il a besoin.
Réponse : Oui. ghcr.io/ayaka-notes/texlive-basic:<year>.1 (de 2020.1 à 2026.1) contient le schéma basic de TeX Live ainsi que quelques paquets tels que latexmk, xetex et fontspec, sans l’ensemble complet des polices. Elle est bien plus légère que texlive-full, mais les projets qui utilisent d’autres paquets obtiennent des erreurs de paquets manquants. Pour TeX Live 2025 basic :
config/variables.env
ghcr.io/ayaka-notes/texlive-full:base n’est pas une image basic : elle ne contient pas TeX Live et ne peut pas compiler.
Réponse : L’éditeur ne l’affiche pas, et le journal clsi ne l’enregistre qu’au niveau debug. Chaque requête de compilation la renvoie toutefois : ouvrez les outils de développement du navigateur, allez dans l’onglet Network (Réseau), relancez la compilation et sélectionnez la requête compile. Sa réponse JSON contient timings en millisecondes, où compileE2E correspond à la compilation complète dans le service de compilation et compile à l’exécution LaTeX elle-même.
Dernière modification le 13 novembre 2026