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
• Komodo-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 (Gitea)
2. Commit
3. Push
4. Deploy über Komodo (GitOps-Sync)
5. Test
6. Dokumentation aktualisieren

---

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
• 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
• Komodo als primäres Deployment-Werkzeug (GitOps)
• Portainer CE nur noch als Legacy-UI (wird in Sprint 5 abgeschaltet)
• Host-Hotfixes nur im Ausnahmefall — sofortige Nachpflege im Repo

---

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:
   • 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. 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?
• Muss diese Änderung ins Repo übernommen werden?
• Ist ein Rollback dokumentiert?

---

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

---

Portainer-Regeln (Legacy)

⚠️ Portainer CE ist in Ablösung. Abschaltung geplant in Sprint 5.

Portainer ist nicht mehr die Quelle der Wahrheit und wird nur noch als Fallback-UI genutzt.

---

Secrets-Regeln

• Secrets liegen niemals im Repository
• Secrets liegen unter /mnt/user/appdata/secrets/
• Secrets werden über Datei-Mounts mit _FILE Variablen oder Komodo Stack Environment Variables 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 (in HOMELAB_ARCHITECTURE_MASTER_V2.md)
3. Compose-Datei im Repo anpassen
4. Commit + Push
5. Deploy über Komodo
6. Test
7. Dokumentation aktualisieren
8. Sprint abschließen

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.

---

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.