latex-docker/README.md

# LaTeX Docker Builder

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](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](#voraussetzungen)
- [Schnellstart](#schnellstart)
  - [1. PowerShell (Windows)](#1-powershell-windows)
  - [2. Bash / Linux / macOS / WSL](#2-bash--linux--macos--wsl)
  - [3. Docker Compose](#3-docker-compose)
  - [4. Reines Docker CLI](#4-reines-docker-cli)
  - [5. Makefile](#5-makefile)
- [Nutzung durch Mitstudierende (Beliebige Ordnerstrukturen)](#nutzung-durch-mitstudierende-beliebige-ordnerstrukturen)
- [Image selbst bauen](#image-selbst-bauen)
- [Git Remote & Image Registry](#git-remote--image-registry)
  - [Code ins Git-Repo pushen](#code-ins-git-repo-pushen)
  - [Image zur Registry pushen (optional)](#image-zur-registry-pushen-optional)
- [Beispiel für CI/CD (Gitea Actions / Woodpecker)](#beispiel-f%C3%BCr-cicd-gitea-actions--woodpecker)

---

## Voraussetzungen

- [Docker Desktop](https://www.docker.com/products/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:

```powershell
# 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

```bash
# 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

```bash
# 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:

```bash
# 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:

```bash
# 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

```bash
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:
1. Typische Dateinamen: `seminararbeit.tex`, `thesis.tex`, `main.tex`, `bachelorarbeit.tex`, `masterarbeit.tex`, `arbeit.tex`, `document.tex`.
2. Findet es keinen dieser Namen, sucht es automatisch nach der Datei, die `\documentclass` enthält.
3. 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:**
```powershell
docker run --rm -v "${PWD}:/workspace" latex-docker:latest
```

**Linux / macOS / WSL:**
```bash
docker run --rm -v "$(pwd):/workspace" latex-docker:latest
```

Falls die Datei einen unüblichen Namen hat (z. B. `mein_projekt.tex`):
```bash
docker run --rm -v "${PWD}:/workspace" latex-docker:latest build mein_projekt.tex
```

### Mit dem Skript für andere Pfade
```powershell
.\build-seminar.ps1 -ProjectPath "C:\Pfad\Zu\Beliebigem\Projekt"
```

---

## Image selbst bauen

Das Image lokal bauen und mit Tags versehen:

```bash
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:

```bash
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:

```bash
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`)

```yaml
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
```