HOMELAB_ARCHITECTURE_MASTER_V2.md aktualisiert

This commit is contained in:
2026-03-29 07:56:38 +00:00
parent 9edb184065
commit 5274b5cb8b
+21 -56
View File
@@ -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-28 | **Aktueller Sprint:** 5 (Compose-Migration Dockerman-Container) — Sprints 14 abgeschlossen
**Stand:** 2026-03-28 | **Aktueller Sprint:** 5 (Plex-Migration + PortainerCE abschalten) — Sprints 14 abgeschlossen
---
@@ -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, Dozzle, filebrowser, scrutiny, UptimeKuma, dashdot, code-server, luckyBackup, Traefik-Dashboard, netdata, Glances, netalertx und beszel sind standardmäßig **Tailscale-only** oder hinter Traefik **mit zentraler Middleware** abgesichert.
Komodo, filebrowser, scrutiny, UptimeKuma, code-server, Traefik-Dashboard, backrest und beszel 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,8 +100,8 @@ Internet
traefik (80/443)
└── frontend_net
├── öffentliche Apps (vaultwarden, mealie, paperless, immich, gitea, gotify, ntfy, homepage)
├── Admin-UIs mit Middleware (komodo, dozzle, uptime-kuma, dashdot, filebrowser, scrutiny, code-server, beszel)
├── öffentliche Apps (vaultwarden, mealie, paperless, immich, gitea, ntfy, homepage)
├── Admin-UIs mit Middleware (komodo, uptime-kuma, filebrowser, scrutiny, code-server, backrest, beszel)
└── Hybrid-Dienste mit Internetbedarf (mail-archiver, ddns-updater)
backend_net (internal: true)
@@ -121,9 +121,6 @@ App-interne Netze
Host-Sonderfälle
├── tailscale
├── Plex-Media-Server
├── netdata
├── Glances
├── netalertx
└── beszel-agent
```
@@ -137,7 +134,6 @@ Diese Dienste sind über echte `*.kaleschke.info`-Domains erreichbar:
- `vaultwarden` — vault.kaleschke.info
- `mealie` — mealie.kaleschke.info
- `paperless-ngx` — paperless.kaleschke.info
- `gotify` — gotify.kaleschke.info
- `ntfy` — ntfy.kaleschke.info
- `gitea` (Web) — git.kaleschke.info
- `immich_server` — immich.kaleschke.info
@@ -147,19 +143,13 @@ Diese Dienste sind über echte `*.kaleschke.info`-Domains erreichbar:
Diese Dienste sind **keine Public Apps**:
- `Komodo` — komodo.kaleschke.info (Middleware)
- `Dozzle`
- `UptimeKuma` — uptime.kaleschke.info (Middleware)
- `dashdot`
- `filebrowser` — files.kaleschke.info (Middleware)
- `scrutiny` — scrutiny.kaleschke.info (Middleware)
- `luckyBackup`
- `code-server`
- `code-server` — Traefik + Middleware
- `beszel` — beszel.kaleschke.info (Middleware ausstehend)
- `backrest`
- `backrest` — Traefik + Middleware
- `Traefik-Dashboard`
- `netdata`
- `Glances`
- `netalertx`
- `AdGuard Home` — Port 3000 direkt (kein Traefik, nur LAN-Zugang)
### 4.3 Regel
@@ -260,7 +250,6 @@ Legende Status:
| `paperless-ngx` | ✅ | `frontend_net`, `backend_net` | Traefik | aktiv via `paperless.kaleschke.info` | — |
| `Paperless-AI` | ✅ | `frontend_net` | Traefik | aktiv | — |
| `mealie` | ✅ | `frontend_net`, `mealie_mealie_internal` | Traefik | sauber getrennte App/DB-Struktur | — |
| `gotify` | ✅ (Dockerman) | `frontend_net` | Traefik | aktiv via `gotify.kaleschke.info`, kein Host-Port | noch kein Git-Stack (Sprint 5) |
| `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` | `immich_default``internal: true` ausstehend |
@@ -273,11 +262,8 @@ 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 |
| `Dozzle` | ✅ (Dockerman) | `frontend_net` | Traefik + Middleware | keine Host-Ports | Git-Stack Sprint 5 |
| `dashdot` | ✅ (Dockerman) | `frontend_net` | Traefik + Middleware | aktiv, kein Host-Port | Git-Stack Sprint 5 |
| `filebrowser` | ✅ | `frontend_net` | Traefik + Middleware | aktiv via `files.kaleschke.info` | Mounts einschränken (Block F) |
| `mail-archiver` | ✅ | `frontend_net`, `backend_net` | intern | IMAP-Abruf + DB-Zugang, kein öffentlicher Zugang | — |
| `luckyBackup` | ⏳ | `frontend_net` | Traefik + Middleware | Sprint 5 | aus bridge → frontend_net, Traefik, Port entfernen |
### 7.6 Monitoring / Status
@@ -287,23 +273,12 @@ Legende Status:
| `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 | — |
| `Glances` | ✅ (Dockerman) | `host` | Tailscale-only | Host-Metriken | Git-Stack Sprint 5 |
| `netdata` | ✅ (Dockerman) | `host` | Tailscale-only | Host-Metriken | leere CLAIM-Vars entfernen, Git-Stack Sprint 5 |
| `netalertx` | ✅ (Dockerman) | `host` | Tailscale-only | Host-/Netzsicht | Git-Stack Sprint 5 |
### 7.7 Sprint 5 — noch zu migrieren (Dockerman → Git-Stack)
### 7.7 Sprint 5 — noch zu migrieren / abzuschalten
| Container | Status | Ziel |
|---|---|---|
| `gotify` | ✅ (Dockerman) | Git-Stack |
| `Dozzle` | ✅ (Dockerman) | Git-Stack |
| `dashdot` | ✅ (Dockerman) | Git-Stack |
| `Stash` | ⏳ | Compose-Migration |
| `netdata` | ✅ (Dockerman) | Git-Stack, CLAIM-Vars entfernen |
| `Glances` | ✅ (Dockerman) | Git-Stack |
| `netalertx` | ✅ (Dockerman) | Git-Stack |
| `Plex-Media-Server` | ⏳ | Compose-Migration, `host`-Netz bleibt (Discovery) |
| `luckyBackup` | ⏳ | Compose-Migration + Traefik + Port entfernen |
| `Plex-Media-Server` | Dockerman | Compose-Migration, `host`-Netz bleibt (Discovery) |
| `PortainerCE` | ⚠️ Legacy | abschalten nach vollständiger Komodo-Übernahme |
### 7.8 Entfernte Container
@@ -315,6 +290,14 @@ Legende Status:
| `scanopy-daemon` | 2026-03-26 | zusammen mit scanopy entfernt |
| `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 |
| `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 |
---
@@ -371,15 +354,12 @@ labels:
[x] mealie-postgres - aus frontend_net raus, nur mealie_mealie_internal
```
### Block C — Frontend-Stack finalisieren ✅ WEITGEHEND ABGESCHLOSSEN
### Block C — Frontend-Stack finalisieren ✅ ABGESCHLOSSEN
```text
[x] gotify - traefik.enable=true - gotify.kaleschke.info - Port entfernt
[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] Dozzle - traefik.enable=true - Middleware aktiv - direkte Ports entfernt
[x] dashdot - 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
@@ -389,7 +369,6 @@ labels:
[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
[ ] luckyBackup - aus bridge → frontend_net - traefik.enable=true - Middleware - Port entfernen
[ ] beszel - Admin-Middleware (dashboard-auth@file) ergänzen
```
@@ -405,15 +384,7 @@ labels:
[x] beszel ✅
[x] ntfy ✅
[x] homepage ✅
[ ] gotify
[ ] Dozzle
[ ] dashdot
[ ] luckyBackup
[ ] Stash
[ ] netdata
[ ] Glances
[ ] netalertx
[ ] Plex-Media-Server
[ ] Plex-Media-Server (Sprint 5)
```
### Block E — Secrets-Migration
@@ -423,13 +394,11 @@ labels:
[x] mail-archiver → Stack ENV (${MAILARCHIVER_AUTH_PASSWORD}) ✅
[x] mealie → Stack ENV (kein _FILE-Support) ✅
[x] mealie-postgres → Stack ENV (kein _FILE-Support) ✅
[x] gotify → GOTIFY_DEFAULTUSER_PASS_FILE ✅
[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
[ ] luckyBackup → Secrets prüfen
```
### Block F — Feinschliff / Hardening
@@ -440,7 +409,6 @@ labels:
[ ] 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
[ ] netdata - leere CLAIM-Vars entfernen
[ ] 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
@@ -458,9 +426,6 @@ labels:
| `tailscale` | `host` | VPN-Zugang; Umstellung nur kontrolliert möglich |
| `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 |
| `netdata` | `host` + zusätzliche Rechte | Host-Metriken |
| `Glances` | `host` | Host-Metriken |
| `netalertx` | `host` + Netzwerksicht | ARP / Netzwerkscan |
| `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 |
@@ -484,7 +449,7 @@ Dieses Projekt wird **blockweise** umgesetzt, nicht wild containerweise.
| 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 | Git-Stack-Migration Dockerman-Container (`gotify`, `Dozzle`, `dashdot`, `luckyBackup`, `Stash`, `netdata`, `Glances`, `netalertx`, `Plex`) + PortainerCE abschalten | 🔄 In Bearbeitung |
| Sprint 5 | `Plex-Media-Server` Compose-Migration + `PortainerCE` abschalten | 🔄 In Bearbeitung |
| Sprint 6 | Hardening / Secrets / Volumes / Sonderfälle (`immich_default`, Volumes, Mounts, AdGuard Traefik) | ⏳ Offen |
### 11.3 Regel für jede Änderung
@@ -557,7 +522,7 @@ Komodo ist nun der primäre GitOps-Stack-Manager:
Update-Monitoring kann über Komodo's eingebaute Update-Notifications abgedeckt werden.
### ntfy — Push-Notifications (Git-Stack)
`ntfy` läuft als Git-Stack (`apps/ntfy/docker-compose.yml`) parallel zu `gotify`:
`ntfy` läuft als Git-Stack (`apps/ntfy/docker-compose.yml`):
- `ntfy.kaleschke.info` via Traefik
- `NTFY_UPSTREAM_BASE_URL: https://ntfy.sh` für mobile Push-Notifications
- `NTFY_BEHIND_PROXY: true` korrekt gesetzt
@@ -571,8 +536,8 @@ Host-Pfade in `env_file` (z.B. `/mnt/...`) sind in Git-Stacks nicht verfügbar.
|---|---|
| Vaultwarden | ✅ ja |
| PostgreSQL | ✅ ja |
| Gotify | ✅ ja (`GOTIFY_DEFAULTUSER_PASS_FILE`) |
| code-server | ✅ ja (`PASSWORD_FILE`) |
| Immich Postgres | ✅ ja (`POSTGRES_PASSWORD_FILE`) |
| Mealie | ❌ nein → Stack ENV |
| paperless-ngx | ❌ nein für DB-Pass → Stack ENV |