Compilations isolées (Sandboxed Compiles)

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 de Server 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

SERVER_PRO=true
SIBLING_CONTAINERS_ENABLED=true

​

Pour les utilisateurs de Docker Compose

À partir d’Overleaf CE/Server Pro 5.0.3, les variables d’environnement ont été renommées de SHARELATEX_* en OVERLEAF_*.

Si vous utilisez une version 4.x (ou antérieure), assurez-vous que les variables portent le préfixe approprié (par exemple SHARELATEX_MONGO_URL au lieu de OVERLEAF_MONGO_URL).

version: '2'
services:
    sharelatex:
        #...
        volumes:
            - /data/overleaf_data:/var/lib/overleaf
            - /var/run/docker.sock:/var/run/docker.sock
        environment:
            #...
            DOCKER_RUNNER: "true"
            SANDBOXED_COMPILES: "true"
            SANDBOXED_COMPILES_HOST_DIR: "/data/overleaf_data/data/compiles"
            #...
        #...

​

Configurer l’image TeX Live

Pour les utilisateurs en Chine continentale, vous pouvez remplacer ghcr.io par ghcr.nju.edu.cn pour accélérer le téléchargement. Mais N’UTILISEZ PAS ghcr.nju.edu.cn directement dans les paramètres d’environnement de votre Toolkit. Vous devez conserver ghcr.io comme unique choix.

Ayakaleaf Pro utilise trois variables d’environnement pour déterminer quelles images TeX Live utiliser pour les compilations isolées :

• TEX_LIVE_DOCKER_IMAGE (obligatoire) : l’image TeX Live par défaut utilisée pour compiler les nouveaux projets. Cette image doit figurer dans ALL_TEX_LIVE_DOCKER_IMAGES.
• ALL_TEX_LIVE_DOCKER_IMAGE_NAMES (obligatoire) : une liste, séparée par des virgules, de noms conviviaux pour les images, utilisés pour les options de l’interface.
• 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.

Installation minimale

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

ALL_TEX_LIVE_DOCKER_IMAGES=ghcr.io/ayaka-notes/texlive-full:2026.1, ghcr.io/ayaka-notes/texlive-full:2025.1
ALL_TEX_LIVE_DOCKER_IMAGE_NAMES=Texlive 2026, Texlive 2025
TEX_LIVE_DOCKER_IMAGE=ghcr.io/ayaka-notes/texlive-full:2026.1

Installation complète

La configuration suivante installe toutes les images Docker TeX Live complètes de 2020 à 2026. Nous recommandons de disposer d’au moins 150 Go d’espace de stockage libre avant d’utiliser cette configuration.

config/variables.env

ALL_TEX_LIVE_DOCKER_IMAGES=ghcr.io/ayaka-notes/texlive-full:2026.1,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
ALL_TEX_LIVE_DOCKER_IMAGE_NAMES=Texlive 2026,Texlive 2025,Texlive 2024,Texlive 2023,Texlive 2022,Texlive 2021,Texlive 2020
TEX_LIVE_DOCKER_IMAGE=ghcr.io/ayaka-notes/texlive-full:2026.1

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

IMAGE_ROOT=hub.your.com/your-repo

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

if (process.env.SANDBOXED_COMPILES === 'true') {
  // Set default image root if not provided
  let imageRootPath = process.env.IMAGE_ROOT || "ghcr.io/ayaka-notes";
  // Export imageRoot to Settings
  Settings.imageRoot = imageRootPath

  // allowedImageNames should be:
  // [
  //  { imageName: "texlive-2023:latest", imageDesc: "TeX Live 2023" },
  //  { imageName: "texlive-2022:latest", imageDesc: "TeX Live 2022" },
  // ]
  Settings.allowedImageNames = parseTextExtensions(process.env.ALL_TEX_LIVE_DOCKER_IMAGES)
    .map((texImage, index) => ({
      imageName: texImage.split("/")[texImage.split("/").length - 1],
      imageDesc: parseTextExtensions(process.env.ALL_TEX_LIVE_DOCKER_IMAGE_NAMES)[index]
        || texImage.split(':')[1],
    }))
  
  // In the end, imageName will be put together with imageRoot to form the full image path
  // The full name will be like: ghcr.io/ayaka-notes/texlive-2023:latest

  // Set default image name if not provided
  if(!process.env.TEX_LIVE_DOCKER_IMAGE) {
    process.env.TEX_LIVE_DOCKER_IMAGE = imageRootPath + "/" + Settings.allowedImageNames[0].imageName
  }

  // Export currentImageName to Settings
  // This is the new created projects' image name
  Settings.currentImageName = process.env.TEX_LIVE_DOCKER_IMAGE
}

​

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 :

TEX_LIVE_DOCKER_IMAGE=texlive/texlive:latest-full
ALL_TEX_LIVE_DOCKER_IMAGES=texlive/texlive:latest-full

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 :

TEX_LIVE_DOCKER_IMAGE=danteev/texlive:2025-10-15
ALL_TEX_LIVE_DOCKER_IMAGES=danteev/texlive:2025-10-15

Dans les journaux, je vois ceci :

{"name":"clsi","level":50,"err":{"message":"(HTTP code 404) no such container - No such image: texlive/texlive:latest-full ","name":"Error","stack":"Error: (HTTP code 404) no such container - No such image: texlive/texlive:latest-full ... 

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

ALL_TEX_LIVE_DOCKER_IMAGES=texlive/texliveA:latest-full
ALL_TEX_LIVE_DOCKER_IMAGE_NAMES=TeXLiveA
TEX_LIVE_DOCKER_IMAGE=texlive/texliveA:latest-full

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.

ALL_TEX_LIVE_DOCKER_IMAGES=texlive/texliveA:latest-full
ALL_TEX_LIVE_DOCKER_IMAGE_NAMES=TeXLiveA
TEX_LIVE_DOCKER_IMAGE=texlive/texliveA:latest-full

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 :

bin/logs clsi

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.