Micha/homelab-infra
1
0
Fork 0
Code Issues 1 Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
da2903c24197a8e53857dca44125d8fbb651fd27
homelab-infra/docs/WORKFLOW.md
T
Micha 88c07e7d66 docs/WORKFLOW.md aktualisiert
2026-03-30 08:53:45 +00:00

6.7 KiB
Raw Blame History

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:
   cp /mnt/user/homelab-infra/traefik/dynamic/middlewares.yml \
      /mnt/user/appdata/traefik/dynamic/middlewares.yml
  1. Traefik lädt dynamic config automatisch neu (kein Neustart nötig)
  2. Ä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:

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.

Reference in New Issue View Git Blame Copy Permalink