diff --git a/HOMELAB_ARCHITECTURE_MASTER_V2.md b/HOMELAB_ARCHITECTURE_MASTER_V2.md index 22efcca..358bfcf 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-04-17 | **Aktueller Schwerpunkt:** GitOps / Doku-Synchronisierung / Reproduzierbare Deployments +**Stand:** 2026-05-16 | **Aktueller Schwerpunkt:** GitOps / Doku-Synchronisierung / Reproduzierbare Deployments --- @@ -52,7 +52,7 @@ Kein Webdienst veröffentlicht finale direkte Host-Ports außer `traefik` selbst ### P2 — Das Setup bleibt bewusst einfach: `frontend_net` + `backend_net` + app-interne Netze - `frontend_net` = Proxy-/Web-Netz - `backend_net` = intern für DB/Cache/App-Kommunikation -- zusätzliche Netze nur app-intern, wenn technisch nötig (`mealie_mealie_internal`, `immich_default`, `dns_net`) +- zusätzliche Netze nur app-intern, wenn technisch nötig (`mealie_internal`, `immich_default`, `dns_net`) Es gibt **keine künstlichen globalen Zusatznetze** wie `admin_net`, `monitoring_net` oder `media_net`. @@ -87,7 +87,7 @@ Jeder produktive Container nutzt `restart: unless-stopped`, außer eine Ausnahme | `frontend_net` | bridge, external | einziges Traefik-/Web-Netz | Standard | | `backend_net` | bridge, `internal: true` | interne App-/DB-/Cache-Kommunikation | Standard | | `dns_net` | bridge | Resolver-Schicht: AdGuard Home + Unbound | bleibt | -| `mealie_mealie_internal` | bridge, `internal: true` | internes Netz nur für `mealie` + `mealie-postgres` | ✅ umgesetzt | +| `mealie_internal` | bridge, `internal: true` | internes Netz nur für `mealie` + `mealie-postgres` | ✅ umgesetzt | | `immich_default` | Compose-intern, `internal: true` | internes Immich-Netz | ✅ umgesetzt | | `nextcloud_internal` | bridge, `internal: true` | internes Netz nur fuer `nextcloud` + `nextcloud-postgres` + `nextcloud-redis` | ✅ vorbereitet | | `grafana_influx_internal` | Compose-intern, `internal: true` | interne Grafana-zu-InfluxDB-Kommunikation | ✅ umgesetzt | @@ -118,7 +118,7 @@ dns_net └── unbound App-interne Netze -├── mealie_mealie_internal (internal: true) ✅ +├── mealie_internal (internal: true) ✅ ├── immich_default (internal: true) ✅ ├── nextcloud_internal (internal: true) ✅ ├── grafana_influx_internal (internal: true) @@ -254,7 +254,7 @@ Legende Status: |---|---|---|---|---|---| | `postgresql17` | ✅ | `backend_net` | intern | kein Host-Port, `POSTGRES_PASSWORD_FILE` | — | | `Redis` | ✅ | `backend_net` | intern | intern-only Cache | optional named volume | -| `mealie-postgres` | ✅ | `mealie_mealie_internal` | intern | isoliert, nie `frontend_net` | — | +| `mealie-postgres` | ✅ | `mealie_internal` | intern | isoliert, nie `frontend_net` | — | | `immich_postgres` | ✅ | `immich_default` | intern | intern-only | — | | `immich_redis` | ⏳ | `immich_default` | intern | intern-only | anonymes Volume → named volume | | `nextcloud-postgres` | ✅ | `nextcloud_internal` | intern | app-eigene Nextcloud-Datenbank mit `_FILE`-Secret | — | @@ -266,7 +266,7 @@ Legende Status: |---|---|---|---|---|---| | `paperless-ngx` | ✅ | `frontend_net`, `backend_net` | Traefik | aktiv via `paperless.kaleschke.info` | — | | `mail-archiver` | ✅ | `frontend_net`, `backend_net` | Traefik + Middleware | aktiv via `mail.kaleschke.info`; IMAP-Abruf + DB-Zugang; App-eigene Auth bleibt zusaetzliche Schutzschicht | — | -| `mealie` | ✅ | `frontend_net`, `mealie_mealie_internal` | Traefik | sauber getrennte App/DB-Struktur | — | +| `mealie` | ✅ | `frontend_net`, `mealie_internal` | Traefik | sauber getrennte App/DB-Struktur | — | | `ntfy` | ✅ | `frontend_net` | Traefik | aktiv via `ntfy.kaleschke.info`, Git-Stack | — | | `gitea` | ✅ | `frontend_net` | Traefik + SSH-Port 222 | Web via Traefik, SSH direkt gebunden | — | | `immich_server` | ✅ | `immich_default`, `frontend_net` | Traefik | aktiv via `immich.kaleschke.info` | — | @@ -577,7 +577,7 @@ Benötigt `backend_net` (PostgreSQL) + `frontend_net` (IMAP-Abruf von GMX/Gmail) - App → `frontend_net` + internes Netzwerk - Datenbank → nur internes Netzwerk (`internal: true`) -Beispiel (Mealie): `mealie` → `frontend_net` + `mealie_mealie_internal`, `mealie-postgres` → nur `mealie_mealie_internal`. +Beispiel (Mealie): `mealie` → `frontend_net` + `mealie_internal`, `mealie-postgres` → nur `mealie_internal`. --- diff --git a/docs/REPO_MAP.md b/docs/REPO_MAP.md index 1cb9421..9d7af6c 100644 --- a/docs/REPO_MAP.md +++ b/docs/REPO_MAP.md @@ -30,8 +30,8 @@ Secret-Werte werden hier nicht dokumentiert. Aufgefuehrt werden nur Variablennam | `docs/WORKFLOW.md` | GitOps-/No-Drift-Arbeitsregeln | | `docs/GITOPS_DRIFT_RUNBOOK.md` | Pflichtmatrix fuer Git/Gitea/Komodo/Docker/Host-Drift | | `docs/DISASTER_RECOVERY.md` | Wiederanlauf nach Host-/Systemausfall | -| `docs/RESTORE_MATRIX.md` | Restore-Quellen und Smoke-Tests je Dienst | -| `docs/ROLLBACK.md` | Rueckweg im GitOps-Betrieb | +| `docs/RESTORE_MATRIX.md` | Restore-Quellen, Dump-Artefakte und Smoke-Tests je Dienst | +| `docs/ROLLBACK.md` | Rueckweg bei Fehlern im GitOps-Betrieb | | `docs/SECRETS_MAP.md` | Secret-Namen, Pfade und Einbindungsarten ohne Werte | | `docs/HOME_ASSISTANT_INFLUXDB_ECOWITT.md` | Home Assistant -> InfluxDB 3 -> Grafana Ablauf | | `docs/AI_CONTEXT.md` | Gesamtverstaendnis fuer KI-Agenten | @@ -152,7 +152,7 @@ Secret-Werte werden hier nicht dokumentiert. Aufgefuehrt werden nur Variablennam | `backend_net` | external/internal laut Architektur | PostgreSQL 17, Redis, Authelia, Paperless, Mail Archiver, Traefik, Loki, Alloy, Grafana-Loki-Datasource | | `dns_net` | App-/Host-Netz | AdGuard Home und Unbound | | `immich_default` | Compose-intern, `internal: true` | Immich Server, ML, Postgres, Redis | -| `mealie_internal` | Compose-intern | Mealie und Mealie Postgres | +| `mealie_internal` | Compose-intern; Laufzeitname mit Compose-Projektpraefix typischerweise `mealie_mealie_internal` | Mealie und Mealie Postgres | | `nextcloud_internal` | Compose-intern | Nextcloud, Nextcloud Postgres, Nextcloud Redis | | `grafana_influx_internal` | Compose-intern, `internal: true` | Grafana und InfluxDB | | `grafana_influx_lan` | Compose-intern bridge | InfluxDB Host-Port-Publishing fuer LAN Writer | @@ -227,7 +227,6 @@ Das Skript liest Secret-Dateien auf dem Host und schreibt Dump-Artefakte. Bei An - Echte `stack.env`- und `.env`-Dateien sind per `.gitignore` ausgeschlossen; nur `*.example`-Dateien gehoeren ins Repo. - Authelia `configuration.yml` ist Repo-Baseline fuer nicht geheime Einstellungen, wird aber nicht automatisch von Komodo auf den Host kopiert. Die produktive Host-Datei kann zusaetzliche OIDC-/Secret-Konfiguration enthalten; Aenderungen muessen manuell gemerged und validiert werden. -- `apps/mealie` nutzt in Compose `mealie_internal`; Architektur-Doku nennt teils `mealie_mealie_internal`. Laufzeitnamen koennen durch Compose-Projektpraefixe abweichen. - `backend_net` ist in der Architektur als `internal: true` beschrieben; einzelne Compose-Dateien referenzieren es external. Live-Netz-Attribute bei Drift-Fragen pruefen. - Einige Images bleiben trotz Digest-Pin semantisch auf mutable Tags (`latest@sha256`, `release@sha256`). Das ist bewusst dokumentiert, aber bei Updates gesondert pruefen. - Stateful Datenhalter sind seit 2026-05-05 bevorzugt mit Minor-/Patch-Tag plus Digest gepinnt; Redis-Caches wurden im Hardening-Sprint 2026-05-16 auf `redis:7.4-alpine@sha256:...` vereinheitlicht. diff --git a/docs/SECRETS_MAP.md b/docs/SECRETS_MAP.md index 3d0cc3a..9d92f94 100644 --- a/docs/SECRETS_MAP.md +++ b/docs/SECRETS_MAP.md @@ -33,6 +33,7 @@ Dieses Dokument listet sensible Daten, deren Ablageorte und die vorgesehene Einb | mail-archiver | Auth Password | Stack ENV `${MAILARCHIVER_AUTH_PASSWORD}` | aktiv | | Authelia | JWT Secret | `/mnt/user/appdata/secrets/authelia_jwt_secret.txt` -> `AUTHELIA_JWT_SECRET_FILE` | aktiv | | Authelia | Session Secret | `/mnt/user/appdata/secrets/authelia_session_secret.txt` -> `AUTHELIA_SESSION_SECRET_FILE` | aktiv | +| Authelia | SMTP Password | `/mnt/user/appdata/secrets/authelia_smtp_password.txt` -> Host-Secret fuer SMTP-Notifier | aktiv | | Authelia | Storage Encryption Key | `/mnt/user/appdata/secrets/authelia_storage_encryption_key.txt` -> `AUTHELIA_STORAGE_ENCRYPTION_KEY_FILE` | aktiv | | Authelia | Postgres Password | `/mnt/user/appdata/secrets/authelia_postgres_password.txt` -> `AUTHELIA_STORAGE_POSTGRES_PASSWORD_FILE` | aktiv | | Komodo Mongo | Root Password | `/mnt/user/appdata/secrets/komodo_mongo_password.txt` -> `MONGO_INITDB_ROOT_PASSWORD_FILE` | aktiv | @@ -68,6 +69,7 @@ Dieses Dokument listet sensible Daten, deren Ablageorte und die vorgesehene Einb |-- authelia_jwt_secret.txt |-- authelia_postgres_password.txt |-- authelia_session_secret.txt +|-- authelia_smtp_password.txt |-- authelia_storage_encryption_key.txt |-- immich_postgres_password.txt |-- komodo_mongo_password.txt diff --git a/docs/WORKFLOW.md b/docs/WORKFLOW.md index b7cf7ae..706c7c6 100644 --- a/docs/WORKFLOW.md +++ b/docs/WORKFLOW.md @@ -306,24 +306,6 @@ Nach jeder erfolgreichen Migration oder relevanten Aenderung muessen diese Datei --- -## Sprint-Regel - -Jede Migration wird als Sprint behandelt. Ein Sprint umfasst immer: - -1. Ist-Zustand pruefen -2. Zielzustand definieren -3. Compose-Datei im Repo anpassen -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 aendern. - ---- - ## Rollback-Regel Jede Aenderung muss rueckrollbar sein. Vor jedem Deploy muss klar sein: