docs/WORKFLOW.md hinzugefügt

Add GitOps workflow and no-drift rules

docs/WORKFLOW.md

@@ -0,0 +1,226 @@
+# Workflow — GitOps / No-Drift Regeln
+
+Dieses Dokument definiert den verbindlichen Arbeitsablauf für Änderungen an der Homelab-Infrastruktur.
+
+---
+
+## Ziel
+
+Es darf **keine dauerhafte Abweichung** zwischen:
+
+- Git-Repository
+- Portainer-Stacks
+- laufenden Docker-Containern
+- Host-Konfiguration
+
+geben.
+
+**Grundsatz:**  
+> Git ist die einzige Quelle der Wahrheit.
+
+---
+
+## Die wichtigste Regel
+
+Änderungen werden immer in dieser Reihenfolge durchgeführt:
+
+1. **Änderung im Repository**
+2. **Commit**
+3. **Push**
+4. **Deploy über Portainer**
+5. **Test**
+6. **Dokumentation aktualisieren**
+
+---
+
+## Verbotene Arbeitsweise
+
+Folgende Dinge sind grundsätzlich zu vermeiden:
+
+- Änderungen direkt im Portainer Web Editor
+- Änderungen direkt per `docker run`
+- Änderungen an laufenden Containern ohne Repo-Anpassung
+- spontane Host-Hotfixes ohne Nachdokumentation
+- Secrets im Git-Repository
+- mehrere Services gleichzeitig migrieren
+
+---
+
+## Erlaubte Arbeitsweise
+
+Erlaubt und gewünscht sind:
+
+- Änderungen an Compose-Dateien im Git-Repo
+- Commit + Push vor jedem Deploy
+- Portainer nur als Deployment- und Monitoring-Werkzeug
+- Host-Hotfixes nur im Ausnahmefall
+- sofortige Nachpflege im Repo, wenn ein Hotfix nötig war
+- Migration immer nur **ein Service pro Sprint**
+
+---
+
+## No-Drift-Prinzip
+
+### Definition
+
+**Configuration Drift** liegt vor, wenn der reale Zustand vom Git-Zustand abweicht.
+
+Beispiele:
+- laufender Container wurde manuell verändert
+- Portainer-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:
+   - Repo an Realität anpassen  
+   **oder**
+   - Realität an Repo zurückführen
+4. erst danach weiterarbeiten
+
+---
+
+## Ausnahmefall: Hotfix auf dem Host
+
+Manchmal ist ein Live-Hotfix nötig, um einen Dienst sofort wieder lauffähig zu machen.
+
+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
+
+Nach jedem Hotfix müssen diese Fragen beantwortet werden:
+
+- Was wurde geändert?
+- Wo wurde es geändert?
+- Warum war es nötig?
+- Muss diese Änderung ins Repo übernommen werden?
+- Ist ein Rollback dokumentiert?
+
+---
+
+## Portainer-Regeln
+
+Portainer ist in diesem Setup:
+
+- Deployment-Werkzeug
+- Monitoring-Werkzeug
+- Log-/Status-Werkzeug
+
+Portainer ist **nicht** die Quelle der Wahrheit.
+
+### Deshalb gilt
+
+- Git-Stacks nicht im Portainer Editor ändern
+- Stack-Konfiguration nur im Repository anpassen
+- Portainer nur zum Deploy/Redeploy nutzen
+- Wenn Portainer und Git voneinander abweichen, gewinnt Git
+
+---
+
+## Secrets-Regeln
+
+- Secrets liegen niemals im Repository
+- Secrets liegen unter `/mnt/user/appdata/secrets/`
+- Secrets werden über Datei-Mounts oder `_FILE` Variablen eingebunden
+- Rechte: `chmod 600`
+- Secret-Namen und Pfade werden in `docs/SECRETS_MAP.md` dokumentiert
+
+---
+
+## 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`
+- `HOMELAB_ARCHITECTURE_MASTER_V2.md` (falls Architektur betroffen)
+
+---
+
+## Sprint-Regel
+
+Jede Migration wird als Sprint behandelt.
+
+Ein Sprint umfasst immer:
+
+1. Ist-Zustand prüfen
+2. Zielzustand definieren
+3. Compose-Datei im Repo anpassen
+4. Commit + Push
+5. Deploy über Portainer
+6. Test
+7. Dokumentation aktualisieren
+8. Sprint abschließen
+
+### Wichtig
+
+> Nie mehrere kritische Dienste gleichzeitig ändern.
+
+---
+
+## 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
+- wie der Dienst im Fehlerfall zurückgenommen wird
+
+Wenn Rollback nicht klar ist, wird nicht deployt.
+
+---
+
+## Umgang mit Legacy-Konfiguration
+
+Legacy-Konfigurationen außerhalb des Repos gelten als Risiko.
+
+Beispiele:
+- alte Traefik dynamic files
+- manuell erzeugte Host-Konfigurationen
+- frühere Docker-/Dockerman-Einzelcontainer
+
+### Regel
+
+Legacy-Bestand muss:
+
+1. identifiziert
+2. dokumentiert
+3. schrittweise entfernt oder ins Repo überführt
+
+werden.
+
+---
+
+## Arbeitsregel für KI-Assistenten
+
+Wenn mit einer KI gearbeitet wird, gilt immer:
+
+> Lies zuerst:
+> 1. `HOMELAB_ARCHITECTURE_MASTER_V2.md`
+> 2. `docs/WORKFLOW.md`
+> 3. die betroffene Compose-Datei
+> 4. ggf. `docs/MIGRATION_LOG.md`
+
+Erst danach dürfen Änderungen vorgeschlagen werden.
+
+---
+
+## Merksatz
+
+> Erst Git, dann Deploy.  
+> Erst Wahrheit, dann Aktion.  
+> Kein Drift, kein Chaos.