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 → <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!** 🚀