# 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 --- ## ⚠️ Ausnahme: Traefik Dynamic Config > **Diese Dateien werden von Komodo NICHT automatisch deployt.** Komodo deployt ausschließlich `docker-compose.yml`-Dateien. Die Traefik-Konfigurationsdateien unter `traefik/dynamic/` im Git-Repo werden **nicht** automatisch auf den Host übertragen. ### 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 Änderungen an Traefik Dynamic Config 1. Datei im Git-Repo (`traefik/dynamic/`) ändern 2. Commit + Push 3. **Manuell auf den Host kopieren:** ```bash cp /mnt/user/homelab-infra/traefik/dynamic/middlewares.yml \ /mnt/user/appdata/traefik/dynamic/middlewares.yml ``` 4. Traefik lädt dynamic config automatisch neu (kein Neustart nötig) 5. Änderung testen > **Merksatz:** Git-Commit allein reicht hier nicht. Ohne den manuellen Kopier-Schritt wirkt die Änderung nicht. ### Warum so? Die `dynamic/`-Dateien definieren Traefik-Middlewares (z. B. Authelia ForwardAuth, Security-Headers). Alle anderen Services referenzieren diese via `@file`-Suffix. Wenn die Dateien auf dem Host fehlen oder veraltet sind, schlagen alle Dienste mit `authelia@file` oder `secure-headers@file` still fehl. --- ## 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 --- ## DNS-Regeln für Container Nicht alle Container können externe DNS-Namen auflösen. Standardmäßig nutzt Docker `127.0.0.11` als internen DNS-Resolver. In bestimmten Netzwerk-Setups schlägt externe Namensauflösung damit fehl (`server misbehaving`). ### Regel Container die **externe Domains auflösen müssen** (z. B. für ACME/Let's Encrypt, GitHub, externe APIs, DDNS-Updates) 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 | ### Interne Services (kein `dns:` nötig) Container, die nur Docker-interne Hostnamen auflösen (z. B. `authelia`, `redis`, `postgres`), benötigen keinen expliziten DNS-Eintrag. --- ## 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.