zmb-webui/PROXMOX_LXC_SETUP.md

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 → → 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:

   • Nesting (für systemd, etc.)
   • Keyctl (für systemd-homed)
   • Mknod (für Devices)

Via CLI (pveam)

# 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)

# 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

# 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

# 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

# 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

# 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)

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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)

# 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! 🚀