# Hugo Docker CMS

Hugo-basiertes CMS im Docker-Stack mit Caddy als TLS-Reverse-Proxy.
Markdown-Dateien einfach in `content/` ablegen – Hugo rendert sie automatisch.

## Architektur

```
                    Port 5443
Browser ── HTTPS ──→ Caddy ── HTTP ──→ Hugo (live-reload)
                     :2-alpine       hugomods/hugo:latest
                     self-signed     markdown → HTML
```

| Komponente | Image | Aufgabe |
|---|---|---|
| Hugo | `hugomods/hugo:latest` (0.165+) | Rendert .md-Dateien, live-reload via --watch |
| Caddy | `caddy:2-alpine` | HTTPS-Terminierung, Reverse-Proxy → Hugo:1313 |

## Verzeichnisstruktur

```
hugo_docker/
├── docker-compose.yml       # Hugo + Caddy Stack
├── Caddyfile                # TLS + Reverse-Proxy
├── content/                 # ← .md-Dateien hier ablegen (Host-Mount)
├── crt/                     # Self-signed Zertifikate
├── site/                    # Hugo-Config, Layouts, CSS
│   ├── hugo.toml
│   ├── entrypoint.sh        # Auto-Frontmatter + Hugo-Server
│   ├── assets/css/main.css  # Modernes CSS (oklch, dark mode, grid)
│   └── layouts/             # HTML-Templates
├── ansible/
│   ├── deploy.yml           # Playbook
│   ├── tasks.yml            # Geteilte Tasks (DRY)
│   ├── templates/           # Caddyfile.j2, hugo.toml.j2
│   └── molecule/default/    # CI-Tests (Ubuntu Docker)
└── .gitea/workflows/
    └── deploy.yml           # CI: Molecule-Test → Deploy
```

## Schnellstart (lokal)

```bash
# Zertifikate generieren (nur einmal)
python3 -c "
import sys; sys.path.insert(0,'../Python_Skripte/create_selfsign')
from selfsign_ca import generate_and_save_cert
generate_and_save_cert(cert_common_name='localhost', cert_name='localhost')
"

# Container starten
docker compose up -d

# HTTPS aufrufen
curl -k https://localhost:5443/
```

## Nutzung

```bash
# Neue Seite anlegen – .md-Datei in content/ werfen
cat > content/mein-artikel.md << 'EOF'
---
title: "Mein Artikel"
date: "2026-09-08"
---

Inhalt im **Markdown**-Format.
EOF

# Kein Neustart nötig – Hugo erkennt Änderungen automatisch
docker compose restart hugo   # nur bei komplett neuen Dateien
```

## Frontmatter

Der Entrypoint (`site/entrypoint.sh`) fügt **automatisch** fehlendes YAML-Frontmatter
in .md-Dateien ein – extrahiert Titel aus der ersten `#`-Überschrift, Datum aus
dem Datei-Änderungsdatum.

Hugo benötigt diesen `---`-Block:

```yaml
---
title: "Meine Seite"
date: "2026-09-08"
---
```

Mit dem Entrypoint kannst du **beliebige** .md-Dateien in `content/` werfen.

## Deployment (Ansible)

Auf entfernten Host ausrollen:

```bash
cd ansible
ansible-playbook -i "ras-dan-01," deploy.yml
```

Variablen (optional):

```bash
ansible-playbook -i "ras-dan-01," deploy.yml \
  -e "target_hostname=ras-dan-01 target_port=5443"
```

Das Playbook legt alles unter `~/.docker/hugo/` auf dem Ziel-Host ab,
rendert Templates mit Hostname/Port und startet die Container.

## Zertifikate

Generiert mit `Python_Skripte/create_selfsign/selfsign_ca.py` (lokales Tool).
Jedes Zertifikat enthält eine **SAN (Subject Alternative Name)** Extension –
Pflicht für moderne Browser.

```bash
# CA systemweit vertrauen (optional, für Browser ohne Warnung)
sudo cp crt/ca.crt /etc/ca-certificates/trust-source/anchors/hugo-docker-ca.crt
sudo update-ca-trust

# Firefox / qutebrowser (NSS-Store)
certutil -A -d sql:$HOME/.pki/nssdb/ -t "CT,," \
  -n "Hugo Docker CA" -i crt/ca.crt
```

## CI/CD (Gitea Actions)

Workflow in `.gitea/workflows/deploy.yml` – läuft auf Runner mit Label `shell`:

```
Push auf main
  → molecule test (Ubuntu Docker)
    → syntax, create, prepare, converge, idempotence, verify, destroy
  → ansible-playbook deploy auf ras-dan-01
```

**Voraussetzungen auf dem Runner:**
- Docker + Docker Compose
- molecule + molecule-plugins[docker] (vorinstalliert)
- ansible-core (vorinstalliert)
- SSH-Agent mit Key für ras-dan-01

## CSS-Features

Modernes Theme in `site/assets/css/main.css`:

- `oklch()`-Farbraum mit `light-dark()` – automatisch hell/dunkel
- CSS Grid Layout (Header – Main – Footer)
- TOC (Table of Contents) als aufklappbares `<details>`-Element
- Code-Highlighting mit Catppuccin-Mocha-Theme
- Responsive (max-width: 840px)

## Hugo-Version

- Image: `hugomods/hugo:latest` (aktuell 0.165.0, August 2026)
- `hugo.toml` verwendet `locale` statt `languageCode` (v0.158+)
- Goldmark-Renderer mit `unsafe: true` (HTML in Markdown erlaubt)

## Troubleshooting

| Problem | Lösung |
|---|---|
| Neue .md-Dateien erscheinen nicht | `docker compose restart hugo` (Entrypoint läuft nur beim Start) |
| Browser zeigt Zertifikatswarnung | CA in NSS-Store importieren (s.o.) |
| Caddy startet nicht | `docker compose logs caddy` – TLS-Zertifikate prüfen unter `crt/` |
| Zertifikatsfehler "no SAN" | Zertifikate mit `selfsign_ca.py` neu generieren (SAN ist jetzt enthalten) |
| Molecule-Test schlägt fehl | `ansible_remote_tmp: /tmp/.ansible` in molecule.yml prüfen |