Configuration Docker / CI

Vous n'êtes pas obligé d'installer TeX sur votre propre ordinateur : une image Docker regroupe l'intégralité de l'environnement de composition, vous pouvez donc transformer .tex en PDF avec la même procédure n'importe où. Cela s'associe naturellement à CI (intégration continue) tel que GitHub Actions : chaque poussée peut créer automatiquement le PDF et l'enregistrer en tant qu'artefact. Cette page couvre l'image texlive/texlive populaire et comment rendre les builds TeX automatisées et reproductibles dans CI.

Pourquoi composer dans un conteneur

Si une distribution est « l'environnement TeX lui-même » (voir Distributions), une image Docker est la boîte qui expédie cet environnement gelé avec son OS. À l'intérieur de la boîte se trouvent une version spécifique de TeX Live, les moteurs, les packages et les polices. Ainsi, que votre hôte soit Windows ou macOS ou un serveur CI, ouvrir la même boîte vous donne le même environnement. Son plus gros gain est d'éviter l'inadéquation « fonctionne sur ma machine mais échoue sur la configuration de mon collègue ou dans CI ».

Les conteneurs et les installations de bureau ne s’excluent pas mutuellement. Une division courante consiste à écrire quotidiennement avec votre éditeur et un TeX local (voir Installation de bureau) et à transmettre uniquement la version finale, la collaboration ou la publication à un conteneur ou à CI. Le mot clé est reproductibilité : épinglez la version avec une balise, et la reconstruction six mois plus tard donne toujours le même PDF.

L'image texlive/texlive

Une image largement utilisée pour TeX Live est texlive/texlive, publiée en tant qu'image Island of TeX sur Docker Hub (docker.io/texlive/texlive) et GitLab (registry.gitlab.com/islandoftex/images/texlive). À l'intérieur se trouve TeX Live (la version stable en 2026 est TeX Live 2026), avec des moteurs, des packages et des outils tels que latexmk. Les versions hebdomadaires suivent les mises à jour de CTAN.

Les balises vous permettent de choisir un schéma (niveau de taille). Il y en a cinq – minimal, basic, small, medium, full – et latest correspond au plus grand, full (tous les packages). Vous pouvez les combiner avec l'inclusion de la documentation et des sources : la balise nue n'a ni l'une ni l'autre, -doc ajoute des documents, -src ajoute des sources et -doc-src ajoute les deux. Les documents et les sources sont volumineux ; CI en a rarement besoin, donc un schéma simple ou plus petit s'exécute plus rapidement. Il existe également des variantes -context pour les utilisateurs de ConTeXt.

L'utilisation est simple : docker run avec le répertoire actuel monté dans le conteneur, puis exécutez latexmk à l'intérieur. Voici une version unique d'un main.tex local. --rm supprime ensuite le conteneur, -v "$PWD":/work mappe votre emplacement actuel à /work et -w /work en fait le répertoire de travail. Le PDF résultant revient directement dans votre dossier.

docker run --rm -v "$PWD":/work -w /work texlive/texlive latexmk -pdf main.tex

Pour un document japonais, exécutez un moteur spécifique au lieu du simple latexmk — par exemple. latexmk -lualatex main.tex pour LuaLaTeX, ou latexmk main.tex pour l'itinéraire upLaTeX + dvipdfmx une fois que vous avez fourni un .latexmkrc. Le montage fonctionne de la même manière : les entrées et les sorties se trouvent dans votre répertoire local.

Gelez l'environnement pour plus de reproductibilité. latest passe à un nouvel instantané TeX Live chaque semaine, ne le laissez donc pas comme valeur par défaut pour la version finale d'un article ou le matériel pédagogique publié. Choisissez d’abord l’année de sortie et la version de TeX Live, et utilisez une balise de version historique le cas échéant. Comme le note le hub Docker, même les images historiques peuvent être reconstruites lorsque l'image OS sous-jacente est mise à jour. Si vous avez besoin exactement du même conteneur bit par bit plus tard, épinglez un résumé d'image ainsi qu'une balise, ou enregistrez l'image connue dans votre propre registre.

Constructions automatisées avec GitHub Actions

Pour un référentiel GitHub, GitHub Actions peut compiler votre .tex à chaque push. Le choix populaire est xu-cheng/latex-action@v4. Il utilise un conteneur contenant TeX Live et appelle latexmk par défaut, le flux de travail ne comporte donc que quelques lignes. Vous trouverez ci-dessous un exemple minimal qui construit main.tex à la racine du dépôt à chaque poussée et enregistre le PDF en tant qu'artefact de construction.

name: Build LaTeX document
on: [push]

jobs:
  build_latex:
    runs-on: ubuntu-latest
    steps:
      - name: Check out the repository
        uses: actions/checkout@v6

      - name: Compile the document
        uses: xu-cheng/latex-action@v4
        with:
          root_file: main.tex

      - name: Upload the PDF
        uses: actions/upload-artifact@v6
        with:
          name: PDF
          path: main.pdf

Lors du push, un conteneur démarre sur le coureur de GitHub et le main.tex nommé dans root_file est compilé par latexmk. Les arguments par défaut de latexmk sont -pdf -file-line-error -halt-on-error -interaction=nonstopmode — un paramètre compatible avec CI qui s'arrête en cas d'erreur et s'exécute jusqu'à la fin sans invite. Le PDF terminé peut être téléchargé en tant qu'artefact à partir de la page d'exécution des actions.

Connaître les principales entrées (with:). root_file est la cible de build (globs autorisés). Changez de moteur avec latexmk_use_lualatex: true pour LuaLaTeX ou latexmk_use_xelatex: true pour XeLaTeX (LuaLaTeX est la voie la plus simple pour les japonais). texlive_version sélectionne 2020–2026 ou latest, vous pouvez donc épingler par année pour plus de reproductibilité. os est le système d'exploitation de base – la valeur par défaut est le alpine léger, avec debian disponible lorsque vous en avez besoin. Pour les packages qui utilisent \write18, définissez latexmk_shell_escape: true.

Pour rendre les builds plus rapides, vous pouvez mettre en cache des éléments qui autrement seraient réinstallés ou re-téléchargés à chaque exécution via actions/cache. Cela dit, latex-action regroupe déjà un TeX Live substantiel, de sorte que la plupart des projets s'exécutent à une vitesse pratique dès la sortie de la boîte. Commencez par la configuration minimale et optimisez-la uniquement lorsque la lenteur devient réellement un problème.

GitLab CI adopte la même approche

GitLab CI suit la même idée, sauf que vous nommez l'image directement au lieu d'utiliser une action dédiée. Définissez le image: du travail sur texlive/texlive:latest (ou une balise épinglée par date), exécutez latexmk -pdf main.tex dans script: et enregistrez le PDF via artifacts:. Comme il repose sur la même image, vous obtenez le même résultat de composition que GitHub Actions.

build:
  image: texlive/texlive:latest
  script:
    - latexmk -pdf main.tex
  artifacts:
    paths:
      - main.pdf

L'essence est la même sur n'importe quel service : à l'intérieur d'une image épinglée par version, laissez latexmk piloter une version unique et collectez le PDF résultant en tant qu'artefact. Il s'agit du modèle partagé pour exécuter TeX dans un conteneur ou CI. Les mécanismes des builds automatisés quotidiens sont explorés plus en détail sur les pages « CI » et « Builds automatisés ».

Préparez le manuscrit pour CI

Un manuscrit qui se comporte bien dans CI ne dépend pas des paramètres de votre éditeur. Le fichier racine, le moteur, les commandes d'assistance et l'emplacement de sortie sont enregistrés dans le référentiel. Pour le travail japonais, placez un .latexmkrc à côté de main.tex et choisissez explicitement upLaTeX ou LuaLaTeX. Si votre ordinateur portable et CI exécutent le même latexmk main.tex, vous évitez l'échec de dernière minute « seule ma machine le construit ».

# .latexmkrc: upLaTeX + dvipdfmx
$latex = "uplatex -interaction=nonstopmode -halt-on-error %O %S";
$bibtex = "upbibtex %O %B";
$dvipdf = "dvipdfmx %O -o %D %S";
$pdf_mode = 3;

Validez ce .latexmkrc, et Docker et GitHub Actions construiront le PDF selon les mêmes règles. Plutôt que d'installer des packages ad hoc avec tlmgr install à chaque exécution, choisissez un schéma TeX Live ou une balise d'image épinglée qui contient déjà ce dont le projet a besoin ; les builds sont plus rapides et les échecs plus faciles à retracer.