homelab-infra/docs/WORKFLOW.md

Workflow - GitOps / No-Drift Regeln

Dieses Dokument definiert den verbindlichen Arbeitsablauf fuer Aenderungen an der Homelab-Infrastruktur.

---

Ziel

Es darf keine dauerhafte Abweichung zwischen:

• Gitea Online
• lokalem Clone
• Komodo-Stacks
• laufenden Docker-Containern
• Host-Konfiguration

geben.

Grundsatz:

Gitea Online ist die operative Quelle der Wahrheit.

---

Betriebsmodell

Die Rollen sind bewusst getrennt:

• Gitea Online ist origin und damit der verbindliche Sollzustand.
• Der lokale Clone ist die Arbeitskopie fuer Aenderungen.
• Komodo deployed aus Gitea und ist kein Bearbeitungsort.
• Der Host ist Laufzeit, nicht Quelle der Wahrheit.

Operative Hierarchie

1. origin/master in Gitea
2. lokaler Clone auf dem Windows-PC
3. Komodo-Deployments / Webhooks
4. laufende Container und Host-Dateien

Wenn diese Ebenen voneinander abweichen, gewinnt immer zuerst Git und nicht der manuelle Live-Zustand.

---

Standard-Workflow

Aenderungen werden immer in dieser Reihenfolge durchgefuehrt:

1. Lokal synchronisieren
2. Lokal aendern
3. Commit erzeugen
4. Push nach Gitea
5. Komodo reagiert automatisch per Webhook
6. Ergebnis testen
7. Doku pruefen und nachziehen

---

Standardwerkzeug fuer den Alltag

Der bevorzugte lokale Workflow ist:

• GitHub Desktop fuer Fetch, Pull, Commit, Push
• Editor nach Wahl fuer Datei-Aenderungen
• Gitea Web fuer Historie, Review und kleine Notfaelle
• Komodo nur fuer Deploy-Status, Logs und Stack-Sicht

Tagesablauf mit GitHub Desktop

Vor lokaler Arbeit:

1. GitHub Desktop oeffnen
2. Fetch origin
3. wenn noetig Pull origin

Nach lokaler Arbeit:

1. Aenderungen pruefen
2. Commit mit sauberer Nachricht
3. Push origin
4. Komodo-Webhook im Hinterkopf behalten

---

Wenn online in Gitea gearbeitet wurde

Web-Aenderungen in Gitea sind erlaubt, aber nicht der Normalfall.

Wenn online etwas geaendert wurde, gilt vor der naechsten lokalen Arbeit:

1. GitHub Desktop oeffnen
2. Fetch origin
3. Pull origin
4. erst dann lokal weiterarbeiten

Sonst entsteht Drift zwischen Gitea Online und lokalem Clone.

---

Komodo-Regeln

Komodo ist in diesem Setup:

• primaeres Deployment-Werkzeug
• GitOps-Consumer fuer die Stacks
• Monitoring- und Status-Werkzeug

Deshalb gilt

• Stack-Konfiguration nur im Repository anpassen
• nicht im Komodo-Web-Editor arbeiten
• Pushes koennen automatisch einen Komodo-Deploy ausloesen
• wenn Komodo und Git voneinander abweichen, gewinnt Git

Ausnahme: Komodo-Zugangsmodell

Komodo bleibt bewusst ohne zentrale Traefik-ForwardAuth-Middleware.

Grund:

• Komodo hat eigene Authentifizierung
• Komodo nutzt REST- und WebSocket-Endpunkte
• Webhooks laufen ueber /listener/...
• Periphery nutzt den speziellen WebSocket-Pfad /ws/periphery

Deshalb wird Komodo aktuell nur ueber Traefik veroeffentlicht, aber nicht pauschal mit authelia@file vorgeschaltet.

Regel: Aenderungen an Komodo-Auth, Komodo-Routing oder vorgeschalteter Middleware nur nach expliziter Wirkungspruefung auf:

• UI-Login
• Gitea-Webhooks
• Periphery-Verbindung
• API-/Automationszugriffe

---

Verbotene Arbeitsweise

Folgende Dinge sind grundsaetzlich zu vermeiden:

• Aenderungen direkt im Komodo-Web-Editor
• Aenderungen direkt per docker run
• Aenderungen an laufenden Containern ohne Repo-Anpassung
• spontane Host-Hotfixes ohne Nachdokumentation
• Secrets im Git-Repository
• mehrere kritische Dienste gleichzeitig migrieren

---

Erlaubte Arbeitsweise

Erlaubt und gewuenscht sind:

• Aenderungen an Compose-Dateien im Git-Repo
• Commit + Push vor jedem produktiven Deploy
• GitHub Desktop als Standardweg fuer den lokalen Sync
• Gitea Web fuer Review, Historie und kleine Hotfixes
• Host-Hotfixes nur im Ausnahmefall mit sofortiger Nachpflege im Repo

---

No-Drift-Prinzip

Definition

Configuration Drift liegt vor, wenn der reale Zustand vom Git-Zustand abweicht.

Beispiele:

• laufender Container wurde manuell veraendert
• lokaler Clone ist nicht mehr auf dem Stand von origin/master
• Komodo-Stack entspricht nicht mehr dem Repo
• Host-Dateien wurden angepasst, aber nicht dokumentiert
• Traefik dynamic config wurde lokal geaendert, aber Git weiss nichts davon

Regel

Wenn Drift erkannt wird, gilt:

1. Drift nicht ignorieren
2. Drift sofort benennen
3. entscheiden:
   • Repo an Realitaet anpassen
   • oder Realitaet an Repo zurueckfuehren
4. erst danach weiterarbeiten

Pflichtcheck bei Drift-Verdacht

Vor jedem Reparaturversuch muessen die Ebenen getrennt geprueft werden:

1. lokaler Clone
2. Gitea origin/master
3. Komodo Stack Workspace
4. Docker Runtime
5. Host-Netzwerklistener

Das detaillierte Runbook steht in docs/GITOPS_DRIFT_RUNBOOK.md.

Regel: HostConfig.PortBindings allein beweist keinen aktiven Host-Port. Entscheidend sind NetworkSettings.Ports, docker ps, ss -ltnp und ein echter curl gegen den Host-Port.

Stop-Regel: Wenn zwei Reparaturversuche nicht zum erwarteten Ergebnis fuehren, keine weiteren Schreibbefehle ausfuehren. Erst die Pflichtmatrix aus dem Runbook ausfuellen.

---

Ausnahmefall: Hotfix auf dem Host

Manchmal ist ein Live-Hotfix noetig. Das ist erlaubt, aber nur unter diesen Bedingungen:

1. Hotfix nur wenn der Dienst sonst nicht funktioniert
2. Aenderung sofort dokumentieren
3. Aenderung danach ins Git-Modell ueberfuehren
4. kein stiller Dauerzustand

Pflicht bei Hotfixes

• Was wurde geaendert?
• Wo wurde es geaendert?
• Warum war es noetig?
• Muss diese Aenderung ins Repo uebernommen werden?
• Ist ein Rollback dokumentiert?

---

Ausnahme: Traefik Dynamic Config

Diese Dateien werden von Komodo nicht automatisch deployed.

Komodo deployed ausschliesslich docker-compose.yml-Dateien. Die Traefik-Konfigurationsdateien unter traefik/dynamic/ im Git-Repo werden nicht automatisch auf den Host uebertragen.

Diese Ausnahme bleibt bewusst bestehen. Der File-Provider wird weiterhin nur fuer zentrale Middlewares, TLS und Dashboard-Konfiguration genutzt, waehrend Service-Routing ueber Docker-Labels laeuft.

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 Aenderungen an Traefik Dynamic Config

1. Datei im Git-Repo (traefik/dynamic/) aendern
2. Commit + Push
3. Datei manuell auf den Host kopieren
4. Traefik laedt dynamic config automatisch neu
5. Aenderung testen

Merksatz: Git-Commit allein reicht hier nicht. Ohne den manuellen Kopier-Schritt wirkt die Aenderung nicht.

---

Secrets-Regeln

• Secrets liegen niemals im Repository
• Secrets liegen unter /mnt/user/appdata/secrets/
• Secrets werden ueber 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

---

Image-Versionierung

• Mutable Tags wie latest, stable, release oder reine Major-Tags werden nach Moeglichkeit auf den aktuell laufenden Digest gepinnt.
• Digest-Pinning friert den bekannten Laufzeitstand ein; es ist kein automatisches Upgrade.
• Echte Versions-Upgrades sind ein eigener, bewusster Aenderungsblock mit anschliessendem Test.
• Wenn der laufende Digest unbekannt ist, wird er zuerst am produktiven Container ausgelesen und erst danach im Repo festgeschrieben.

---

DNS-Regeln fuer Container

Nicht alle Container koennen externe DNS-Namen aufloesen. Standardmaessig nutzt Docker 127.0.0.11 als internen DNS-Resolver. In bestimmten Netzwerk-Setups schlaegt externe Namensaufloesung damit fehl (server misbehaving).

Regel

Container die externe Domains aufloesen muessen erhalten explizit:

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

---

Dokumentationspflicht

Nach jeder erfolgreichen Migration oder relevanten Aenderung muessen diese Dateien geprueft werden:

• docs/MIGRATION_LOG.md
• docs/SECRETS_MAP.md
• docs/ROLLBACK.md
• HOMELAB_ARCHITECTURE_MASTER_V2.md falls Architektur betroffen ist
• docs/GITOPS_DRIFT_RUNBOOK.md falls GitOps-/Komodo-/Runtime-Drift betroffen ist

---

Sprint-Regel

Jede Migration wird als Sprint behandelt. Ein Sprint umfasst immer:

1. Ist-Zustand pruefen
2. Zielzustand definieren
3. Compose-Datei im Repo anpassen
4. lokal synchronisieren und aendern
5. Commit + Push
6. Deploy ueber Komodo
7. Test
8. Doku aktualisieren
9. Sprint abschliessen

Nie mehrere kritische Dienste gleichzeitig aendern.

---

Rollback-Regel

Jede Aenderung muss rueckrollbar sein. Vor jedem Deploy muss klar sein:

• wie der letzte funktionierende Zustand aussieht
• welcher Commit der letzte stabile Stand ist
• ob Datenpfade unveraendert bleiben
• wie der Dienst im Fehlerfall zurueckgenommen wird

Wenn Rollback nicht klar ist, wird nicht deployed.

---

Arbeitsregel fuer 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 duerfen Aenderungen vorgeschlagen werden.

---

Merksatz

Erst syncen, dann aendern. Erst Git, dann Deploy. Kein Drift, kein Chaos.