docs/WORKFLOW.md aktualisiert

docs/WORKFLOW.md

@@ -7,6 +7,7 @@ Dieses Dokument definiert den verbindlichen Arbeitsablauf für Änderungen an de
 ## Ziel
 
 Es darf **keine dauerhafte Abweichung** zwischen:
+
 - Git-Repository
 - Komodo-Stacks
 - laufenden Docker-Containern
@@ -15,6 +16,7 @@ Es darf **keine dauerhafte Abweichung** zwischen:
 geben.
 
 **Grundsatz:**
+
 > Git ist die einzige Quelle der Wahrheit.
 
 ---
@@ -35,6 +37,7 @@ geben.
 ## Verbotene Arbeitsweise
 
 Folgende Dinge sind grundsätzlich zu vermeiden:
+
 - Änderungen direkt im Komodo- oder Portainer-Web-Editor
 - Änderungen direkt per `docker run`
 - Änderungen an laufenden Containern ohne Repo-Anpassung
@@ -47,6 +50,7 @@ Folgende Dinge sind grundsätzlich zu vermeiden:
 ## Erlaubte Arbeitsweise
 
 Erlaubt und gewünscht sind:
+
 - Änderungen an Compose-Dateien im Git-Repo
 - Commit + Push vor jedem Deploy
 - Komodo als primäres Deployment-Werkzeug (GitOps)
@@ -58,16 +62,20 @@ Erlaubt und gewünscht sind:
 ## No-Drift-Prinzip
 
 ### Definition
+
 **Configuration Drift** liegt vor, wenn der reale Zustand vom Git-Zustand abweicht.
 
 Beispiele:
+
 - laufender Container wurde manuell verändert
 - Komodo-Stack entspricht nicht mehr dem Repo
 - Host-Dateien wurden angepasst, aber nicht dokumentiert
 - Traefik dynamic config wurde lokal geändert, aber Git weiß nichts davon
 
 ### Regel
+
 Wenn Drift erkannt wird, gilt:
+
 1. Drift **nicht ignorieren**
 2. Drift **sofort benennen**
 3. entscheiden:
@@ -80,12 +88,14 @@ Wenn Drift erkannt wird, gilt:
 ## Ausnahmefall: Hotfix auf dem Host
 
 Manchmal ist ein Live-Hotfix nötig. Das ist erlaubt, aber nur unter diesen Bedingungen:
+
 1. Hotfix nur wenn der Dienst sonst nicht funktioniert
 2. Änderung sofort dokumentieren
 3. Änderung danach ins Git-Modell überführen
 4. kein stiller Dauerzustand
 
 ### Pflicht bei Hotfixes
+
 - Was wurde geändert?
 - Wo wurde es geändert?
 - Warum war es nötig?
@@ -97,17 +107,53 @@ Manchmal ist ein Live-Hotfix nötig. Das ist erlaubt, aber nur unter diesen Bedi
 ## Komodo-Regeln
 
 Komodo ist in diesem Setup:
+
 - **primäres** Deployment-Werkzeug (GitOps)
 - Stack-Manager (sync aus Gitea)
 - Monitoring-/Status-Werkzeug
 
 ### Deshalb gilt
+
 - Stack-Konfiguration nur im Repository anpassen
 - Komodo sync auslösen statt manuell deployen
 - Wenn Komodo und Git voneinander abweichen, gewinnt Git
 
 ---
 
+## ⚠️ Ausnahme: Traefik Dynamic Config
+
+> **Diese Dateien werden von Komodo NICHT automatisch deployt.**
+
+Komodo deployt ausschließlich `docker-compose.yml`-Dateien. Die Traefik-Konfigurationsdateien unter `traefik/dynamic/` im Git-Repo werden **nicht** automatisch auf den Host übertragen.
+
+### Betroffene Dateien
+
+| Git-Pfad | Host-Pfad (NAS) |
+|---|---|
+| `traefik/dynamic/middlewares.yml` | `/mnt/user/appdata/traefik/dynamic/middlewares.yml` |
+| `traefik/dynamic/tls.yml` | `/mnt/user/appdata/traefik/dynamic/tls.yml` |
+| `traefik/dynamic/dashboards.yml` | `/mnt/user/appdata/traefik/dynamic/dashboards.yml` |
+
+### Pflicht-Workflow bei Änderungen an Traefik Dynamic Config
+
+1. Datei im Git-Repo (`traefik/dynamic/`) ändern
+2. Commit + Push
+3. **Manuell auf den Host kopieren:**
+```bash
+   cp /mnt/user/homelab-infra/traefik/dynamic/middlewares.yml \
+      /mnt/user/appdata/traefik/dynamic/middlewares.yml
+```
+4. Traefik lädt dynamic config automatisch neu (kein Neustart nötig)
+5. Änderung testen
+
+> **Merksatz:** Git-Commit allein reicht hier nicht. Ohne den manuellen Kopier-Schritt wirkt die Änderung nicht.
+
+### Warum so?
+
+Die `dynamic/`-Dateien definieren Traefik-Middlewares (z. B. Authelia ForwardAuth, Security-Headers). Alle anderen Services referenzieren diese via `@file`-Suffix. Wenn die Dateien auf dem Host fehlen oder veraltet sind, schlagen alle Dienste mit `authelia@file` oder `secure-headers@file` still fehl.
+
+---
+
 ## Portainer-Regeln (Legacy)
 
 > ⚠️ Portainer CE ist in Ablösung. Abschaltung geplant in Sprint 5.
@@ -126,9 +172,36 @@ Portainer ist **nicht** mehr die Quelle der Wahrheit und wird nur noch als Fallb
 
 ---
 
+## DNS-Regeln für Container
+
+Nicht alle Container können externe DNS-Namen auflösen. Standardmäßig nutzt Docker `127.0.0.11` als internen DNS-Resolver. In bestimmten Netzwerk-Setups schlägt externe Namensauflösung damit fehl (`server misbehaving`).
+
+### Regel
+
+Container die **externe Domains auflösen müssen** (z. B. für ACME/Let's Encrypt, GitHub, externe APIs, DDNS-Updates) erhalten explizit:
+```yaml
+dns:
+  - 1.1.1.1
+  - 8.8.8.8
+```
+
+### Aktuell betroffen
+
+| Service | Grund |
+|---|---|
+| `traefik` | ACME Let's Encrypt (`acme-v02.api.letsencrypt.org`) |
+| `ddns-updater` | IP-Erkennung (ipify.org) + Cloudflare API |
+
+### Interne Services (kein `dns:` nötig)
+
+Container, die nur Docker-interne Hostnamen auflösen (z. B. `authelia`, `redis`, `postgres`), benötigen keinen expliziten DNS-Eintrag.
+
+---
+
 ## Dokumentationspflicht
 
 Nach jeder erfolgreichen Migration oder relevanten Änderung müssen diese Dateien geprüft werden:
+
 - `docs/MIGRATION_LOG.md`
 - `docs/SECRETS_MAP.md`
 - `docs/ROLLBACK.md`
@@ -139,6 +212,7 @@ Nach jeder erfolgreichen Migration oder relevanten Änderung müssen diese Datei
 ## Sprint-Regel
 
 Jede Migration wird als Sprint behandelt. Ein Sprint umfasst immer:
+
 1. Ist-Zustand prüfen
 2. Zielzustand definieren (in `HOMELAB_ARCHITECTURE_MASTER_V2.md`)
 3. Compose-Datei im Repo anpassen
@@ -155,6 +229,7 @@ Jede Migration wird als Sprint behandelt. Ein Sprint umfasst immer:
 ## Rollback-Regel
 
 Jede Änderung muss rückrollbar sein. Vor jedem Deploy muss klar sein:
+
 - wie der letzte funktionierende Zustand aussieht
 - welcher Commit der letzte stabile Stand ist
 - ob Datenpfade unverändert bleiben