diff --git a/HOMELAB_ARCHITECTURE_MASTER_V2.md b/HOMELAB_ARCHITECTURE_MASTER_V2.md index 533d6cd..17434e4 100644 --- a/HOMELAB_ARCHITECTURE_MASTER_V2.md +++ b/HOMELAB_ARCHITECTURE_MASTER_V2.md @@ -3,7 +3,7 @@ > **Single Source of Truth** für Docker-Netzwerkarchitektur, Sicherheitsregeln, Zielbild und Migration des Kallilabcore-Homelabs. > **Arbeitsregel für KI-Assistenten:** Dieses Dokument immer zuerst lesen, bevor Fragen zu Containern, Netzwerken, Traefik, Tailscale, Migration oder Security beantwortet werden. -**Stand:** 2026-03-29 | **Aktueller Sprint:** 7 (Authelia SSO/2FA) — Sprints 1–6 abgeschlossen +**Stand:** 2026-04-15 | **Aktueller Schwerpunkt:** GitOps / Borg / Workflow-Konsolidierung --- @@ -37,7 +37,7 @@ | TLS | Let's Encrypt via Cloudflare DNS Challenge | | Certresolver | `le` | | Compose-Standard | Komodo (GitOps, Stack aus Gitea) | -| Legacy | Portainer CE (in Ablösung durch Komodo, Sprint 5) | +| Legacy | Portainer CE entfernt; Komodo ist alleiniger Stack-Manager | | Homelab-Compose-Pfad | `/mnt/user/services/homelab/` | | Secrets-Pfad | `/mnt/user/appdata/secrets/` | | Grundsatz | Keine neuen Dockerman-Einzelcontainer | @@ -66,7 +66,7 @@ Komodo, filebrowser, scrutiny, UptimeKuma, code-server, Traefik-Dashboard, backr Alle produktiven Container werden als Compose verwaltet. Bestehende Dockerman-/Ad-hoc-Container werden schrittweise migriert. ### P6 — Secrets nie im Klartext -Passwörter, Tokens und API-Keys gehören in Secret-Dateien unter `/mnt/user/appdata/secrets/` oder als Komodo/Portainer Environment Variables mit `${VARIABLE}` in der Compose. +Passwörter, Tokens und API-Keys gehören in Secret-Dateien unter `/mnt/user/appdata/secrets/` oder als Komodo Stack Environment Variables mit `${VARIABLE}` in der Compose. ### P7 — `restart: unless-stopped` ist Pflichtstandard Jeder produktive Container nutzt `restart: unless-stopped`, außer eine Ausnahme ist dokumentiert. @@ -74,7 +74,7 @@ Jeder produktive Container nutzt `restart: unless-stopped`, außer eine Ausnahme ### P8 — Least Privilege - `security_opt: ["no-new-privileges:true"]` standardmäßig ergänzen - `privileged: true` nur mit dokumentierter Begründung -- Docker-Socket standardmäßig vorsichtig behandeln; **Komodo/PortainerCE sind dokumentierte Ausnahmen** +- Docker-Socket standardmäßig vorsichtig behandeln; **Komodo ist dokumentierte Ausnahme** --- @@ -166,7 +166,7 @@ Wenn ein Dienst im `frontend_net` hängt, heißt das **nicht automatisch öffent 1. Keine produktiven Dienste im Docker-Default-`bridge` 2. Keine direkten Host-Ports für Web-UIs außer dokumentierte Ausnahmen 3. `restart: unless-stopped` als Standard -4. Secrets als Datei / `_FILE` oder Komodo/Portainer Environment Variables mit `${VAR}` +4. Secrets als Datei / `_FILE` oder Komodo Stack Environment Variables mit `${VAR}` 5. `no-new-privileges:true` ergänzen, wo praktikabel 6. `traefik.docker.network=frontend_net` immer explizit setzen 7. Admin-Dienste immer mit `dashboard-auth@file,secure-headers@file` @@ -262,7 +262,7 @@ Legende Status: |---|---|---|---|---|---| | `komodo` | ✅ | `frontend_net` | Traefik + Middleware | primärer GitOps-Stack-Manager | — | | `code-server` | ✅ | `frontend_net` | Traefik + Middleware | `PASSWORD_FILE` aktiv | — | -| `PortainerCE` | ⚠️ Legacy | `frontend_net` | Traefik + Middleware | wird durch Komodo abgelöst | abschalten Sprint 5 | +| `PortainerCE` | ❌ entfernt | - | - | 2026-03-29 abgeschaltet | historisch; nicht mehr deployen | | `filebrowser` | ✅ | `frontend_net` | Traefik + Middleware | aktiv via `files.kaleschke.info` | Mounts einschränken (Block F) | | `borg-ui` | 🔄 | `frontend_net` | Traefik + Middleware | Git-Stack für Borg/BorgBase-Backups; Borg UI bündelt Borg-CLI im Container | BorgBase-SSH-Key hinterlegen, erstes Repo initialisieren, Quell-Mounts bei Bedarf gezielt erweitern | | `mail-archiver` | ✅ | `frontend_net`, `backend_net` | intern | IMAP-Abruf + DB-Zugang, kein öffentlicher Zugang | — | @@ -281,7 +281,7 @@ Legende Status: | Container | Status | Ziel | |---|---|---| | `Plex-Media-Server` | ⏳ Dockerman | Compose-Migration, `host`-Netz bleibt (Discovery) | -| `PortainerCE` | ⚠️ Legacy | abschalten nach vollständiger Komodo-Übernahme | +| `PortainerCE` | ✅ abgeschlossen | 2026-03-29 abgeschaltet | ### 7.8 Entfernte Container @@ -300,6 +300,7 @@ Legende Status: | `netalertx` | 2026-03-28 | nicht mehr aktiv | | `luckyBackup` | 2026-03-28 | nicht mehr aktiv; Backup via backrest | | `Stash` | 2026-03-28 | nicht mehr aktiv | +| `PortainerCE` | 2026-03-29 | abgeschaltet; Komodo ist alleiniger Stack-Manager | --- @@ -444,7 +445,6 @@ labels: | `scrutiny` | `privileged: true` | SMART-Datenzugriff auf Laufwerke | | `beszel-agent` | `host` | direkter Host-Zugriff für System-Monitoring nötig | | `Komodo` | Docker-Socket Zugriff | Stack-Deployments benötigen Socket | -| `PortainerCE` | Docker-Socket | Legacy-UI; wird durch Komodo abgelöst | | `gitea` | SSH-Port 222 direkt gebunden | Git-SSH-Zugang; kein HTTP-Proxy für SSH möglich | | `ddns-updater` | bleibt in `frontend_net` statt `backend_net` | braucht Cloudflare-API-Zugang; `backend_net` ist `internal: true` | | `mail-archiver` | `frontend_net` + `backend_net` | braucht Internetzugang für IMAP-Abruf (GMX, Gmail) und DB-Zugang | @@ -479,10 +479,18 @@ Dieses Projekt wird **blockweise** umgesetzt, nicht wild containerweise. 7. erst dann nächster Schritt ### 11.4 Source-of-Truth-Hierarchie -1. **Dieses Dokument** -2. Compose-Dateien im Git-Repo -3. operative Checklisten -4. ad-hoc Notizen / Chat +1. **Gitea Online (origin/master)** +2. lokaler Clone / GitHub Desktop +3. Compose-Dateien im Git-Repo +4. Komodo als Deploy-Consumer +5. operative Checklisten und Notizen + +### 11.5 Operativer Git-Workflow +- Gitea Online ist der verbindliche Sollzustand. +- Lokal wird standardmäßig über GitHub Desktop gearbeitet. +- Komodo deployt aus Gitea und ist kein Bearbeitungsort. +- Webhooks sind aktiv: Ein Push kann unmittelbar einen Komodo-Deploy auslösen. +- Wenn online in Gitea editiert wurde, muss vor der nächsten lokalen Änderung zuerst Fetch origin und danach Pull origin erfolgen. --- @@ -518,9 +526,9 @@ Komodo ist nun der primäre GitOps-Stack-Manager: - **Komodo Core** läuft als Docker-Stack (`ops/komodo/docker-compose.yml`) - **Komodo Periphery** läuft auf dem Unraid-Host für direktes Server-Management - Stacks werden via Gitea synchronisiert und über Komodo deployed -- Portainer CE läuft noch als Legacy-UI und wird in Sprint 5 abgeschaltet +- Portainer CE ist abgeschaltet; Komodo ist der alleinige aktive Stack-Manager -**Vorteil gegenüber Portainer:** Sauberer GitOps-Flow ohne Web-Editor; alle Stack-Änderungen laufen über Git. +**Betriebsregel:** Alle Stack-Änderungen laufen über Git; Komodo konsumiert nur den Stand aus Gitea. ### AdGuard Home — Ablösung von Pi-hole (2026-03-28) `binhex-official-pihole` wurde entfernt und durch `AdGuard Home` + `unbound` ersetzt: diff --git a/README.md b/README.md index 2006116..087a9b7 100644 --- a/README.md +++ b/README.md @@ -1,53 +1,56 @@ # Homelab Infrastructure (KalliLab CORE) -Dieses Repository ist die zentrale Quelle ("Single Source of Truth") für die komplette Infrastruktur meines Homelabs. +Dieses Repository ist die zentrale Quelle ("Single Source of Truth") fuer die komplette Infrastruktur meines Homelabs. -## 🚨 WICHTIG – Einstieg +## WICHTIG - Einstieg -Vor jeder Änderung lesen: +Vor jeder Aenderung lesen: -1. 👉 HOMELAB_ARCHITECTURE_MASTER_V2.md -2. 👉 docs/WORKFLOW.md +1. `HOMELAB_ARCHITECTURE_MASTER_V2.md` +2. `docs/WORKFLOW.md` ## Architektur - Host: Unraid -- Container: Docker (Compose) +- Container: Docker Compose - Reverse Proxy: Traefik v3 (100% Docker-Labels, kein File-Provider mehr) - Zugriff: Tailscale (VPN) - DNS: AdGuard Home + Unbound -- GitOps: Gitea + Komodo (Stack-Manager) +- GitOps: Gitea + Komodo ## Grundprinzipien -- Alle Änderungen erfolgen über Git (Komodo deployed automatisch aus Gitea) -- Keine produktiven Container außerhalb von Compose -- Traefik ist der einzige öffentliche Einstiegspunkt -- Admin-Dienste sind nicht öffentlich erreichbar (nur via VPN oder Auth) -- Secrets werden niemals im Repository gespeichert +- Gitea Online ist der operative Sollzustand. +- Der lokale Clone ist die Arbeitskopie. +- Komodo deployed automatisch aus Gitea und ist kein Bearbeitungsort. +- Keine produktiven Container ausserhalb von Compose. +- Traefik ist der einzige oeffentliche Einstiegspunkt. +- Secrets werden niemals im Repository gespeichert. ## Repository-Struktur -- `core/` → Basisdienste (Gitea) -- `security/` → sicherheitskritische Dienste (Vaultwarden) -- `infra/` → Datenbanken & technische Services (PostgreSQL, Redis, DDNS-Updater) -- `apps/` → Anwendungen (Immich, Paperless, Mealie, Homepage, ...) -- `ops/` → Monitoring & Tools (Komodo, Scrutiny, Uptime-Kuma, Backrest, ...) -- `host-services/` → Dienste mit Host-Netz (AdGuard, Beszel, Tailscale, ...) -- `traefik/` → Reverse Proxy Konfiguration -- `docs/` → Dokumentation & Prozesse -- `env/` → Beispiel-Umgebungsvariablen +- `core/` -> Basisdienste (Gitea) +- `security/` -> sicherheitskritische Dienste +- `infra/` -> Datenbanken und technische Services +- `apps/` -> Anwendungen +- `ops/` -> Monitoring und Tools +- `host-services/` -> Dienste mit Host-Netz +- `traefik/` -> Reverse Proxy Konfiguration +- `docs/` -> Dokumentation und Prozesse +- `env/` -> Beispiel-Umgebungsvariablen -## Workflow +## Kurz-Workflow -1. Änderung im Repository (Git) -2. Commit & Push nach Gitea -3. Komodo deployed automatisch (GitOps) -4. Testen -5. Dokumentation aktualisieren +1. In GitHub Desktop `Fetch origin`. +2. Wenn noetig `Pull origin`. +3. Lokal aendern. +4. Commit erstellen. +5. `Push origin`. +6. Komodo-Webhook und Ergebnis pruefen. +7. Doku bei Bedarf aktualisieren. ## Status -GitOps-Migration (Sprint 1–4) abgeschlossen. Komodo ist primärer Stack-Manager. - -> ⚠️ Portainer CE läuft noch als Legacy-UI – wird in Sprint 5 abgeschaltet. +- Komodo ist der primaere und einzige produktive Stack-Manager. +- Portainer CE ist abgeschaltet und kein Teil des aktiven Betriebs mehr. +- Der verbindliche Detailablauf steht in `docs/WORKFLOW.md`. diff --git a/docs/WORKFLOW.md b/docs/WORKFLOW.md index 5b3bb7d..d180632 100644 --- a/docs/WORKFLOW.md +++ b/docs/WORKFLOW.md @@ -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. \ No newline at end of file +> Kein Drift, kein Chaos.