ZMB Webui: Complete Project – Rebrand & Initial Clean Commit
ARCHITECTURE ============ Backend: FastAPI + uvicorn (port 8000) - JWT authentication with PAM system users - ZFS CLI wrapper with caching (30-60s TTL) - WebSocket pool status broadcaster (30s interval) - Services: auth, zfs_runner, file_manager, shares, identities, system_info - Routers: pools, datasets, snapshots, shares, identities, navigator, system Frontend: Next.js 15 + TypeScript (static export) - Incremental Static Regeneration (ISR) for weak hardware - Type-safe API client (lib/api.ts) - Dark mode + custom Tailwind theme - Pages: Dashboard, Login, Snapshots, Datasets, Shares, etc. DEPLOYMENT ========== Test Target: 192.168.1.179:8090 (Debian LXC) Production: 10.66.120.3:9090 (Raspberry Pi 4GB ARM64) Updater: Automated Gitea-based deployment (update-test.sh, update-pi.sh) FEATURES COMPLETED ================== Phase 3a: Dashboard Quick Stats (System, CPU, Memory, Storage) - Real-time stats with color-coded progress bars - Responsive grid layout (mobile: 1, tablet: 2, desktop: 4 columns) - ISR-optimized for fast loads on weak hardware REBRANDING ========== Renamed throughout: - Project: 'ZFS Manager' → 'ZMB Webui' - Services: 'zfs-manager' → 'zmb-webui' - Systemd units: zfs-manager-backend → zmb-webui-backend - Configuration files and documentation Co-Authored-By: Patrick <patrick@perlbach24.de>
This commit is contained in:
Claude Code
@@ -0,0 +1,417 @@
|
||||
# Proxmox LXC Setup für ZMB Webui
|
||||
|
||||
ZMB Webui läuft in **Proxmox LXC Container** mit direktem Zugriff auf Proxmox Host ZFS Pools.
|
||||
|
||||
## Voraussetzungen
|
||||
|
||||
- ✅ Proxmox Host mit ZFS (z.B. pool "tank")
|
||||
- ✅ LXC Container Support
|
||||
- ✅ Netzwerk-Zugriff zum Container
|
||||
|
||||
## 1. Container im Proxmox erstellen
|
||||
|
||||
### Via Proxmox Web UI
|
||||
|
||||
1. **Datacenter → Nodes → <node-name> → Create CT**
|
||||
- Hostname: `zmb-webui`
|
||||
- CT ID: z.B. `100`
|
||||
- Unprivileged: **NEIN** ← Muss Privilegiert sein!
|
||||
- Template: `debian-12-standard`
|
||||
- Storage: Proxmox-Default OK
|
||||
- Memory: 2048 MB (2GB) mindestens
|
||||
- Cores: 2 (für Pi Kompatibilität reicht auch 1)
|
||||
- Disk: 20-30GB
|
||||
|
||||
2. **Features aktivieren:**
|
||||
- [x] Nesting (für systemd, etc.)
|
||||
- [x] Keyctl (für systemd-homed)
|
||||
- [x] Mknod (für Devices)
|
||||
|
||||
### Via CLI (pveam)
|
||||
|
||||
```bash
|
||||
# Auf Proxmox Host:
|
||||
|
||||
# Template herunterladen (falls nicht vorhanden)
|
||||
pveam download local debian-12-standard_12.2-1_amd64.tar.zst
|
||||
|
||||
# Container erstellen
|
||||
pct create 100 local:vztmpl/debian-12-standard_12.2-1_amd64.tar.zst \
|
||||
--hostname zmb-webui \
|
||||
--memory 2048 \
|
||||
--cores 2 \
|
||||
--storage local-lvm \
|
||||
--net0 name=eth0,bridge=vmbr0 \
|
||||
--onboot 1 \
|
||||
--features nesting=1,keyctl=1,mknod=1 \
|
||||
--privileged 1
|
||||
|
||||
# Starten
|
||||
pct start 100
|
||||
|
||||
# Shell Zugriff
|
||||
pct enter 100
|
||||
```
|
||||
|
||||
## 2. ZFS Mounting im Container
|
||||
|
||||
### A. Host-Bindung (Recommended)
|
||||
|
||||
```bash
|
||||
# Auf dem Proxmox Host:
|
||||
|
||||
# ZFS-Mountpoint für Container zugänglich machen
|
||||
# (Proxmox macht das nicht automatisch!)
|
||||
|
||||
# Option 1: Via /etc/pct/lxc/100/config
|
||||
|
||||
pct set 100 -mp0 /tank/share,mp=/tank/share
|
||||
|
||||
# oder direkt in config editieren:
|
||||
nano /etc/pve/lxc/100.conf
|
||||
|
||||
# Hinzufügen:
|
||||
mp0: /tank/share,mp=/tank/share
|
||||
|
||||
# Container neustarten:
|
||||
pct reboot 100
|
||||
```
|
||||
|
||||
### B. ZFS im Container - Kernel Module
|
||||
|
||||
```bash
|
||||
# Proxmox Host muss ZFS Kernel Module haben:
|
||||
lsmod | grep zfs
|
||||
# Falls leer: apt install zfsutils-linux
|
||||
|
||||
# Im privilegierten Container wird das Kernel-Modul vom Host sichtbar:
|
||||
pct enter 100
|
||||
# Im Container:
|
||||
lsmod | grep zfs # Sollte auch sichtbar sein!
|
||||
zpool list # Sollte Host-Pools zeigen
|
||||
```
|
||||
|
||||
## 3. Backend Installation im Container
|
||||
|
||||
```bash
|
||||
# Auf dem Proxmox Host:
|
||||
pct enter 100
|
||||
|
||||
# Im Container:
|
||||
apt update && apt upgrade -y
|
||||
apt install -y python3 python3-pip python3-venv git curl
|
||||
|
||||
# Backend klonen (oder kopieren)
|
||||
git clone <repo-url> /opt/zmb-webui
|
||||
cd /opt/zmb-webui/backend
|
||||
|
||||
# System check
|
||||
bash check_system.sh
|
||||
# Sollte zeigen:
|
||||
# ✓ Debian
|
||||
# ✓ Privileged Container (erkannt!)
|
||||
# ✓ ZFS Tools verfügbar
|
||||
# ✓ /tank/share gemountet
|
||||
|
||||
# Installation
|
||||
bash install.sh
|
||||
|
||||
# Service starten
|
||||
systemctl start zmb-webui-backend
|
||||
systemctl status zmb-webui-backend
|
||||
|
||||
# Test
|
||||
curl http://localhost:8000/health
|
||||
```
|
||||
|
||||
## 4. Network Access vom Host/External
|
||||
|
||||
### Container IP finden
|
||||
|
||||
```bash
|
||||
# Im Container:
|
||||
ip addr show eth0
|
||||
|
||||
# Oder vom Host:
|
||||
pct exec 100 ip addr show eth0
|
||||
# z.B.: 192.168.100.150
|
||||
```
|
||||
|
||||
### Zugriff vom Host
|
||||
|
||||
```bash
|
||||
# SSH vom Host zum Container
|
||||
ssh root@<container-ip>
|
||||
|
||||
# oder direkt via pct:
|
||||
pct enter 100
|
||||
|
||||
# Über Proxmox Firewall (falls aktiviert):
|
||||
# Neue Regel: Port 8000 (Backend) erlauben
|
||||
```
|
||||
|
||||
### Zugriff von External (Outside Proxmox)
|
||||
|
||||
```bash
|
||||
# Option A: Port Forward auf Proxmox Host
|
||||
# (In Proxmox Firewall oder iptables)
|
||||
|
||||
# Option B: Reverse Proxy auf Host
|
||||
# nginx auf Proxmox Host → 9090 → Container :8000
|
||||
|
||||
sudo nano /etc/nginx/sites-available/zmb-webui
|
||||
# Inhalt:
|
||||
server {
|
||||
listen 9090 ssl http2;
|
||||
server_name _;
|
||||
|
||||
ssl_certificate /etc/pve/nodes/<node>/pve-ssl.pem;
|
||||
ssl_certificate_key /etc/pve/nodes/<node>/pve-ssl.key;
|
||||
|
||||
location / {
|
||||
proxy_pass http://<container-ip>:8000;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection "upgrade";
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
}
|
||||
}
|
||||
|
||||
sudo systemctl restart nginx
|
||||
# Dann: https://<proxmox-host-ip>:9090
|
||||
```
|
||||
|
||||
## 5. ZFS Management im Container
|
||||
|
||||
### Test ZFS Funktionalität
|
||||
|
||||
```bash
|
||||
# Im Container:
|
||||
|
||||
# Pool-Liste (vom Proxmox Host!)
|
||||
zpool list
|
||||
# tank 364G 189G 175G - - 0% 52% 1.00x ONLINE -
|
||||
|
||||
# Datasets anschauen
|
||||
zfs list
|
||||
|
||||
# Snapshots erstellen
|
||||
zfs snapshot tank/share@test-2026-04-14
|
||||
|
||||
# Scrub starten
|
||||
zpool scrub tank
|
||||
|
||||
# Backend API Test
|
||||
TOKEN=$(curl -s -X POST http://localhost:8000/api/auth/login \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"username":"admin","password":"admin123"}' | jq -r .access_token)
|
||||
|
||||
curl http://localhost:8000/api/pools \
|
||||
-H "Authorization: Bearer $TOKEN"
|
||||
# → Zeigt [{"name":"tank", ...}]
|
||||
```
|
||||
|
||||
## 6. Container Backup/Restore
|
||||
|
||||
### Proxmox Native Backup
|
||||
|
||||
```bash
|
||||
# Auf dem Host:
|
||||
|
||||
# Container Backup erstellen
|
||||
vzdump 100 --storage local --notes "zmb-webui vor update"
|
||||
|
||||
# Backup anschauen
|
||||
ls -lh /var/lib/vz/dump/
|
||||
|
||||
# Restore
|
||||
pct restore 101 /var/lib/vz/dump/vzdump-lxc-100-2026_04_14-12_30_45.tar.zst
|
||||
pct start 101
|
||||
```
|
||||
|
||||
### Snapshot im Container
|
||||
|
||||
```bash
|
||||
# Im Container:
|
||||
systemctl stop zmb-webui-backend
|
||||
|
||||
# ZFS Snapshot des / Filesystems
|
||||
zfs snapshot rpool/data/containers/100@backup-2026-04-14
|
||||
|
||||
# Oder: Proxmox Snapshot
|
||||
systemctl start zmb-webui-backend
|
||||
```
|
||||
|
||||
## 7. Monitoring & Logging
|
||||
|
||||
```bash
|
||||
# Proxmox Web UI → CT 100 → Logs
|
||||
|
||||
# oder SSH:
|
||||
pct enter 100
|
||||
journalctl -u zmb-webui-backend -f
|
||||
|
||||
# Memory/CPU im Container
|
||||
top
|
||||
free -h
|
||||
df -h /
|
||||
|
||||
# Proxmox Monitoring
|
||||
# Web UI → Nodes → <node> → Resources
|
||||
```
|
||||
|
||||
## 8. Performance Tuning
|
||||
|
||||
### Memory im Container
|
||||
|
||||
```bash
|
||||
# Proxmox Host – Container config anpassen
|
||||
pct set 100 --memory 2048
|
||||
pct set 100 --swap 512 # Swap auch gut
|
||||
|
||||
# Vom Container-Zustand her:
|
||||
free -h
|
||||
# Total sollte ~2GB sein
|
||||
```
|
||||
|
||||
### CPU Zuordnung
|
||||
|
||||
```bash
|
||||
# Alle Cores des Proxmox Hosts nutzen
|
||||
pct set 100 --cores 2 # oder mehr, je nach Host
|
||||
|
||||
# CPU-Limit setzen (optional)
|
||||
# pct set 100 --cpulimit 2 # Max 2 CPU cores
|
||||
```
|
||||
|
||||
### Disk Performance
|
||||
|
||||
```bash
|
||||
# Wenn Container auf lokallvm läuft:
|
||||
# Default OK, aber SSD ist besser
|
||||
|
||||
# Wenn auf ZFS läuft (Proxmox Storage):
|
||||
# ZFS selbst managed das
|
||||
```
|
||||
|
||||
## 9. Proxmox-spezifische Gotchas
|
||||
|
||||
### Issue: ZFS im Container nicht sichtbar
|
||||
|
||||
```bash
|
||||
# Problem: zfs commands geben "command not found"
|
||||
# Lösung:
|
||||
|
||||
# 1. Im Container installieren
|
||||
apt install -y zfsutils-linux
|
||||
|
||||
# 2. Host-Kernel-Module müssen geladen sein
|
||||
pct enter 100
|
||||
modprobe zfs
|
||||
lsmod | grep zfs
|
||||
|
||||
# 3. Privilegiert-Mode checken
|
||||
# /etc/pve/lxc/100.conf sollte haben:
|
||||
features: nesting=1
|
||||
```
|
||||
|
||||
### Issue: /tank/share nicht gemountet im Container
|
||||
|
||||
```bash
|
||||
# Problem: ls /tank/share → Permission denied
|
||||
# Lösung:
|
||||
|
||||
# /etc/pve/lxc/100.conf checken:
|
||||
cat /etc/pve/lxc/100.conf | grep mp0
|
||||
|
||||
# Falls nicht vorhanden, hinzufügen:
|
||||
pct set 100 -mp0 /tank/share,mp=/tank/share
|
||||
|
||||
# Container neustarten:
|
||||
pct reboot 100
|
||||
|
||||
# Oder manuell in config:
|
||||
nano /etc/pve/lxc/100.conf
|
||||
# mp0: /tank/share,mp=/tank/share
|
||||
```
|
||||
|
||||
### Issue: Port 8000/9090 nicht erreichbar
|
||||
|
||||
```bash
|
||||
# Proxmox Firewall prüfen
|
||||
# Web UI → Firewall
|
||||
|
||||
# oder CLI:
|
||||
pve-firewall status
|
||||
pve-firewall enable
|
||||
|
||||
# Port erlauben:
|
||||
# Datacenter → Firewall → Add Rule
|
||||
# Action: ACCEPT
|
||||
# Direction: IN
|
||||
# Protocol: TCP
|
||||
# Destination Port: 8000 (oder 9090)
|
||||
|
||||
# Dann im Container prüfen:
|
||||
netstat -tlnp | grep 8000
|
||||
```
|
||||
|
||||
## 10. Security
|
||||
|
||||
### Unprivilegiert vs Privilegiert
|
||||
|
||||
```
|
||||
⚠️ Container ist PRIVILEGIERT!
|
||||
|
||||
Risiken:
|
||||
- Root im Container ≈ Root auf Host
|
||||
- Zugriff auf Host-Filesystems
|
||||
|
||||
Mitigationen:
|
||||
- Firewall (Proxmox + System)
|
||||
- regelmäßige Updates
|
||||
- Backup-Strategy
|
||||
- Monitoring
|
||||
```
|
||||
|
||||
### Firewall Rules (Proxmox)
|
||||
|
||||
```bash
|
||||
# Nur lokales Netzwerk zulassen
|
||||
Datacenter → Firewall:
|
||||
- Allow FROM 192.168.x.0/24 → Port 8000
|
||||
|
||||
# oder SSH Tunnel statt direkter Zugriff
|
||||
ssh -L 9090:localhost:8000 root@proxmox-host
|
||||
curl http://localhost:9090/health
|
||||
```
|
||||
|
||||
## 11. Production Checklist
|
||||
|
||||
- [ ] Container erstellt & Started
|
||||
- [ ] ZFS Mount funktioniert (`ls /tank/share`)
|
||||
- [ ] Backend installiert & Running
|
||||
- [ ] `curl /health` → 200 OK
|
||||
- [ ] Admin-Passwort geändert
|
||||
- [ ] Firewall konfiguriert
|
||||
- [ ] Network/SSH Zugriff funktioniert
|
||||
- [ ] Backup-Strategy definiert
|
||||
- [ ] Monitoring konfiguriert
|
||||
- [ ] Logs prüfbar
|
||||
|
||||
## Zusammenfassung
|
||||
|
||||
```
|
||||
Proxmox Host
|
||||
├── ZFS Pool: tank
|
||||
├── LXC Container: 100 (zmb-webui, privilegiert)
|
||||
│ ├── /tank/share (gemountet)
|
||||
│ ├── FastAPI :8000
|
||||
│ └── systemd service: zmb-webui-backend
|
||||
└── Firewall: Port 8000/9090 allowed
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Backend läuft im Proxmox LXC Container mit vollständigem ZFS Management!** 🚀
|
||||
Reference in New Issue
Block a user