docs/WORKFLOW.md aktualisiert
This commit is contained in:
+34
-75
@@ -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.
|
||||
> Erst Git, dann Deploy.
|
||||
> Erst Wahrheit, dann Aktion.
|
||||
> Kein Drift, kein Chaos.
|
||||
|
||||
Reference in New Issue
Block a user