chore: project skeleton + phase-1 plan

2026-04-21 21:59:29 +02:00 · 2026-04-21 21:59:29 +02:00 · fab512f1e1
commit fab512f1e1
4 changed files with 2048 additions and 0 deletions
--- a/.gitignore
+++ b/.gitignore
@ -0,0 +1,27 @@
+# Elixir/Mix
+/server/_build/
+/server/deps/
+/server/cover/
+/server/doc/
+/server/.fetch
+/server/erl_crash.dump
+/server/*.ez
+/server/priv/static/assets/
+/server/priv/static/cache_manifest.json
+/server/*.db
+/server/*.db-journal
+/server/*.db-wal
+/server/*.db-shm
+
+/agent/_build/
+/agent/deps/
+/agent/cover/
+/agent/doc/
+/agent/.fetch
+/agent/erl_crash.dump
+/agent/*.ez
+
+# Editors / OS
+.DS_Store
+.vscode/
+.idea/
--- a/README.md
+++ b/README.md
@ -0,0 +1,8 @@
+# Proxmox Monitor
+
+Agent-Server monitoring for Proxmox hosts. Elixir/OTP. See `proxmox-monitor-konzept.md`.
+
+- `server/` — Phoenix + SQLite + LiveView
+- `agent/` — Slipstream Channels client, deploys as Burrito binary
+
+Phase 1 focuses on end-to-end metric push. Later phases add ZFS/VM collectors, persistence, LiveView dashboard.
--- a/docs/superpowers/plans/2026-04-21-phase1-grundgeruest.md
+++ b/docs/superpowers/plans/2026-04-21-phase1-grundgeruest.md
--- a/proxmox-monitor-konzept.md
+++ b/proxmox-monitor-konzept.md
@ -0,0 +1,418 @@
+# Proxmox Monitor — Konzept
+
+Eine Agent-Server-Anwendung zum Monitoring von Proxmox-Hosts mit Fokus auf ZFS-Gesundheit und VM-Übersicht. Implementiert in Elixir/OTP.
+
+## Designprinzipien
+
+- **KISS**: Jede Entscheidung zugunsten der einfacheren Lösung, solange sie funktioniert.
+- **YAGNI**: Features werden erst gebaut, wenn sie konkret gebraucht werden — nicht prophylaktisch.
+- **Read-only**: Der Agent führt keine verändernden Commands auf dem Proxmox-Host aus.
+- **Push-Architektur**: Agents initiieren die Verbindung zum Server (NAT-freundlich).
+
+---
+
+## Architektur-Übersicht
+
+```
+┌──────────────────┐           ┌────────────────────┐
+│  Proxmox-Host 1  │           │  Server (LXC)      │
+│  ┌────────────┐  │           │  im Rechenzentrum  │
+│  │   Agent    │──┼──WSS──┐   │                    │
+│  └────────────┘  │       │   │  ┌──────────────┐  │
+└──────────────────┘       └──▶│  │   Caddy      │  │
+                               │  │ Reverse Proxy│  │
+┌──────────────────┐           │  └──────┬───────┘  │
+│  Proxmox-Host 2  │           │         │          │
+│  ┌────────────┐  │           │  ┌──────▼───────┐  │
+│  │   Agent    │──┼──WSS─────▶│  │   Phoenix    │  │
+│  └────────────┘  │           │  │   LiveView   │  │
+└──────────────────┘           │  └──────┬───────┘  │
+         ...                   │         │          │
+                               │  ┌──────▼───────┐  │
+┌──────────────────┐           │  │    SQLite    │  │
+│  Proxmox-Host N  │           │  └──────────────┘  │
+│  ┌────────────┐  │           │                    │
+│  │   Agent    │──┼──WSS─────▶│                    │
+│  └────────────┘  │           │                    │
+└──────────────────┘           └────────────────────┘
+```
+
+## Technologie-Stack
+
+| Komponente | Technologie | Begründung |
+|------------|-------------|------------|
+| Agent | Elixir + Burrito | Eigenständige Binary, keine Erlang-Installation auf Proxmox nötig |
+| Server | Phoenix + LiveView | Realtime-UI ohne separates Frontend |
+| Transport | Phoenix Channels (WSS) | Persistente Verbindung, Auto-Reconnect, Offline-Detection gratis |
+| Datenbank | SQLite + Ecto | Für ~20 Hosts vollkommen ausreichend, keine separate DB-Instanz |
+| TLS / Reverse Proxy | Caddy (bereits vorhanden) | Let's Encrypt automatisch |
+| Deployment (Server) | LXC-Container auf Proxmox im RZ | Geringer Overhead, saubere Isolation |
+| Deployment (Agent) | systemd-Service | Standard auf Debian/Proxmox |
+
+## Systemanforderungen
+
+- **Proxmox-Hosts**: Proxmox VE 8.3+ mit OpenZFS 2.3+ (für `-j` JSON-Output)
+- **Server**: LXC oder VM mit ausreichend RAM (1 GB reicht), Debian/Ubuntu
+- **Netzwerk**: Server muss öffentlich über HTTPS erreichbar sein (via Caddy)
+
+---
+
+## Agent
+
+### Verantwortlichkeiten
+
+Der Agent läuft auf jedem Proxmox-Host, sammelt in festen Intervallen Metriken und schickt sie an den Server. Er hält eine persistente WebSocket-Verbindung zum Server über Phoenix Channels.
+
+### Sammlungs-Intervalle
+
+Nicht alles muss gleich häufig gesammelt werden. Daten mit hoher Änderungsrate werden öfter abgefragt, statische Informationen seltener.
+
+| Intervall | Daten |
+|-----------|-------|
+| 30 Sekunden | Host-Metriken, VM-Runtime-Status, ZFS-Pool-Status, Storage-Auslastung |
+| 5 Minuten | Snapshots, Dataset-Liste, VM-Config, Guest-Agent-IPs |
+| 30 Minuten | Proxmox-Version, pending APT-Updates, ZFS-Version |
+
+### Zu sammelnde Daten
+
+**Host-Metriken** (aus `/proc` und `uptime`)
+- CPU-Auslastung (%), Load-Average (1/5/15)
+- RAM: used, total, available
+- Uptime in Sekunden
+- Root-Filesystem: used, total
+- Hostname, Kernel-Version
+
+**Proxmox-Storage** (`pvesh get /nodes/<node>/storage --output-format json`)
+- Alle konfigurierten Storages (ZFS, NFS, Local, etc.)
+- Typ, Status (active/inactive), used, total
+- Content-Typen (images, backup, iso, ...)
+
+**ZFS-Pools** (`zpool status -j --json-flat-vdevs --json-int`, `zpool list -j --json-int`)
+- Rohes JSON (vollständig gespeichert für spätere Analyse)
+- Zusätzlich extrahiertes Summary:
+  - Pool-Name, Health-State
+  - Size, Allocated, Free (Bytes)
+  - Fragmentation (%), Capacity (%)
+  - Error-Counter (read/write/checksum)
+  - Scrub-Status, letzter erfolgreicher Scrub
+  - Anzahl vdevs, Anzahl degraded vdevs
+
+**ZFS-Datasets & Snapshots** (`zfs list -j --json-int`)
+- Rohes JSON (Datasets und Snapshots)
+- Snapshot-Summary pro Dataset:
+  - Anzahl Snapshots
+  - Alter des ältesten / neuesten Snapshots
+  - Gesamt-Speicher (usedbysnapshots)
+
+**Virtuelle Maschinen & LXC-Container** (`pvesh`)
+- Statisch (aus Config): VMID, Name, Type (qemu/lxc), Cores, RAM (max), Disks (mit Storage-Backend), Tags, Autostart
+- Dynamisch (aus Runtime-Status): Status, Uptime, CPU-Auslastung, RAM-Verbrauch, Disk-I/O, Netzwerk-I/O
+- Via Guest-Agent (QEMU, optional): IP-Adressen aller Interfaces, OS-Info, Disk-Usage im Guest
+- LXC: IPs direkt aus Container-Config
+
+**System-Info**
+- Proxmox-Version (`pveversion`)
+- Anzahl verfügbarer Updates (`apt list --upgradable 2>/dev/null | wc -l`)
+- ZFS-Version
+- Agent-Version (fest einkompiliert)
+
+### Konfiguration
+
+Datei: `/etc/proxmox-monitor/agent.toml`, Zugriffsrechte `0600`, Eigentümer `root`.
+
+```toml
+server_url = "wss://monitor.example.com/socket/websocket"
+token = "agent_abc123xyz..."
+host_id = "pve-host-01"  # optional, sonst Hostname
+
+[intervals]
+fast_seconds = 30
+medium_seconds = 300
+slow_seconds = 1800
+```
+
+### Deployment
+
+```bash
+# Einmaliges Setup auf einem Proxmox-Host
+scp proxmox-monitor-agent root@pve-host-01:/usr/local/bin/
+scp agent.toml root@pve-host-01:/etc/proxmox-monitor/
+scp proxmox-monitor-agent.service root@pve-host-01:/etc/systemd/system/
+ssh root@pve-host-01 "systemctl enable --now proxmox-monitor-agent"
+```
+
+Der Agent muss als root laufen, da `zpool status` bei Degraded-Pools und einigen ZFS-Details Root-Rechte benötigt. Das ist akzeptabel, weil der Agent ausschließlich lesende Commands ausführt und keine eingehenden Verbindungen akzeptiert.
+
+---
+
+## Server
+
+### Verantwortlichkeiten
+
+- Nimmt Verbindungen von Agents entgegen, authentifiziert sie
+- Speichert Metriken in SQLite
+- Stellt LiveView-Dashboard bereit
+- Cleanup alter Metriken (Retention)
+
+### Datenmodell
+
+```elixir
+# hosts
+- id (PK)
+- name (unique)
+- token_hash (bcrypt)
+- created_at
+- last_seen_at
+- agent_version (nullable)
+- proxmox_version (nullable)
+- zfs_version (nullable)
+- status ("online" | "offline" | "never_connected")
+
+# metrics (Zeitreihe, ein Eintrag pro Sample)
+- id (PK)
+- host_id (FK)
+- collected_at (indexed)
+- interval_type ("fast" | "medium" | "slow")
+- payload (JSON)    # Gesamter Sample-Inhalt
+
+# Indexiert wegen Dashboard-Queries:
+# - (host_id, collected_at DESC) für "letzte N Samples eines Hosts"
+# - (collected_at) für Retention-Cleanup
+```
+
+**Begründung für JSON-Payload statt normalisierter Spalten:**
+Die Daten werden fast immer vollständig pro Host/Zeitpunkt gelesen (für die Detail-View). Separate Spalten pro Metrik würden die Schema-Evolution aufwendig machen. SQLite unterstützt JSON-Operatoren (`->>`) für Queries, falls wir mal einzelne Felder filtern müssen.
+
+### Phoenix Channels — Protokoll
+
+**Join** (Agent → Server):
+```json
+{
+  "topic": "host:pve-host-01",
+  "payload": {
+    "token": "agent_abc123xyz...",
+    "agent_version": "0.1.0"
+  }
+}
+```
+
+Server validiert Token gegen `hosts.token_hash`. Bei Erfolg: Assign der `host_id` an den Socket, `last_seen_at` aktualisieren, Status auf `online` setzen.
+
+**Events** (Agent → Server):
+```json
+// Event: "metric:fast" | "metric:medium" | "metric:slow"
+{
+  "collected_at": "2026-04-21T12:34:56Z",
+  "data": { /* je nach Intervall-Typ */ }
+}
+```
+
+**Disconnect-Handling** (Server):
+Wenn der Channel-Prozess stirbt (Terminate-Callback), wird der Host sofort als `offline` markiert. Kein Polling, keine Timeouts nötig.
+
+### LiveView-Seiten
+
+**1. Übersicht (`/`)**
+- Eine Karte pro Host, Grid-Layout
+- Status-Ampel: Grün (alles ok) / Gelb (Warnung) / Rot (kritisch) / Grau (offline)
+- Kritisch = Pool DEGRADED/FAULTED, Capacity > 90%, Agent offline
+- Warnung = Capacity 80-90%, alte Snapshots, pending Updates, Scrub überfällig
+- Pro Karte sichtbar: Host-Name, CPU, RAM, Uptime, Pool-Status (Zusammenfassung), VM-Anzahl
+- Sortier-/Filter-Optionen: nach Status, nach Host-Name
+
+**2. Host-Detail (`/hosts/:name`)**
+- Header mit Proxmox-Version, Uptime, letzter Kontakt
+- Tabs oder Sektionen:
+  - **Metriken**: CPU/RAM/Load-Graphen über 24h (simple Line-Charts mit Chart.js oder Contex)
+  - **ZFS-Pools**: Pro Pool eine Box mit Health, Capacity-Bar, Fragmentation, Error-Counters, Scrub-Info, vdev-Liste
+  - **Snapshots**: Tabelle pro Dataset mit Anzahl, Alter des ältesten/neuesten Snapshots
+  - **Storage**: Tabelle aller Proxmox-Storages mit Auslastung
+  - **VMs/LXCs**: Tabelle mit Name, Type, Status, CPU/RAM-Auslastung, IPs, Tags
+
+**3. VM-Suche (`/vms`)**
+- Globale Suche über alle Hosts
+- Input: Name oder IP
+- Ergebnis: Tabelle mit VM-Name, Host, Status, IP, Ressourcen
+- Killer-Feature bei 20 Hosts: "Wo läuft `nginx-proxy`?"
+
+**4. Host-Verwaltung (`/admin/hosts`)**
+- Liste aller Hosts mit Status, letzter Kontakt, Agent-Version
+- Button "Neuen Host hinzufügen": Formular mit Name → generiert Token, zeigt Install-Anleitung
+- Pro Host: "Token revoken" (setzt neuen Token), "Host löschen"
+
+### Authentifizierung
+
+**Web-UI:**
+- Single-User, Login via Passwort (Argon2-Hash in Environment-Variable oder Secret-Config)
+- Minimal-Setup mit einer einzigen Session/Cookie
+- Kein User-Management-UI nötig
+
+**Agents:**
+- Shared Token pro Agent
+- Token-Generierung: 32 Bytes Random, Base64-URL-encoded
+- In DB als Bcrypt-Hash gespeichert
+- Revoke durch Token-Neugenerierung im Admin-UI
+
+### Retention / Cleanup
+
+Ein GenServer läuft stündlich und löscht:
+- `metrics` älter als 48 Stunden
+
+Das reicht für "was ist in den letzten 2 Tagen passiert"-Analysen. Bei 20 Hosts × 30s-Samples × 48h = ca. 230.000 Rows. Völlig unproblematisch für SQLite.
+
+---
+
+## Projekt-Struktur
+
+Monorepo mit zwei getrennten Mix-Projekten:
+
+```
+proxmox_monitor/
+├── README.md
+├── konzept.md                 # Dieses Dokument
+│
+├── agent/                     # Mix-Projekt → Burrito-Binary
+│   ├── mix.exs
+│   ├── config/
+│   │   ├── config.exs
+│   │   └── runtime.exs
+│   ├── lib/
+│   │   ├── agent.ex
+│   │   ├── agent/
+│   │   │   ├── application.ex
+│   │   │   ├── config.ex
+│   │   │   ├── reporter.ex       # Phoenix Channel Client
+│   │   │   ├── supervisor.ex
+│   │   │   └── collectors/
+│   │   │       ├── host.ex
+│   │   │       ├── storage.ex
+│   │   │       ├── zfs.ex
+│   │   │       ├── vms.ex
+│   │   │       └── system_info.ex
+│   │   └── agent/schema/         # Structs für Samples
+│   │       ├── sample.ex
+│   │       ├── pool_summary.ex
+│   │       └── ...
+│   ├── rel/
+│   │   └── burrito.exs
+│   └── test/
+│
+└── server/                    # Phoenix-Projekt
+    ├── mix.exs
+    ├── config/
+    ├── lib/
+    │   ├── server/
+    │   │   ├── application.ex
+    │   │   ├── hosts.ex          # Kontext: Host-Verwaltung
+    │   │   ├── metrics.ex        # Kontext: Metrik-Speicherung
+    │   │   ├── retention.ex      # GenServer: Cleanup
+    │   │   └── schema/
+    │   │       ├── host.ex
+    │   │       └── metric.ex
+    │   └── server_web/
+    │       ├── router.ex
+    │       ├── endpoint.ex
+    │       ├── channels/
+    │       │   ├── agent_socket.ex
+    │       │   └── host_channel.ex
+    │       ├── live/
+    │       │   ├── overview_live.ex
+    │       │   ├── host_detail_live.ex
+    │       │   ├── vm_search_live.ex
+    │       │   └── admin_hosts_live.ex
+    │       └── controllers/
+    │           └── auth_controller.ex
+    ├── priv/
+    │   └── repo/migrations/
+    └── test/
+```
+
+---
+
+## Sicherheit
+
+- **TLS erzwungen** über Caddy, Agent verifiziert Server-Zertifikat
+- **Token niemals in Plaintext** in DB (Bcrypt) oder Logs
+- **Agent-Config mit Rechten `0600`, Root**
+- **Rate-Limiting** auf Channel-Join via Hammer-Library (z.B. 5 Versuche/Minute pro IP)
+- **Keine eingehenden Verbindungen zum Agent** — Agent initiiert immer
+- **Server-URL im Agent fest gepinnt** (keine Redirects)
+- **Read-only auf dem Proxmox-Host** — Agent führt keine verändernden Commands aus
+
+---
+
+## MVP-Scope — Was ist drin, was nicht
+
+### ✅ Im MVP
+
+- Agent sammelt Host-, ZFS-, VM-, Storage-, System-Metriken
+- Persistente WebSocket-Verbindung via Phoenix Channels
+- SQLite-Speicherung mit 48h Retention
+- Dashboard: Übersicht, Host-Detail, VM-Suche, Admin
+- Single-User-Auth für Web-UI
+- Token-basierte Agent-Auth
+- Burrito-Binary für Agent
+- LXC-Deployment für Server
+
+### ❌ Bewusst nicht im MVP (YAGNI)
+
+- **Alerts per E-Mail/Telegram/Gotify** — Dashboard zeigt farbig, reicht erstmal
+- **SMART-Werte der Disks** — eigenes Unterprojekt, später
+- **Backup-Task-Historie** — aufwendiges Parsing, später
+- **Cluster-Support** — nicht benötigt
+- **Agent-Self-Update** — manuell via scp reicht bei 20 Hosts
+- **Remote-Actions** (VM starten, Scrub triggern) — Read-only bleibt Read-only
+- **Multi-User, RBAC** — Single-User reicht
+- **Langzeit-Historie (>48h)** — separates Konzept (Downsampling) wenn gebraucht
+- **Mobile App** — Web-UI responsive reicht
+
+---
+
+## Roadmap
+
+### Phase 1 — Grundgerüst (Woche 1-2)
+- Agent-Skeleton: Ein Collector (Host-Metriken), Output auf Console
+- Server-Skeleton: Phoenix-Projekt, Host-Schema, einfacher Channel, der Daten empfängt und loggt
+- Ende: Agent verbindet sich lokal zum Server und pusht CPU-Metriken
+
+### Phase 2 — ZFS & VMs (Woche 3-4)
+- ZFS-Collector (pool status, list, snapshots)
+- VM-Collector (pvesh)
+- Storage-Collector
+- Server speichert in SQLite, simple Anzeige-Route
+
+### Phase 3 — LiveView-Dashboard (Woche 5-6)
+- Übersichtsseite mit Status-Ampeln
+- Host-Detail mit allen Sektionen
+- VM-Suche
+- Auth für Web-UI
+
+### Phase 4 — Admin & Deployment (Woche 7)
+- Admin-UI für Host-Verwaltung
+- Retention-GenServer
+- Burrito-Build für Agent
+- LXC-Deployment-Dokumentation
+
+### Phase 5 — Produktiv-Rollout (Woche 8)
+- Deployment auf Server im RZ
+- Caddy-Konfiguration
+- Agent auf 2-3 Test-Hosts ausrollen
+- Nach erfolgreichem Test: Rollout auf alle 20 Hosts
+
+### Nach dem MVP — ggf. als nächstes
+
+1. **Alerts** (wenn klar ist, welche Thresholds sinnvoll sind)
+2. **SMART-Monitoring** (für ZFS-Vorhersage)
+3. **Backup-Task-Tracking**
+4. **Langzeit-Historie** mit Downsampling
+
+---
+
+## Offene Entscheidungen / Vormerkungen
+
+Diese Punkte können beim Implementieren entschieden werden, sind aber fürs Konzept nicht kritisch:
+
+- **Chart-Library**: Chart.js (JS, via LiveView-Hook) vs. Contex (SVG, pure Elixir). Contex ist "eleganter", Chart.js bietet mehr Optionen out-of-the-box.
+- **Shared Structs zwischen Agent/Server**: Anfangs duplizieren. Falls das wehtut, später in eine geteilte Lib extrahieren.
+- **Exception-Handling bei pvesh/zpool-Fehlern**: Ausfall einer Datenquelle darf nicht das ganze Sample verwerfen. Teil-Samples mit Fehler-Flag akzeptieren.
+- **Logs**: Strukturiert (JSON) vs. Text. Vorschlag: Server strukturiert für spätere Auswertung, Agent textbasiert für einfaches journalctl-Debugging.