docs/WORKFLOW.md aktualisiert

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 Komodo- oder Portainer-Web-Editor
-- Änderungen direkt im 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
+- Komodo als primäres Deployment-Werkzeug (GitOps)
-- Host-Hotfixes nur im Ausnahmefall
+- Portainer CE nur noch als Legacy-UI (wird in Sprint 5 abgeschaltet)
-- sofortige Nachpflege im Repo, wenn ein Hotfix nötig war
+- Host-Hotfixes nur im Ausnahmefall — sofortige Nachpflege im Repo
-- Migration immer nur **ein Service pro Sprint**
 
 ---
 
 ## 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  
+   - Repo an Realität anpassen **oder**
-   **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.
+Manchmal ist ein Live-Hotfix nötig. Das ist erlaubt, aber nur unter diesen Bedingungen:
-
-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:
+Komodo ist in diesem Setup:
-
+- **primäres** Deployment-Werkzeug (GitOps)
-- Deployment-Werkzeug
+- Stack-Manager (sync aus Gitea)
-- Monitoring-Werkzeug
+- Monitoring-/Status-Werkzeug
-- Log-/Status-Werkzeug
-
-Portainer ist **nicht** die Quelle der Wahrheit.
 
 ### Deshalb gilt
-
-- Git-Stacks nicht im Portainer Editor ändern
 - Stack-Konfiguration nur im Repository anpassen
-- Portainer nur zum Deploy/Redeploy nutzen
+- Komodo sync auslösen statt manuell deployen
-- Wenn Portainer und Git voneinander abweichen, gewinnt Git
+- 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.
+Jede Migration wird als Sprint behandelt. Ein Sprint umfasst immer:
-
-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.
+Jede Änderung muss rückrollbar sein. Vor jedem Deploy muss klar 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 Git, dann Deploy.
-> Erst Wahrheit, dann Aktion.  
+> Erst Wahrheit, dann Aktion.
-> Kein Drift, kein Chaos.
+> Kein Drift, kein Chaos.