# 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

---

## 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

---

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