doc: konsolidierte Homelab-Dokumentation + Original-Plan

doc/plan/homelab-projekt-kontext.md

@@ -0,0 +1,81 @@
+# homelab rebuild — projekt-kontext / handoff
+
+> Dieses Dokument bündelt den Stand des Homelab-Rebuild-Projekts, damit ein neuer Assistent (z.B. Claude Code) sofort im Bild ist. Stand: Juni 2026.
+
+## ziel
+
+Sauberer Komplett-Neuaufbau des Proxmox-Homelabs: PVE neu installieren mit **ZFS-Root**, den ZFS-Mirror `tank` neu anlegen, alles am geschriebenen **homelab-manifest** ausrichten. Vorher: backup-first Migration (alles sichern, verifizieren, *dann* wipen).
+
+## kontext zur person
+
+Architekt (Masterstudium berufsbegleitend, Luzern) mit kleinem Büro-Kontext, FOSS-/Linux-Mensch, entwickelt eigene Software-Suite **openbureau** (Rapport, Dossier, Pendenz) mit Claude Code. Vor-Architektur-Hintergrund: Elektroinstallation + BIM-Projektleitung. Werte: Datensouveränität, config-as-code, self-hosted.
+
+## hardware
+
+- Mini-PC Server
+- 1× 1TB NVMe — **aktuell LVM-Thin (`local-lvm`) Root**, soll nach Reinstall **ZFS-Root (`rpool`)** werden
+- 2× 4TB — **ZFS Mirror `tank`** (~3.6 TiB nutzbar, die Bulk-Daten)
+- 1× 2TB externe HDD — `ext-hdd01` unter `/mnt/pve/ext-hdd01` (Directory, Backup-Ziel)
+- 1× 2TB USB-C NVMe SSD — neu, für den **PBS-Datastore** (Pfad ist beim User zu bestätigen, Annahme `/mnt/pve/pbs-ssd`)
+
+## aktuelles inventar (echte CTIDs/VMIDs)
+
+LXC: 100 nextcloud · 101 immich · 102 vaultwarden · 103 mailserver · 105 obsidian-livesync · 106 gitea · 107 openbureau · 110 flarum · 111 nginx-proxy-manager · 200 kgva-website · 210 openbureau-web · 211 rapport-website · 212 dossier-website · 219 dev.openbureau · 220 trattoriamarina.ch · 900 rapport-server
+VM: 500 windows · 800 homeassistant-os
+
+## getroffene entscheidungen
+
+**Architektur-Prinzipien:** filesystem-first (das FS ist die Wahrheit, Web/SMB/Sync sind Clients); FOSS + config-as-code in Gitea; öffentlich = Caddy / privat = WireGuard-only; RAID ≠ Backup (3-2-1); ZFS-Pool nie über 85%; grosse Daten mit `backup=0` + separat sichern; bewusster Hybrid (single-purpose Infra = native LXC, echte Multi-Container-Apps = ein Docker-LXC pro Stack).
+
+**ZFS:** tank = Mirror (einzige sinnvolle Redundanz bei 2 Platten). rpool = Single-Disk-ZFS für Einheitlichkeit. ashift=12, lz4, atime=off.
+
+**Speicher:** thin provisioning mit Quotas als Sicherheitsdeckel (nicht starr partitionieren). Reserve bewusst eingeplant.
+
+**Reverse Proxy:** Caddy statt NPM (Binary, auto-HTTPS, Caddyfile config-as-code). Edge-Härtung (TLS, Header, CrowdSec) bei Caddy, nicht in den App-Containern.
+
+**Nextcloud:** Docker-compose-Stack (NICHT native Rieger, NICHT AIO) — aber mit Rieger-Tuning-Werten (php opcache/JIT, APCu, Redis-Locking, MariaDB READ-COMMITTED). fpm + nginx-Sidecar. Inkl. Collabora + Whiteboard-Backend. Compose-Datei liegt vor (siehe Dateien).
+
+**Supabase:** nur für die eigenen openbureau-Apps als eigener, getrennter Stack — NICHT als Nextcloud-DB. NC bekommt eine nackte MariaDB/Postgres. NC- und Supabase-DBs strikt getrennt.
+
+**Shares:** zwei getrennte Datasets/Samba-Shares — `tank/business` (projektbasiert nach SIA-Phasen 00–08) und `tank/private` (nach Lebensbereichen). Synology-artiger Zugriff via Samba + Filebrowser (Web + Share-Links) + Syncthing (das "Drive"). Bewusst kein Seafile (sperrt Files weg → SMB ginge nicht mehr).
+
+**Architektur-spezifische Erweiterungen empfohlen:** Paperless-ngx (DMS+OCR), Stirling-PDF, BookStack-Wiki, Speckle (BIM-Datenhub, bei BIM-Arbeit), Authentik (SSO sobald mehr Leute). Plus Betrieb: Uptime Kuma, Beszel, Homepage. Privat: AdGuard Home, Linkwarden, Jellyfin/Navidrome, Miniflux.
+
+**Backup-Kette:**
+
+| Schicht | Werkzeug | Lokal | Offsite |
+|---------|----------|-------|---------|
+| Container + VMs | PBS | neue SSD | (aus Gitea reproduzierbar) |
+| Tank-Daten | Restic | ext-hdd01 (HDD) | Hetzner Storage Box |
+
+PBS läuft als privileged LXC, Datastore auf der SSD (überlebt den Wipe). Nach Reinstall: frisches PBS → bestehenden Datastore wieder einhängen → Gäste zurück. Tank: neu anlegen → Restic zurück. Verschlüsselungs-Key (falls genutzt) MUSS off-box gesichert werden.
+
+## migrations-reihenfolge
+
+1. PBS aufsetzen (Skript vorhanden), Datastore auf SSD.
+2. Alle 18 Gäste per `vzdump --mode stop --storage pbs` sichern.
+3. Stateful-Dienste app-level dumpen (mailserver-Backup + DKIM/DNS notieren; DB-Dumps).
+4. Tank-Daten per Restic auf ext-hdd01 + Hetzner.
+5. **Verifizieren + je 1 Container- und 1 Tank-Restore testen.**
+6. Erst dann wipen: PVE neu auf NVMe (ZFS-root, NUR NVMe als Ziel), tank neu als Mirror.
+7. Zurückspielen: PBS-Datastore wieder einhängen → Gäste; tank-Datasets nach Manifest → Restic zurück. Mailserver zuletzt.
+8. Laufendes Backup-System einrichten (PBS-Job + sanoid + Restic-Cron).
+
+## offene punkte (vom user noch zu liefern/bestätigen)
+
+- [ ] Discovery-Output: `zfs list -o name,used,mountpoint -r tank` + `pct config <id>` aller Container → um die echten Restic-Pfade und `backup=0/1`-Flags zu fixieren. **Wichtig:** App-Daten liegen in `subvol-*`-Mountpoints (z.B. `subvol-100-disk-0` = Nextcloud-Data) — nicht über Dataset-Namen auto-erkennbar.
+- [ ] Was ist `103 mailserver` genau (docker-mailserver / Mailcow)? → bestimmt Backup-Kommando + DKIM-Handling.
+- [ ] Stateful-Bestätigung: 107 openbureau & 900 rapport-server = Postgres? 105 obsidian-livesync = CouchDB? 219 dev.openbureau = ?
+- [ ] Pfad/Name der neuen SSD bestätigen (`cat /etc/pve/storage.cfg`).
+- [ ] Hetzner Storage Box vorhanden oder Offsite später?
+- [ ] PBS-Setup-Skript gelaufen? PBS sauber in PVE sichtbar?
+
+## produzierte dateien
+
+- `homelab-manifest.md` — die Referenz-Architektur (Pools, Dienste, CTID-Schema, Speicher-Quotas, Shares+Struktur, Netz, Backup, App-Katalog).
+- `homelab-anleitung.md` — Aufbau-Anleitung Schritt 1–12 (Proxmox → Pools → Datasets → Fileserver → Caddy/WireGuard/AdGuard → Apps → Monitoring → Backup).
+- `nextcloud-stack/` — docker-compose.yml + config/ (php-custom.ini, mariadb-tuning.cnf, nginx-nextcloud.conf) + .env.example.
+- `migrations-backup-runbook.md` — Backup-vor-dem-Wipe Runbook mit echtem Inventar.
+- `pbs-und-tank-backup-anleitung.md` — PBS aufsetzen + Tank sichern, Schritt für Schritt.
+- `setup-pbs.sh` — interaktives, ungefährliches Skript das den PBS-LXC provisioniert.
+- `homelab-projekt-kontext.md` — dieses Dokument.