zmb-webui/PROXMOX_QUICKSTART.md

Proxmox LXC Quick Start (5 Minutes)

ZMB Webui auf Proxmox LXC – schnell & einfach!

One-Liner Setup

# === AUF PROXMOX HOST ===

# 1. Container erstellen
pct create 100 local:vztmpl/debian-12-standard_12.2-1_amd64.tar.zst \
    --hostname zmb-webui \
    --memory 2048 \
    --cores 2 \
    --privileged 1 \
    --features nesting=1,keyctl=1 \
    --net0 name=eth0,bridge=vmbr0 \
    --onboot 1

# 2. ZFS Mount
pct set 100 -mp0 /tank/share,mp=/tank/share

# 3. Starten
pct start 100

# 4. Shell
pct enter 100

# === IM CONTAINER ===

# 5. Update
apt update && apt upgrade -y

# 6. Dependencies
apt install -y python3 python3-pip python3-venv git curl

# 7. Backend
git clone <repo> /opt/zmb-webui
cd /opt/zmb-webui/backend

# 8. Check
bash check_system.sh
# Sollte zeigen: ✓ Debian, ✓ Privileged, ✓ ZFS

# 9. Install
bash install.sh

# 10. Start
systemctl start zmb-webui-backend

# 11. Test
curl http://localhost:8000/health
# → {"status":"healthy"}

# 12. ZFS Test
zpool list
# → tank pool sichtbar!

# 13. Password
python3 manage_users.py change-password admin

Container IP & Access

# Im Container oder vom Host:
pct exec 100 ip addr show eth0
# z.B.: 192.168.100.150

# SSH vom Host:
ssh root@192.168.100.150

# Oder direkt:
pct enter 100

# API Test:
curl http://192.168.100.150:8000/health

Verify ZFS Management

# Im Container:

# ZFS Pools
zpool list
# → Zeigt Proxmox Host Pools (z.B. tank)

# Datasets
zfs list
# → Alle Datasets vom Host

# Snapshots
zfs list -t snapshot | head
# → Snapshots sind sichtbar

# Backend API
TOKEN=$(curl -s -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"newpass"}' | jq -r .access_token)

curl http://localhost:8000/api/pools \
  -H "Authorization: Bearer $TOKEN"
# → [{"name":"tank","health":"ONLINE",...}]

Access vom Proxmox Host

# Shell zum Container
pct enter 100

# SSH zum Container
pct enter 100  # oder
ssh root@<container-ip>

# curl von Host
curl http://<container-ip>:8000/health

Performance im Proxmox LXC

• Pool Queries: 20-50ms (vs 10-20ms bare metal)
• ZFS funktioniert native (Host-Kernel-Module)
• ~50% Performance-Overhead normal (akzeptabel)

Container Config anpassen

# Memory
pct set 100 --memory 2048
pct set 100 --swap 512

# Cores
pct set 100 --cores 2

# Disk (falls nötig)
pct set 100 --rootfs local-lvm:vm-100-disk-0,size=30G

# Neustarten
pct reboot 100

Proxmox Firewall (Optional)

# Wenn Firewall active:
# Web UI → Firewall → Add Rule
# 
# In:  TCP, Destination Port 8000
# Out: TCP, Allow all (default)

# oder CLI (nicht empfohlen)

Troubleshooting

ZFS nicht sichtbar

# Im Container:
apt install -y zfsutils-linux
modprobe zfs
zpool list  # Sollte funktionieren

/tank/share nicht gemountet

# Auf Proxmox Host:
pct set 100 -mp0 /tank/share,mp=/tank/share
pct reboot 100

# Im Container:
ls -la /tank/share  # Sollte funktionieren

Port 8000 nicht erreichbar

# Im Container:
netstat -tlnp | grep 8000
# Sollte zeigen: LISTEN ... 8000

# Proxmox Firewall prüfen
# Web UI → Firewall → Status

# SSH Tunnel als Workaround:
# ssh -L 9090:localhost:8000 root@proxmox-host
# curl http://localhost:9090/health

Backup & Restore

# Backup
vzdump 100 --storage local

# Restore
pct restore 101 /var/lib/vz/dump/vzdump-lxc-100-*.tar.zst
pct start 101

Logs

# Im Container:
journalctl -u zmb-webui-backend -f

# Von Proxmox Host:
pct exec 100 journalctl -u zmb-webui-backend -f

Summary

Proxmox Host (mit ZFS Pool "tank")
└── LXC Container 100 (zmb-webui, privilegiert)
    ├── /tank/share (gemountet)
    ├── FastAPI :8000 running
    ├── systemd service enabled
    └── ZFS Management funktioniert!

Access:
├── Local: pct enter 100
├── SSH: ssh root@<container-ip>
└── API: curl http://<container-ip>:8000/health

---

Das war's! Backend läuft auf Proxmox LXC mit vollständigem ZFS Management. 🚀