diff --git a/HOMELAB_ARCHITECTURE_MASTER_V2.md b/HOMELAB_ARCHITECTURE_MASTER_V2.md index 17434e4..e42c321 100644 --- a/HOMELAB_ARCHITECTURE_MASTER_V2.md +++ b/HOMELAB_ARCHITECTURE_MASTER_V2.md @@ -16,7 +16,7 @@ 6. [Einordnungsschema für neue Container](#6-einordnungsschema-für-neue-container) 7. [Container-Zielbild (vollständig)](#7-container-zielbild-vollständig) 8. [Traefik-Label-Standard](#8-traefik-label-standard) -9. [Migrationsstrategie (Blöcke A–F)](#9-migrationsstrategie-blöcke-af) +9. [Historische Migration (abgeschlossen)](#9-historische-migration-abgeschlossen) 10. [Bekannte Ausnahmen und Begründungen](#10-bekannte-ausnahmen-und-begründungen) 11. [Projektorganisation und Arbeitsmodus](#11-projektorganisation-und-arbeitsmodus) 12. [Nutzung mit KI / Kontext-Regel](#12-nutzung-mit-ki--kontext-regel) @@ -60,7 +60,7 @@ Es gibt **keine künstlichen globalen Zusatznetze** wie `admin_net`, `monitoring Postgres, Redis und ähnliche Dienste laufen ausschließlich in `backend_net` oder einem eigenen internen Compose-Netz. ### P4 — Admin-UIs sind nicht öffentlich -Komodo, filebrowser, scrutiny, UptimeKuma, code-server, Traefik-Dashboard, backrest, borg-ui und beszel sind standardmäßig **Tailscale-only** oder hinter Traefik **mit zentraler Middleware** abgesichert. +Komodo, filebrowser, scrutiny, UptimeKuma, code-server, Traefik-Dashboard, backrest und borg-ui sind standardmäßig **Tailscale-only** oder hinter Traefik **mit zentraler Middleware** abgesichert. ### P5 — Compose-first Alle produktiven Container werden als Compose verwaltet. Bestehende Dockerman-/Ad-hoc-Container werden schrittweise migriert. @@ -100,7 +100,7 @@ traefik (80/443) │ └── frontend_net ├── öffentliche Apps (vaultwarden, mealie, paperless, immich, gitea, ntfy, homepage) - ├── Admin-UIs mit Middleware (komodo, uptime-kuma, filebrowser, scrutiny, code-server, backrest, borg-ui, beszel) + ├── Admin-UIs mit Middleware (komodo, uptime-kuma, filebrowser, scrutiny, code-server, backrest, borg-ui) └── Hybrid-Dienste mit Internetbedarf (mail-archiver, ddns-updater) backend_net (internal: true) @@ -119,8 +119,8 @@ App-interne Netze Host-Sonderfälle ├── tailscale -├── Plex-Media-Server -└── beszel-agent +└── Plex-Media-Server + ``` --- @@ -146,7 +146,6 @@ Diese Dienste sind **keine Public Apps**: - `filebrowser` — files.kaleschke.info (Middleware) - `scrutiny` — scrutiny.kaleschke.info (Middleware) - `code-server` — Traefik + Middleware -- `beszel` — beszel.kaleschke.info (Middleware ausstehend) - `backrest` — Traefik + Middleware - `borg-ui` — borg.kaleschke.info (Middleware) - `Traefik-Dashboard` @@ -273,15 +272,12 @@ Legende Status: |---|---|---|---|---|---| | `UptimeKuma` | ✅ | `frontend_net` | Traefik + Middleware | aktiv via `uptime.kaleschke.info` | — | | `scrutiny` | ✅ | `frontend_net` | Traefik + Middleware | aktiv via `scrutiny.kaleschke.info`, Git-Stack | `privileged` später prüfen | -| `beszel` | ✅ | `frontend_net` | Traefik | aktiv via `beszel.kaleschke.info`, Git-Stack | Admin-Middleware ergänzen (Block F) | -| `beszel-agent` | ✅ | `host` | intern | System-Monitoring, Socket-Zugriff auf Host | — | -### 7.7 Sprint 5 — noch zu migrieren / abzuschalten +### 7.7 Noch offene Sonderfälle | Container | Status | Ziel | |---|---|---| | `Plex-Media-Server` | ⏳ Dockerman | Compose-Migration, `host`-Netz bleibt (Discovery) | -| `PortainerCE` | ✅ abgeschlossen | 2026-03-29 abgeschaltet | ### 7.8 Entfernte Container @@ -293,14 +289,16 @@ Legende Status: | `diun` | 2026-03-28 | Update-Monitoring via Komodo; Stack + Netz `diun_diun_default` + Repo-Eintrag entfernt | | `binhex-official-pihole` | 2026-03-28 | ersetzt durch AdGuard Home + Unbound | | `gotify` | 2026-03-28 | nicht mehr aktiv; Push-Notifications via ntfy abgedeckt | -| `Dozzle` | 2026-03-28 | nicht mehr aktiv; Log-Monitoring via Komodo/beszel | -| `dashdot` | 2026-03-28 | nicht mehr aktiv; System-Monitoring via beszel | -| `netdata` | 2026-03-28 | nicht mehr aktiv; System-Monitoring via beszel | +| `Dozzle` | 2026-03-28 | nicht mehr aktiv | +| `dashdot` | 2026-03-28 | nicht mehr aktiv | +| `netdata` | 2026-03-28 | nicht mehr aktiv | | `Glances` | 2026-03-28 | nicht mehr aktiv | | `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 | +| `beszel` | nicht dokumentiert | bereits entfernt; nicht mehr Teil des Zielbilds | +| `beszel-agent` | nicht dokumentiert | bereits entfernt; nicht mehr Teil des Zielbilds | --- @@ -334,105 +332,24 @@ labels: --- -## 9. Migrationsstrategie (Blöcke A–F) +## 9. Historische Migration (abgeschlossen) -**Letzte Aktualisierung:** 2026-03-29 +Die frühere Blockmigration aus der Portainer-/Dockerman-Phase ist fachlich abgeschlossen. -### Block A — Quick Wins ✅ ABGESCHLOSSEN -```text -[x] restart: unless-stopped für alle Container gesetzt -[x] vaultwarden ADMIN_TOKEN-Doppelpräfix korrigiert -[x] backrest DNS-Hardcoding entfernt -[x] leere Netzwerke entfernt: br0, immich_net, kopia_default, netbox_default, diun_default -[x] anonyme/verwaiste Volumes bereinigt -[x] scanopy komplett entfernt (3 Container + 2 Volumes + Netz) -[x] binhex-official-pihole entfernt → ersetzt durch AdGuard Home + Unbound -``` +Dieser Abschnitt dient nur noch als **historischer Vermerk**: -### Block B — Kritische Kernmigrationen ✅ ABGESCHLOSSEN -```text -[x] vaultwarden - frontend_net, Host-Port entfernt, ADMIN_TOKEN_FILE, Traefik aktiv -[x] postgresql17 - Port 5432 entfernt, nur backend_net, POSTGRES_PASSWORD_FILE -[x] mealie-postgres - aus frontend_net raus, nur mealie_mealie_internal -``` +- Traefik läuft labelbasiert ohne Service-Routen im File-Provider. +- Komodo ist der einzige aktive Stack-Manager. +- Portainer CE ist entfernt. +- Borg/Borg UI, Dump-Automatisierung und Restore-Test sind produktiv eingeführt. +- Frühere Sprint-/Block-Checklisten werden hier **nicht mehr operativ gepflegt**. -### Block C — Frontend-Stack finalisieren ✅ ABGESCHLOSSEN -```text -[x] ntfy - Git-Stack - ntfy.kaleschke.info - Traefik aktiv -[x] paperless-ngx - traefik.enable=true - paperless.kaleschke.info - Port entfernt - tls=true -[x] Paperless-AI - traefik.enable=true - aktiv -[x] PortainerCE - traefik.enable=true - Middleware aktiv - direkte Ports entfernt -[x] UptimeKuma - traefik.enable=true - uptime.kaleschke.info - Port entfernt - Middleware aktiv -[x] filebrowser - frontend_net - traefik.enable=true - files.kaleschke.info - Port entfernt - Middleware aktiv -[x] scrutiny - frontend_net - traefik.enable=true - scrutiny.kaleschke.info - Git-Stack -[x] gitea - traefik.enable=true - git.kaleschke.info - SSH-Port 222 bleibt (Ausnahme dokumentiert) -[x] backrest - traefik.docker.network=frontend_net korrigiert (war backend_net — Routing-Bug) -[x] Traefik File-Provider bereinigt - immich.yml, gitea.yml, mealie.yml, scrutiny.yml, vaultwarden.yml.bak gelöscht -[x] immich Bad Gateway behoben - Traefik nutzt jetzt immich@docker statt immich@file -[x] AdGuard Home - Git-Stack - dns_net + frontend_net - Port 53 (DNS) + 3000 (Admin) -[x] beszel - Git-Stack - frontend_net - beszel.kaleschke.info - Traefik aktiv -[ ] beszel - Admin-Middleware (dashboard-auth@file) ergänzen -``` +Für den laufenden Betrieb gilt stattdessen: -### Block D — Dockerman-Container in Git-Stacks -```text -[x] vaultwarden ✅ -[x] postgresql17 ✅ -[x] mail-archiver ✅ -[x] scrutiny ✅ -[x] filebrowser ✅ -[x] tailscale ✅ -[x] AdGuard Home ✅ -[x] beszel ✅ -[x] ntfy ✅ -[x] homepage ✅ -[ ] Plex-Media-Server (Sprint 5) -``` - -### Block E — Secrets-Migration -```text -[x] vaultwarden → ADMIN_TOKEN_FILE ✅ -[x] postgresql17 → POSTGRES_PASSWORD_FILE ✅ -[x] mail-archiver → Stack ENV (${MAILARCHIVER_AUTH_PASSWORD}) ✅ -[x] mealie → Stack ENV (kein _FILE-Support) ✅ -[x] mealie-postgres → Stack ENV (kein _FILE-Support) ✅ -[x] paperless-ngx → Stack ENV (${PAPERLESS_DBPASS}) ✅ -[x] code-server → PASSWORD_FILE ✅ -[x] immich_server → Stack ENV (${IMMICH_DB_PASSWORD}) ✅ -[x] immich_postgres → POSTGRES_PASSWORD_FILE ✅ -[ ] immich_redis → anonymes Volume → named volume -``` - -### Block F — Feinschliff / Hardening -```text -[x] immich_default - internal: true gesetzt (2026-03-29) -[x] PortainerCE - abgeschaltet (Sprint 5, 2026-03-29) -[ ] immich_redis - anonymes Volume → named volume in Compose -[ ] immich_server - anonymes Volume prüfen und benennen -[ ] backrest - /mnt/user doppelt gemountet (ro + rw) - rw-Mount auf konkrete Pfade einschränken -[ ] filebrowser - /mnt/user:/srv ist sehr breit - auf /mnt/user/documents:/srv einschränken wenn möglich -[ ] Redis - optional named volume -[ ] scrutiny - später prüfen, ob privileged reduziert werden kann -[ ] tailscale - TS_USERSPACE/privileged bereinigen wenn möglich -[ ] beszel - Admin-Middleware (dashboard-auth@file) ergänzen -[ ] AdGuard Home - Admin-Port 3000 per Traefik + Middleware absichern (aktuell direkter Port) -``` - -### Block G — Authelia SSO/2FA (Sprint 7) -```text -[x] security/authelia/docker-compose.yml im Repo (2026-03-29) -[x] security/authelia/configuration.yml im Repo (2026-03-29) -[x] traefik/dynamic/middlewares.yml - authelia ForwardAuth Middleware ergänzt (2026-03-29) -[ ] NAS: Secrets anlegen (jwt_secret, session_secret, storage_encryption_key, postgres_password) -[ ] NAS: Authelia PostgreSQL-User und -Datenbank anlegen -[ ] NAS: /mnt/user/appdata/authelia/config/configuration.yml aus Repo übernehmen -[ ] NAS: users_database.yml mit gehashten Passwörtern anlegen -[ ] NAS: DNS-Eintrag auth.kaleschke.info in AdGuard setzen -[ ] Komodo: Stack security/authelia deployen -[ ] Services schrittweise mit authelia@docker Middleware absichern -``` - ---- +- Zielbild und Architektur in diesem Dokument +- Git-/Komodo-Ablauf in `docs/WORKFLOW.md` +- fachliche Änderungen in der jeweils betroffenen Stack-Doku +- Entscheidungen und besondere Umstellungen im Entscheidungs-Log unten ## 10. Bekannte Ausnahmen und Begründungen @@ -443,7 +360,6 @@ labels: | `AdGuard Home` | Port 53 (TCP/UDP) direkt + Port 3000 Admin | DNS benötigt direkten Port 53; kein HTTP-Proxy für DNS möglich | | `Plex-Media-Server` | `host` | Discovery / mDNS / Plex GDM | | `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 | | `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` | @@ -454,32 +370,27 @@ labels: ## 11. Projektorganisation und Arbeitsmodus ### 11.1 Unser Arbeitsprinzip -Dieses Projekt wird **blockweise** umgesetzt, nicht wild containerweise. +Dieses Projekt wird heute nicht mehr sprintweise im Dokument gesteuert, sondern über einen stabilen GitOps-Betrieb. -### 11.2 Reihenfolge der Umsetzung - -| Sprint | Inhalt | Status | -|---|---|---| -| Sprint 1 | Quick Wins + `vaultwarden` | ✅ Abgeschlossen | -| Sprint 2 | `postgresql17` + `diun/gotify` | ✅ Abgeschlossen | -| Sprint 3 | `mealie` / `mealie-postgres` + `mail-archiver` | ✅ Abgeschlossen | -| Sprint 4 | Frontend-Stack (`paperless`, `PortainerCE`, `Dozzle`, `dashdot`, `scrutiny`, `filebrowser`, `gitea`, `UptimeKuma`, `ntfy`, `beszel`) + Traefik File-Provider Bereinigung + Komodo Einführung + AdGuard Home Migration + Pi-hole Ablösung | ✅ Abgeschlossen | -| Sprint 5 | `Plex-Media-Server` Compose-Migration + `PortainerCE` abschalten | ✅ Abgeschlossen | -| Sprint 6 | Hardening / Secrets / Volumes / Sonderfälle (`immich_default` ✅, Volumes, Mounts, AdGuard Traefik) | ✅ Abgeschlossen | -| Sprint 7 | `Authelia` SSO/2FA: Compose + Config im Repo, Traefik ForwardAuth Middleware, NAS-seitige Einrichtung | 🔄 In Bearbeitung | -| Sprint 8 | `borg-ui` Git-Stack + BorgBase Offsite-Backup-Workflow | 🔄 In Bearbeitung | +### 11.2 Operativer Ablauf +1. Zielbild prüfen +2. lokal synchronisieren +3. gezielt ändern +4. Commit + Push +5. Komodo-Webhook und Ergebnis prüfen +6. Dokumentation nachziehen ### 11.3 Regel für jede Änderung 1. Zielbild in diesem Dokument prüfen -2. nur den aktuellen Block anfassen -3. Compose-Datei ändern -4. deployen -5. testen -6. dokumentieren / abhaken -7. erst dann nächster Schritt +2. nur den betroffenen Bereich anfassen +3. Änderung lokal vorbereiten +4. nach Gitea pushen +5. automatische Reaktion von Komodo beachten +6. testen +7. dokumentieren ### 11.4 Source-of-Truth-Hierarchie -1. **Gitea Online (origin/master)** +1. **Gitea Online (`origin/master`)** 2. lokaler Clone / GitHub Desktop 3. Compose-Dateien im Git-Repo 4. Komodo als Deploy-Consumer @@ -490,9 +401,7 @@ Dieses Projekt wird **blockweise** umgesetzt, nicht wild containerweise. - 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. - ---- +- Wenn online in Gitea editiert wurde, muss vor der nächsten lokalen Änderung zuerst `Fetch origin` und danach `Pull origin` erfolgen. ## 12. Nutzung mit KI / Kontext-Regel