Nizz05/latex-docker
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0bfda24a822705bbaa7cb27f3f900197a177ea0e
latex-docker/README.md
T

320 lines
8.7 KiB
Markdown
Raw Blame History

# 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)
- [VS Code Integration](#vs-code-integration)
- [Variante A: Mit der Extension "LaTeX Workshop" (Auto-Build bei Speichern)](#variante-a-mit-der-extension-latex-workshop-auto-build-bei-speichern)
- [Variante B: Über VS Code Tasks (Strg + Shift + B)](#variante-b-%C3%BCber-vs-code-tasks-strg--shift--b)
- [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"
```
---
## 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:
```json
{
"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`:
```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:
```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
```
Reference in New Issue View Git Blame Copy Permalink