Docker-Image und Build-Umgebung zum plattformunabhängigen, reproduzierbaren Kompilieren von LaTeX-Dokumenten (wie der Seminararbeit oder Masterthesis an der Fachhochschule Burgenland).

Git-Repository: https://git.djnizz.at/Nizz05/latex-docker.git
Basis-Image: texlive/texlive:latest (Vollständige TeX Live Distribution inkl. latexmk, biber, biblatex, koma-script, mathpazo, tikz etc.)

Inhaltsverzeichnis

Voraussetzungen
Schnellstart
Nutzung durch Mitstudierende (Beliebige Ordnerstrukturen)
VS Code Integration
- Variante A: Mit der Extension "LaTeX Workshop" (Auto-Build bei Speichern)
- Variante B: Über VS Code Tasks (Strg + Shift + B)
Image selbst bauen
Git Remote & Image Registry
- Code ins Git-Repo pushen
- Image zur Registry pushen (optional)
Beispiel für CI/CD (Gitea Actions / Woodpecker)

Voraussetzungen

Docker Desktop (oder Docker Engine unter Linux) läuft auf Ihrem System.
Keine lokale TeX-Live- oder MiKTeX-Installation auf dem Host erforderlich!

Schnellstart

1. PowerShell (Windows)

Das mitgelieferte Skript build-seminar.ps1 vereinfacht alle Abläufe:

# Seminararbeit kompilieren
.\build-seminar.ps1

# Bereinigen (löscht temporäre Dateien im out/-Ordner)
.\build-seminar.ps1 -Clean

# Kontinuierlicher Watch-Modus (baut bei jeder Dateiänderung neu)
.\build-seminar.ps1 -Watch

# Anderes Dokument kompilieren
.\build-seminar.ps1 -File "meinDokument.tex"

2. Bash / Linux / macOS / WSL

# Ausführbar machen
chmod +x build-seminar.sh

# Kompilieren
./build-seminar.sh

# Bereinigen
./build-seminar.sh ../Seminar_Arbeit_BITI_Gruber clean

# Watch-Modus
./build-seminar.sh ../Seminar_Arbeit_BITI_Gruber watch

3. Docker Compose

# Bauen
docker compose run --rm builder

# Bereinigen
docker compose run --rm clean

# Watch-Modus
docker compose run --rm watch

4. Reines Docker CLI

Direkt ohne Hilfsskripte:

# Windows PowerShell:
docker run --rm -v "${PWD}/../Seminar_Arbeit_BITI_Gruber:/workspace" -w /workspace latex-docker:latest

# Linux / macOS / WSL:
docker run --rm -v "$(pwd)/../Seminar_Arbeit_BITI_Gruber:/workspace" -w /workspace latex-docker:latest

Beliebige LaTeX-Befehle übergeben:

# Bereinigen
docker run --rm -v "${PWD}/../Seminar_Arbeit_BITI_Gruber:/workspace" latex-docker:latest clean

# Spezifischen latexmk-Befehl ausführen
docker run --rm -v "${PWD}/../Seminar_Arbeit_BITI_Gruber:/workspace" latex-docker:latest latexmk -pdf seminararbeit.tex

5. Makefile

make image    # Image bauen
make build    # Seminararbeit kompilieren
make clean    # Temporäre Dateien löschen
make watch    # Kontinuierlich bauen
make shell    # Interaktive Bash-Shell im Container öffnen

Nutzung durch Mitstudierende (Beliebige Ordnerstrukturen)

Ja! Das Docker-Image ist so konzipiert, dass es für jede beliebige Ordnerstruktur und Dateinamen funktioniert:

Automatische Erkennung

Das Image erkennt automatisch das Hauptdokument im übergebenen Ordner:

Typische Dateinamen: seminararbeit.tex, thesis.tex, main.tex, bachelorarbeit.tex, masterarbeit.tex, arbeit.tex, document.tex.
Findet es keinen dieser Namen, sucht es automatisch nach der Datei, die \documentclass enthält.
Hat das Projekt eine .latexmkrc (z. B. für Ausgabe nach out/), wird diese automatisch beachtet. Falls keine vorhanden ist, kompiliert es im Hauptverzeichnis.

1-Zeiler für Mitstudierende (ohne dieses Repo clonen zu müssen)

Mitstudierende müssen nur in ihren eigenen Projektordner wechseln und folgenden Befehl ausführen:

Windows PowerShell:

docker run --rm -v "${PWD}:/workspace" latex-docker:latest

Linux / macOS / WSL:

docker run --rm -v "$(pwd):/workspace" latex-docker:latest

Falls die Datei einen unüblichen Namen hat (z. B. mein_projekt.tex):

docker run --rm -v "${PWD}:/workspace" latex-docker:latest build mein_projekt.tex

Mit dem Skript für andere Pfade

.\build-seminar.ps1 -ProjectPath "C:\Pfad\Zu\Beliebigem\Projekt"

VS Code Integration

Variante A: Mit der Extension "LaTeX Workshop" (Auto-Build bei Speichern)

Wenn Sie oder Ihre Kollegen die beliebte Extension LaTeX Workshop (James-Yu.latex-workshop) nutzen, kann Docker als Standard-Compiler hinterlegt werden. Bei jedem Strg + S baut Docker das PDF automatisch und aktualisiert die Vorschau in VS Code.

Fügen Sie dazu in Ihrem LaTeX-Projekt in .vscode/settings.json Folgendes ein:

{
    "latex-workshop.latex.outDir": "%DIR%/out",
    "latex-workshop.latex.tools": [
        {
            "name": "docker-latexmk",
            "command": "docker",
            "args": [
                "run",
                "--rm",
                "-v",
                "%DIR%:/workspace",
                "-w",
                "/workspace",
                "latex-docker:latest",
                "build",
                "%DOCFILE%"
            ]
        }
    ],
    "latex-workshop.latex.recipes": [
        {
            "name": "Docker LaTeX",
            "tools": [
                "docker-latexmk"
            ]
        }
    ],
    "latex-workshop.latex.recipe.default": "Docker LaTeX",
    "latex-workshop.latex.autoBuild.run": "onSave"
}

Variante B: Über VS Code Tasks (`Strg + Shift + B`)

Funktioniert komplett ohne spezielle LaTeX-Erweiterung über die integrierte Task-Funktion von VS Code.

Erstellen Sie im LaTeX-Projekt die Datei .vscode/tasks.json:

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "Build LaTeX (Docker)",
            "type": "shell",
            "command": "docker",
            "args": [
                "run",
                "--rm",
                "-v",
                "${workspaceFolder}:/workspace",
                "-w",
                "/workspace",
                "latex-docker:latest",
                "build"
            ],
            "group": {
                "kind": "build",
                "isDefault": true
            },
            "problemMatcher": ["$latex"]
        },
        {
            "label": "Clean LaTeX (Docker)",
            "type": "shell",
            "command": "docker",
            "args": [
                "run",
                "--rm",
                "-v",
                "${workspaceFolder}:/workspace",
                "-w",
                "/workspace",
                "latex-docker:latest",
                "clean"
            ],
            "problemMatcher": []
        }
    ]
}

Bauen: Tastenkombination Strg + Shift + B
Bereinigen: Menü Terminal -> Run Task... -> Clean LaTeX (Docker)

Image selbst bauen

Das Image lokal bauen und mit Tags versehen:

docker build -t latex-docker:latest -t git.djnizz.at/nizz05/latex-docker:latest .

Git Remote & Image Registry

Code ins Git-Repo pushen

Der Ordner ist bereits mit der Remote-URL https://git.djnizz.at/Nizz05/latex-docker.git verknüpft:

git add .
git commit -m "feat: Initial commit of latex docker builder environment"
git push -u origin main

Image zur Registry pushen (optional)

Falls Ihre Gitea/Forgejo-Instanz die Docker-Container-Registry aktiviert hat:

docker login git.djnizz.at
docker push git.djnizz.at/nizz05/latex-docker:latest

Beispiel für CI/CD (Gitea Actions / Woodpecker)

Gitea / GitHub Actions (`.gitea/workflows/build.yml`)

name: Build Seminararbeit

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    container:
      image: texlive/texlive:latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Compile LaTeX
        run: |
          latexmk -pdf seminararbeit.tex

      - name: Upload PDF Artifact
        uses: actions/upload-artifact@v4
        with:
          name: seminararbeit-pdf
          path: out/seminararbeit.pdf

README.md

LaTeX Docker Builder