# 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 --- ## 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 --- ## 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: ```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 | --- ## 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 --- ## 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.