Micha/homelab-infra
1
0
Fork 0
Code Issues 1 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Aktualisierung

Browse Source 
Aktualisierung meiner Doku
This commit is contained in:
Micha
2026-04-15 12:21:02 +02:00
parent 736aef160e
commit d362a9ab4c
3 changed files with 203 additions and 145 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/WORKFLOW.md
+148 -101
View File
@@ -1,6 +1,6 @@
# Workflow — GitOps / No-Drift Regeln
# Workflow - GitOps / No-Drift Regeln
Dieses Dokument definiert den verbindlichen Arbeitsablauf für Änderungen an der Homelab-Infrastruktur.
Dieses Dokument definiert den verbindlichen Arbeitsablauf fuer Aenderungen an der Homelab-Infrastruktur.
---
@@ -8,7 +8,8 @@ Dieses Dokument definiert den verbindlichen Arbeitsablauf für Änderungen an de
Es darf **keine dauerhafte Abweichung** zwischen:
- Git-Repository
- Gitea Online
- lokalem Clone
- Komodo-Stacks
- laufenden Docker-Containern
- Host-Konfiguration
@@ -17,45 +18,124 @@ geben.
**Grundsatz:**
> Git ist die einzige Quelle der Wahrheit.
> Gitea Online ist die operative Quelle der Wahrheit.
---
## Die wichtigste Regel
## Betriebsmodell
Änderungen werden immer in dieser Reihenfolge durchgeführt:
Die Rollen sind bewusst getrennt:
1. **Änderung im Repository** (Gitea)
2. **Commit**
3. **Push**
4. **Deploy über Komodo** (GitOps-Sync)
5. **Test**
6. **Dokumentation aktualisieren**
- **Gitea Online** ist `origin` und damit der verbindliche Sollzustand.
- Der **lokale Clone** ist die Arbeitskopie fuer Aenderungen.
- **Komodo** deployed aus Gitea und ist kein Bearbeitungsort.
- Der **Host** ist Laufzeit, nicht Quelle der Wahrheit.
### Operative Hierarchie
1. `origin/master` in Gitea
2. lokaler Clone auf dem Windows-PC
3. Komodo-Deployments / Webhooks
4. laufende Container und Host-Dateien
Wenn diese Ebenen voneinander abweichen, gewinnt immer zuerst Git und nicht der manuelle Live-Zustand.
---
## Standard-Workflow
Aenderungen werden immer in dieser Reihenfolge durchgefuehrt:
1. Lokal synchronisieren
2. Lokal aendern
3. Commit erzeugen
4. Push nach Gitea
5. Komodo reagiert automatisch per Webhook
6. Ergebnis testen
7. Doku pruefen und nachziehen
---
## Standardwerkzeug fuer den Alltag
Der bevorzugte lokale Workflow ist:
- **GitHub Desktop** fuer `Fetch`, `Pull`, `Commit`, `Push`
- Editor nach Wahl fuer Datei-Aenderungen
- Gitea Web fuer Historie, Review und kleine Notfaelle
- Komodo nur fuer Deploy-Status, Logs und Stack-Sicht
### Tagesablauf mit GitHub Desktop
Vor lokaler Arbeit:
1. GitHub Desktop oeffnen
2. `Fetch origin`
3. wenn noetig `Pull origin`
Nach lokaler Arbeit:
1. Aenderungen pruefen
2. Commit mit sauberer Nachricht
3. `Push origin`
4. Komodo-Webhook im Hinterkopf behalten
---
## Wenn online in Gitea gearbeitet wurde
Web-Aenderungen in Gitea sind erlaubt, aber nicht der Normalfall.
Wenn online etwas geaendert wurde, gilt **vor der naechsten lokalen Arbeit**:
1. GitHub Desktop oeffnen
2. `Fetch origin`
3. `Pull origin`
4. erst dann lokal weiterarbeiten
Sonst entsteht Drift zwischen Gitea Online und lokalem Clone.
---
## Komodo-Regeln
Komodo ist in diesem Setup:
- primaeres Deployment-Werkzeug
- GitOps-Consumer fuer die Stacks
- Monitoring- und Status-Werkzeug
### Deshalb gilt
- Stack-Konfiguration nur im Repository anpassen
- nicht im Komodo-Web-Editor arbeiten
- Pushes koennen automatisch einen Komodo-Deploy ausloesen
- wenn Komodo und Git voneinander abweichen, gewinnt Git
---
## Verbotene Arbeitsweise
Folgende Dinge sind grundsätzlich zu vermeiden:
Folgende Dinge sind grundsaetzlich zu vermeiden:
- Änderungen direkt im Komodo- oder Portainer-Web-Editor
- Änderungen direkt per `docker run`
- Änderungen an laufenden Containern ohne Repo-Anpassung
- Aenderungen direkt im Komodo-Web-Editor
- Aenderungen direkt per `docker run`
- Aenderungen an laufenden Containern ohne Repo-Anpassung
- spontane Host-Hotfixes ohne Nachdokumentation
- Secrets im Git-Repository
- mehrere Services gleichzeitig migrieren
- mehrere kritische Dienste gleichzeitig migrieren
---
## Erlaubte Arbeitsweise
Erlaubt und gewünscht sind:
Erlaubt und gewuenscht 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
- Aenderungen an Compose-Dateien im Git-Repo
- Commit + Push vor jedem produktiven Deploy
- GitHub Desktop als Standardweg fuer den lokalen Sync
- Gitea Web fuer Review, Historie und kleine Hotfixes
- Host-Hotfixes nur im Ausnahmefall mit sofortiger Nachpflege im Repo
---
@@ -67,10 +147,11 @@ Erlaubt und gewünscht sind:
Beispiele:
- laufender Container wurde manuell verändert
- laufender Container wurde manuell veraendert
- lokaler Clone ist nicht mehr auf dem Stand von `origin/master`
- 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
- Traefik dynamic config wurde lokal geaendert, aber Git weiss nichts davon
### Regel
@@ -79,52 +160,36 @@ 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
- Repo an Realitaet anpassen
- oder Realitaet an Repo zurueckfuehren
4. erst danach weiterarbeiten
---
## Ausnahmefall: Hotfix auf dem Host
Manchmal ist ein Live-Hotfix nötig. Das ist erlaubt, aber nur unter diesen Bedingungen:
Manchmal ist ein Live-Hotfix noetig. 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
2. Aenderung sofort dokumentieren
3. Aenderung danach ins Git-Modell ueberfuehren
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?
- Was wurde geaendert?
- Wo wurde es geaendert?
- Warum war es noetig?
- Muss diese Aenderung ins Repo uebernommen werden?
- Ist ein Rollback dokumentiert?
---
## Komodo-Regeln
## Ausnahme: Traefik Dynamic Config
Komodo ist in diesem Setup:
> **Diese Dateien werden von Komodo nicht automatisch deployed.**
- **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.
Komodo deployed ausschliesslich `docker-compose.yml`-Dateien. Die Traefik-Konfigurationsdateien unter `traefik/dynamic/` im Git-Repo werden **nicht** automatisch auf den Host uebertragen.
### Betroffene Dateien
@@ -134,31 +199,15 @@ Komodo deployt ausschließlich `docker-compose.yml`-Dateien. Die Traefik-Konfigu
| `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
### Pflicht-Workflow bei Aenderungen an Traefik Dynamic Config
1. Datei im Git-Repo (`traefik/dynamic/`) ändern
1. Datei im Git-Repo (`traefik/dynamic/`) aendern
2. Commit + Push
3. **Manuell auf den Host kopieren:**
```bash
cp /mnt/user/homelab-infra/traefik/dynamic/middlewares.yml \
/mnt/user/appdata/traefik/dynamic/middlewares.yml
```
4. Traefik lädt dynamic config automatisch neu (kein Neustart nötig)
5. Änderung testen
3. Datei manuell auf den Host kopieren
4. Traefik laedt dynamic config automatisch neu
5. Aenderung 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.
> **Merksatz:** Git-Commit allein reicht hier nicht. Ohne den manuellen Kopier-Schritt wirkt die Aenderung nicht.
---
@@ -166,19 +215,20 @@ Portainer ist **nicht** mehr die Quelle der Wahrheit und wird nur noch als Fallb
- 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
- Secrets werden ueber 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
## DNS-Regeln fuer 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`).
Nicht alle Container koennen externe DNS-Namen aufloesen. Standardmaessig nutzt Docker `127.0.0.11` als internen DNS-Resolver. In bestimmten Netzwerk-Setups schlaegt externe Namensaufloesung 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:
Container die **externe Domains aufloesen muessen** erhalten explizit:
```yaml
dns:
- 1.1.1.1
@@ -192,20 +242,16 @@ dns:
| `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:
Nach jeder erfolgreichen Migration oder relevanten Aenderung muessen diese Dateien geprueft werden:
- `docs/MIGRATION_LOG.md`
- `docs/SECRETS_MAP.md`
- `docs/ROLLBACK.md`
- `HOMELAB_ARCHITECTURE_MASTER_V2.md` (falls Architektur betroffen)
- `HOMELAB_ARCHITECTURE_MASTER_V2.md` falls Architektur betroffen ist
---
@@ -213,33 +259,34 @@ Nach jeder erfolgreichen Migration oder relevanten Änderung müssen diese Datei
Jede Migration wird als Sprint behandelt. Ein Sprint umfasst immer:
1. Ist-Zustand prüfen
2. Zielzustand definieren (in `HOMELAB_ARCHITECTURE_MASTER_V2.md`)
1. Ist-Zustand pruefen
2. Zielzustand definieren
3. Compose-Datei im Repo anpassen
4. Commit + Push
5. Deploy über Komodo
6. Test
7. Dokumentation aktualisieren
8. Sprint abschließen
4. lokal synchronisieren und aendern
5. Commit + Push
6. Deploy ueber Komodo
7. Test
8. Doku aktualisieren
9. Sprint abschliessen
> Nie mehrere kritische Dienste gleichzeitig ändern.
> Nie mehrere kritische Dienste gleichzeitig aendern.
---
## Rollback-Regel
Jede Änderung muss rückrollbar sein. Vor jedem Deploy muss klar sein:
Jede Aenderung muss rueckrollbar 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
- ob Datenpfade unveraendert bleiben
- wie der Dienst im Fehlerfall zurueckgenommen wird
Wenn Rollback nicht klar ist, wird nicht deployt.
Wenn Rollback nicht klar ist, wird nicht deployed.
---
## Arbeitsregel für KI-Assistenten
## Arbeitsregel fuer KI-Assistenten
Wenn mit einer KI gearbeitet wird, gilt immer:
@@ -249,12 +296,12 @@ Wenn mit einer KI gearbeitet wird, gilt immer:
> 3. die betroffene Compose-Datei
> 4. ggf. `docs/MIGRATION_LOG.md`
Erst danach dürfen Änderungen vorgeschlagen werden.
Erst danach duerfen Aenderungen vorgeschlagen werden.
---
## Merksatz
> Erst syncen, dann aendern.
> Erst Git, dann Deploy.
> Erst Wahrheit, dann Aktion.
> Kein Drift, kein Chaos.
> Kein Drift, kein Chaos.