Traefik Reverse Proxy – Stack-Template

Zentraler Reverse Proxy / Edge Router für alle Stacks auf dem Server: TLS-Terminierung via Let's Encrypt, HTTP→HTTPS-Redirect, HTTP/3, Security-Header, Rate-Limiting, Geo-Blocking (optional) und ein interner Metrics/Ping-Endpoint für das Zabbix-Monitoring.

Template-Hinweis: Dieses Repo enthält nur Platzhalter (CHANGE_ME, example.com). Vor dem Produktiveinsatz alle Platzhalter in der .env und ggf. configs/traefik.yaml ersetzen.

---

1. Voraussetzungen

• Docker + Docker Compose v2

• Die Ports 80, 443/tcp und 443/udp (HTTP/3) müssen am Host frei sein

• Ein externes Docker-Netz, in dem alle zu routenden Stacks hängen:

  docker network create traefik_proxy_network
  

---

2. Einrichtung (Schritt für Schritt)

1. .env anpassen (alle Platzhalter ersetzen):

   • HOSTRULE → eigene Dashboard-Domain (DNS-A-Record muss auf den Server zeigen)
   • LETSENCRYPT_EMAIL → gültige E-Mail
   • DASHBOARD_PASSWORD_HASH → siehe nächster Punkt

2. Dashboard-Passwort-Hash erzeugen (Doppel-$$ ist Pflicht, sonst frisst Compose die Variablen):

   docker run --rm httpd:alpine htpasswd -nbB traefik-admin "DEIN_SICHERES_PASSWORT" | sed 's/\$/\$\$/g'
   

   Sicheres Passwort vorab erzeugen:

   openssl rand -base64 24
   

3. Starten:

   docker compose up -d
   

   Die Ordner logs/ und volumes/ werden beim ersten Start automatisch erstellt (sind in .gitignore – kommen niemals ins Git).

---

3. Worauf besonders achten

• Externes Netz zuerst anlegen – ohne traefik_proxy_network startet der Stack nicht.
• acme.json / Zertifikate liegen in volumes/Traefik.json. Dieses Verzeichnis sichern, aber niemals committen (ist ignoriert).
• Let's Encrypt Rate-Limits: Zum Testen ggf. den Staging-CA-Server in configs/traefik.yaml (caServer) verwenden, sonst drohen Sperren bei wiederholten Fehlversuchen.
• TLS ist sehr strikt (modern: nur TLS 1.3, sniStrict). Sehr alte Clients/Bots scheitern – bewusste Sicherheitsentscheidung.
• Statische traefik.yaml kann keine Env-Variablen lesen. Werte, die aus der .env kommen müssen (z. B. ACME-E-Mail), werden in docker-compose.yml per command-Flag gesetzt.
• Geo-Blocking (geo-block in traefik-dynamic.yaml) ist definiert, aber standardmäßig an keinen Router gehängt → wirkt erst, wenn man die Middleware aktiv zuweist.

---

4. Monitoring (Zabbix-Agent2)

Der interne Entrypoint metrics lauscht auf :8082 und liefert ohne TLS/Auth:

Pfad	Zweck
/metrics	Prometheus-Metrics (Last)
/ping	Status / Healthcheck (up/down)

Port 8082 wird bewusst nicht auf den Host veröffentlicht. Der Zabbix-Agent2 muss im selben Docker-Netz hängen (traefik_proxy_network) und erreicht Traefik dann über:

http://traefik:8082/metrics
http://traefik:8082/ping

Der Container-healthcheck nutzt denselben Ping-Endpoint (traefik healthcheck --ping).

---

5. Wiederverwendbare Middlewares (für andere Stacks)

In configs/traefik-dynamic.yaml definiert, per @file referenzierbar, z. B.:

• redirect-to-https@file, redirect-to-www@file, redirect-to-non-www@file
• security-headers@file (HSTS, Frame-Deny, Nosniff, Referrer-/Permissions-Policy)
• compression@file, rate-limit@file, in-flight-limit@file, geo-block@file

Beispiel-Label in einem anderen Stack:

- traefik.http.routers.meinapp.middlewares=security-headers@file,redirect-to-https@file

---

6. Logging & Rotation

• Application-Log: Datei logs/traefik.log, interne Rotation (maxSize 50MB, maxBackups 5, maxAge 7, gzip).
• Access-Log: geht auf stdout (Access-Log unterstützt keine interne Rotation) und wird über den Docker-json-file-Driver rotiert (max-size 50m, max-file 5). Abrufbar mit docker logs traefik.

Es gibt bewusst keinen separaten logrotate-Container mehr.

---

7. Nützliche Befehle

docker compose config -q        # Konfiguration validieren (.env-Auflösung prüfen)
docker compose up -d            # Starten
docker compose logs -f traefik  # Access-Log live
docker compose down             # Stoppen

---

8. CI/CD & Spiegelung

Die Pipeline (.forgejo/workflows/ci.yml) läuft self-hosted auf Forgejo, ganz ohne externe Actions (Checkout per git clone):

• validate (jeder Push/PR auf main + Tags): docker compose config -q, yamllint (relaxed) und gitleaks (nur Working-Tree). Es wird docker compose v2 genutzt (Runner-Image catthehacker/ubuntu:act-latest; nötig u. a. für v2-Keys wie dockerfile_inline), apt nur als Fallback – kein 64-MB-github-Download.
• mirror (nur Push, needs: validate): spiegelt main + Tags erst nach grünen Checks nach Codeberg (Org Docker-Stacks), mit Retry gegen transiente 502/504. Forgejos eingebauten Push-Mirror dafür nicht zusätzlich aktivieren.
• release (nur Tag v*): baut ein schlankes Deploy-ZIP und hängt es an ein Forgejo-Release und – als Backup – an ein Codeberg-Release (die Releases-Unit am Codeberg-Repo wird dabei automatisch aktiviert).

Release auslösen:

git tag v1.1
git push origin v1.1

Details siehe CICD-Actions.md.

Lizenz

Copyright (C) 2026 Christian Säum – web-seo-consulting.eu

Dieses Projekt steht unter der GNU Affero General Public License, Version 3 oder (nach deiner Wahl) einer späteren Version (AGPL-3.0-or-later). Der vollständige Lizenztext steht in der Datei LICENSE.

Du darfst die Software nutzen, weitergeben und – auch kommerziell – verkaufen. Gibst du eine veränderte Fassung weiter oder betreibst du sie über ein Netzwerk (z. B. als Dienst), muss deren vollständiger Quellcode ebenfalls unter der AGPL-3.0-or-later verfügbar sein. Der Copyright-Hinweis und die Nennung des ursprünglichen Autors dürfen nicht entfernt werden.

Diese Angabe betrifft nur die in diesem Repository enthaltenen eigenen Dateien (Konfiguration, Skripte, Anpassungen). Eingebundene Fremdsoftware und Container-Images unterliegen weiterhin ihren eigenen Lizenzen.