Einrichtung mit Docker / CI

Sie müssen TeX nicht auf Ihrem eigenen Computer installieren: Ein Docker-Image packt die gesamte Satzumgebung, sodass Sie .tex mit dem gleichen Verfahren überall in PDF umwandeln können. Dies passt natürlich zu CI (kontinuierliche Integration) wie GitHub Actions – jeder Push kann PDF automatisch erstellen und als Artefakt speichern. Auf dieser Seite geht es um das beliebte texlive/texlive-Image und darum, wie man TeX-Builds in CI automatisiert und reproduzierbar macht.

Warum in einen Container setzen?

Wenn eine Distribution die „TeX-Umgebung selbst“ ist (siehe Distributionen), ist ein Docker-Image die Box, die diese Umgebung zusammen mit ihrem OS eingefroren liefert. In der Box befinden sich eine bestimmte Version von TeX Live, die Engines, die Pakete und die Schriftarten. Ganz gleich, ob Ihr Host Windows oder macOS oder ein CI-Server ist, wenn Sie dieselbe Box öffnen, erhalten Sie dieselbe Umgebung. Der größte Vorteil besteht darin, die Nichtübereinstimmung „funktioniert auf meinem Computer, schlägt aber im Setup meines Kollegen oder in CI fehl“ zu vermeiden.

Container und Desktop-Installationen schließen sich nicht gegenseitig aus. Eine häufige Aufteilung besteht darin, täglich mit Ihrem Editor und einem lokalen TeX zu schreiben (siehe Desktop-Installation) und nur den endgültigen Build, die endgültige Zusammenarbeit oder die Veröffentlichung in einen Container oder CI zu übergeben. Das Schlüsselwort ist Reproduzierbarkeit: Fixieren Sie die Version mit einem Tag, und eine Neuerstellung ein halbes Jahr später ergibt immer noch dasselbe PDF.

Das texlive/texlive-Bild

Ein weit verbreitetes Image für TeX Live ist texlive/texlive, veröffentlicht als Island of TeX-Image auf Docker Hub (docker.io/texlive/texlive) und GitLab (registry.gitlab.com/islandoftex/images/texlive). Darin befindet sich TeX Live (die stabile Version im Jahr 2026 ist TeX Live 2026), mit Engines, Paketen und Tools wie latexmk. Wöchentliche Builds verfolgen CTAN-Updates.

Mithilfe von Tags können Sie ein Schema (Größenstufe) auswählen. Es gibt fünf – minimal, basic, small, medium, full – und latest-Maps zum größten, full (alle Pakete). Sie können diese damit kombinieren, ob Dokumentation und Quellen enthalten sind: Das Bare-Tag hat keines davon, -doc fügt Dokumente hinzu, -src fügt Quellen hinzu und -doc-src fügt beide hinzu. Dokumente und Quellen sind umfangreich; CI benötigt sie selten, sodass ein nacktes oder kleineres Schema schneller funktioniert. Es gibt auch -context-Varianten für ConTeXt-Benutzer.

Die Verwendung ist einfach: docker run mit dem aktuellen Verzeichnis, das im Container gemountet ist, und dann latexmk darin ausführen. Hier ist ein einmaliger Build eines lokalen main.tex. --rm verwirft den Container anschließend, -v "$PWD":/work ordnet Ihren aktuellen Standort /work zu und -w /work macht diesen zum Arbeitsverzeichnis. Das resultierende PDF landet direkt wieder in Ihrem Ordner.

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

Führen Sie für ein japanisches Dokument eine bestimmte Engine anstelle von einfachem latexmk aus – z. B. latexmk -lualatex main.tex für LuaLaTeX oder latexmk main.tex für die Route upLaTeX + dvipdfmx, sobald Sie eine .latexmkrc angeben. Das Mounten funktioniert auf die gleiche Weise: Sowohl die Ein- als auch die Ausgabe befinden sich live in Ihrem lokalen Verzeichnis.

Frieren Sie die Umgebung ein, um die Reproduzierbarkeit zu gewährleisten. latest wechselt jede Woche zu einem neuen TeX Live-Snapshot. Belassen Sie ihn also nicht als Standard für die endgültige Erstellung einer Arbeit oder veröffentlichtes Lehrmaterial. Wählen Sie zunächst das Veröffentlichungsjahr und die Version von TeX Live aus und verwenden Sie gegebenenfalls ein historisches Veröffentlichungs-Tag. Wie der Docker-Hub jedoch feststellt, können sogar historische Images neu erstellt werden, wenn das zugrunde liegende OS-Image aktualisiert wird. Wenn Sie später genau denselben Container Stück für Stück benötigen, heften Sie einen Image-Digest sowie ein Tag an oder speichern Sie das nachweislich funktionierende Image in Ihrer eigenen Registrierung.

Automatisierte Builds mit GitHub Actions

Für ein GitHub-Repository kann GitHub Actions Ihr .tex bei jedem Push kompilieren. Die beliebte Wahl ist xu-cheng/latex-action@v4. Es verwendet einen Container mit TeX Live darin und ruft standardmäßig latexmk auf, sodass der Workflow nur ein paar Zeilen umfasst. Unten finden Sie ein Minimalbeispiel, das bei jedem Push main.tex im Repo-Root erstellt und PDF als Build-Artefakt speichert.

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

Beim Push startet ein Container auf dem Runner von GitHub und der in root_file genannte main.tex wird von latexmk kompiliert. Die standardmäßigen latexmk-Argumente sind -pdf -file-line-error -halt-on-error -interaction=nonstopmode – eine CI-freundliche Einstellung, die bei Fehlern stoppt und ohne Aufforderung bis zum Ende ausgeführt wird. Das fertige PDF kann als Artefakt von der Seite „Aktionen ausführen“ heruntergeladen werden.

Kennen Sie die wichtigsten Eingaben (with:). root_file ist das Build-Ziel (Globs erlaubt). Wechseln Sie die Engine mit latexmk_use_lualatex: true für LuaLaTeX oder latexmk_use_xelatex: true für XeLaTeX (LuaLaTeX ist die einfachere Route für Japaner). texlive_version wählt 2020–2026 oder latest aus, sodass Sie zur Reproduzierbarkeit nach Jahr pinnen können. os ist das Basisbetriebssystem – standardmäßig ist das leichte Betriebssystem alpine, wobei debian bei Bedarf verfügbar ist. Für Pakete, die \write18 verwenden, legen Sie latexmk_shell_escape: true fest.

Um Builds schneller zu machen, können Sie über actions/cache Dinge zwischenspeichern, die sonst bei jedem Lauf neu installiert oder heruntergeladen würden. Das heißt, latex-action bündelt bereits ein umfangreiches TeX Live, sodass die meisten Projekte sofort mit einer praktischen Geschwindigkeit laufen. Beginnen Sie mit der minimalen Einrichtung und optimieren Sie erst, wenn die Langsamkeit tatsächlich zum Problem wird.

GitLab CI verfolgt den gleichen Ansatz

GitLab CI folgt der gleichen Idee, nur dass Sie das Bild direkt benennen, anstatt eine dedizierte Aktion zu verwenden. Setzen Sie „image:“ des Jobs auf „texlive/texlive:latest“ (oder einen Tag mit Datumsfixierung), führen Sie „latexmk -pdf main.tex“ in „script:“ aus und speichern Sie „PDF“ über „artifacts:“. Da es auf demselben Bild basiert, erhalten Sie das gleiche Satzergebnis wie GitHub Actions.

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

Das Wesentliche ist bei jedem Dienst das Gleiche: Lassen Sie latexmk in einem versionsfixierten Image einen One-Shot-Build steuern und sammeln Sie das resultierende PDF als Artefakt. Dies ist das gemeinsame Muster für die Ausführung von TeX in einem Container oder CI. Die Mechanismen alltäglicher automatisierter Builds werden auf den Seiten „CI“ und „Automatisierte Builds“ näher erläutert.

Machen Sie das Manuskript CI-ready

Ein Manuskript, das sich in CI gut verhält, hängt nicht von Ihren Editoreinstellungen ab. Die Root-Datei, Engine, Hilfsbefehle und Ausgabespeicherort werden im Repository aufgezeichnet. Fügen Sie für japanische Arbeiten ein .latexmkrc neben main.tex ein und wählen Sie explizit upLaTeX oder LuaLaTeX aus. Wenn sowohl Ihr Laptop als auch CI dasselbe latexmk main.tex ausführen, vermeiden Sie den Fehler „Nur mein Computer erstellt es“ in letzter Minute.

# .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;

Übertragen Sie dieses .latexmkrc, und Docker und GitHub Actions erstellen PDF nach denselben Regeln. Anstatt Pakete bei jedem Lauf ad hoc mit tlmgr install zu installieren, wählen Sie ein TeX Live-Schema oder ein angeheftetes Image-Tag, das bereits enthält, was das Projekt benötigt. Builds sind schneller und Fehler lassen sich leichter nachverfolgen.