diff --git a/docs/WORKFLOW.md b/docs/WORKFLOW.md index 405ef1d..ddaa4db 100644 --- a/docs/WORKFLOW.md +++ b/docs/WORKFLOW.md @@ -7,15 +7,14 @@ Dieses Dokument definiert den verbindlichen Arbeitsablauf für Änderungen an de ## Ziel Es darf **keine dauerhafte Abweichung** zwischen: - - Git-Repository -- Portainer-Stacks +- Komodo-Stacks - laufenden Docker-Containern - Host-Konfiguration geben. -**Grundsatz:** +**Grundsatz:** > Git ist die einzige Quelle der Wahrheit. --- @@ -24,10 +23,10 @@ geben. Änderungen werden immer in dieser Reihenfolge durchgeführt: -1. **Änderung im Repository** +1. **Änderung im Repository** (Gitea) 2. **Commit** 3. **Push** -4. **Deploy über Portainer** +4. **Deploy über Komodo** (GitOps-Sync) 5. **Test** 6. **Dokumentation aktualisieren** @@ -36,8 +35,7 @@ geben. ## Verbotene Arbeitsweise Folgende Dinge sind grundsätzlich zu vermeiden: - -- Änderungen direkt im Portainer Web Editor +- Ä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 @@ -49,37 +47,31 @@ Folgende Dinge sind grundsätzlich zu vermeiden: ## Erlaubte Arbeitsweise Erlaubt und gewünscht sind: - - Änderungen an Compose-Dateien im Git-Repo - Commit + Push vor jedem Deploy -- Portainer nur als Deployment- und Monitoring-Werkzeug -- Host-Hotfixes nur im Ausnahmefall -- sofortige Nachpflege im Repo, wenn ein Hotfix nötig war -- Migration immer nur **ein Service pro Sprint** +- 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 -- Portainer-Stack entspricht nicht mehr dem Repo +- 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** + - Repo an Realität anpassen **oder** - Realität an Repo zurückführen 4. erst danach weiterarbeiten @@ -87,19 +79,13 @@ Wenn Drift erkannt wird, gilt: ## Ausnahmefall: Hotfix auf dem Host -Manchmal ist ein Live-Hotfix nötig, um einen Dienst sofort wieder lauffähig zu machen. - -Das ist erlaubt, aber nur unter diesen Bedingungen: - +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 - -Nach jedem Hotfix müssen diese Fragen beantwortet werden: - - Was wurde geändert? - Wo wurde es geändert? - Warum war es nötig? @@ -108,22 +94,25 @@ Nach jedem Hotfix müssen diese Fragen beantwortet werden: --- -## Portainer-Regeln +## Komodo-Regeln -Portainer ist in diesem Setup: - -- Deployment-Werkzeug -- Monitoring-Werkzeug -- Log-/Status-Werkzeug - -Portainer ist **nicht** die Quelle der Wahrheit. +Komodo ist in diesem Setup: +- **primäres** Deployment-Werkzeug (GitOps) +- Stack-Manager (sync aus Gitea) +- Monitoring-/Status-Werkzeug ### Deshalb gilt - -- Git-Stacks nicht im Portainer Editor ändern - Stack-Konfiguration nur im Repository anpassen -- Portainer nur zum Deploy/Redeploy nutzen -- Wenn Portainer und Git voneinander abweichen, gewinnt Git +- 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. --- @@ -131,7 +120,7 @@ Portainer ist **nicht** die Quelle der Wahrheit. - Secrets liegen niemals im Repository - Secrets liegen unter `/mnt/user/appdata/secrets/` -- Secrets werden über Datei-Mounts oder `_FILE` Variablen eingebunden +- 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 @@ -140,7 +129,6 @@ Portainer ist **nicht** die Quelle der Wahrheit. ## 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` @@ -150,31 +138,23 @@ Nach jeder erfolgreichen Migration oder relevanten Änderung müssen diese Datei ## Sprint-Regel -Jede Migration wird als Sprint behandelt. - -Ein Sprint umfasst immer: - +Jede Migration wird als Sprint behandelt. Ein Sprint umfasst immer: 1. Ist-Zustand prüfen -2. Zielzustand definieren +2. Zielzustand definieren (in `HOMELAB_ARCHITECTURE_MASTER_V2.md`) 3. Compose-Datei im Repo anpassen 4. Commit + Push -5. Deploy über Portainer +5. Deploy über Komodo 6. Test 7. Dokumentation aktualisieren 8. Sprint abschließen -### Wichtig - > Nie mehrere kritische Dienste gleichzeitig ändern. --- ## Rollback-Regel -Jede Änderung muss rückrollbar sein. - -Vor jedem Deploy muss klar sein: - +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 @@ -184,27 +164,6 @@ Wenn Rollback nicht klar ist, wird nicht deployt. --- -## Umgang mit Legacy-Konfiguration - -Legacy-Konfigurationen außerhalb des Repos gelten als Risiko. - -Beispiele: -- alte Traefik dynamic files -- manuell erzeugte Host-Konfigurationen -- frühere Docker-/Dockerman-Einzelcontainer - -### Regel - -Legacy-Bestand muss: - -1. identifiziert -2. dokumentiert -3. schrittweise entfernt oder ins Repo überführt - -werden. - ---- - ## Arbeitsregel für KI-Assistenten Wenn mit einer KI gearbeitet wird, gilt immer: @@ -221,6 +180,6 @@ Erst danach dürfen Änderungen vorgeschlagen werden. ## Merksatz -> Erst Git, dann Deploy. -> Erst Wahrheit, dann Aktion. -> Kein Drift, kein Chaos. \ No newline at end of file +> Erst Git, dann Deploy. +> Erst Wahrheit, dann Aktion. +> Kein Drift, kein Chaos.