homelab-infra/docs/WORKFLOW.md

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.