zmb-webui/deploy/lxc-setup.md

ZMB Webui in LXC Container

Setup für LXC

Scenario

• Host: ZFS Pool (tank) mit ZFS Tools
• LXC Container: Backend läuft in privilegiertem Container (für ZFS Management)
• Storage: ZFS Pool direkt im Container sichtbar, kein Mount nötig
• Netzwerk: Container auf eigenem IP, Port-Mapping zu Host

LXC Container erstellen

# 1. Container erstellen (PRIVILEGIERT für ZFS Management!)
lxc launch images:debian/bookworm zmb-webui \
    --config security.privileged=true \
    --config security.nesting=true

# 2. Container IP prüfen
lxc exec zmb-webui -- ip addr show eth0

# 3. Host-Port zu Container portmappen (9090 → 8000)
lxc config device add zmb-webui http proxy \
    listen=tcp:0.0.0.0:9090 \
    connect=tcp:127.0.0.1:8000

Warum privilegiert?

• ✓ ZFS Kernel-Modul wird sichtbar im Container
• ✓ zpool und zfs Commands funktionieren voll
• ✓ Pool-Management direkt im Container möglich
• ✓ Snapshots, Scrub, alles native im Container
• ⚠️ Sicherheits-Trade-off: Container hat Root-ähnliche Zugriffe

Installation im Container

# 1. In Container einsteigen
lxc exec zmb-webui -- bash

# 2. Update & Grundtools
apt update && apt upgrade -y
apt install -y python3 python3-pip python3-venv git curl

# 3. Backend klonen/kopieren
cd /opt
git clone <repo-url> zmb-webui
cd zmb-webui/backend

# 4. Installation durchführen
bash install.sh

# 5. Service starten
systemctl start zmb-webui-backend
systemctl enable zmb-webui-backend

# 6. Prüfen
curl http://localhost:8000/health

API-Zugriff vom Host

# Vom Host aus:
curl http://<container-ip>:9090/health

# oder via Port-Mapping:
curl http://localhost:9090/health

File Manager Zugriff

# Files liegen im Container unter /tank/share
# Das ist ein Mount vom Host (/tank/share)
# Änderungen sind direkt auf dem Host sichtbar

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

curl http://localhost:9090/api/files/browse?path=/ \
  -H "Authorization: Bearer $TOKEN"

Container-spezifische Anpassungen

1. ZFS-Operationen im Container

✅ ZFS funktioniert nativ! (weil Container privilegiert ist)

# Im privilegierten Container direkt:
lxc exec zmb-webui -- zpool list
# → Zeigt Host-Pools (tank, etc.)

lxc exec zmb-webui -- zfs list
# → Zeigt alle Datasets inklusive Snapshots

lxc exec zmb-webui -- zpool status tank
# → Zeigt VDEV-Status vom Host-Pool

Wie funktioniert das?

• Host hat ZFS Kernel-Modul geladen
• Privilegierter Container hat Zugriff auf /dev/zfs
• zpool/zfs Commands funktionieren wie auf Bare Metal
• Backend im Container kann direkt ZFS managen (kein SSH nötig!)

2. System Users im Container

Im privilegierten Container:

# im Container:
useradd -m newuser  # User im Container erstellen
# Host sieht das auch! (weil privilegiert)

# Beispiel: /etc/passwd wird synchronisiert
cat /etc/passwd | grep newuser  # existiert im Container

3. Samba/NFS im Container

# Im Container:
apt install -y samba

# Samba konfigurieren (Shares zeigen auf ZFS Datasets)
[tank_share]
    path = /tank/share
    browseable = yes
    read only = no
    public = yes

# NFS auch möglich
apt install -y nfs-kernel-server
# /etc/exports konfigurieren

LXC Resources begrenzen

# Memory limit: 2GB (für Backend + ZFS)
lxc config set zmb-webui limits.memory 2GB

# CPU limit: 2 cores
lxc config set zmb-webui limits.cpu 2

# Disk limit (falls auf separate Volume)
lxc config device set zmb-webui root size 50GB

# ZFS im Container hat direkten Zugriff auf Host-Disks
# (keine extra device-einbindung nötig wenn privilegiert)

Backup/Restore in LXC

# Container snapshot
lxc snapshot zmb-webui backup-2026-04-14

# Restore
lxc restore zmb-webui backup-2026-04-14

# Export Container
lxc export zmb-webui zmb-webui-backup.tar.gz

# Import
lxc import zmb-webui-backup.tar.gz

Debugging im Container

# Shell zugriff
lxc exec zmb-webui -- bash

# Logs anschauen
lxc exec zmb-webui -- journalctl -u zmb-webui-backend -f

# Network prüfen
lxc exec zmb-webui -- ip addr

# Port check
lxc exec zmb-webui -- netstat -tlnp | grep 8000

# Host Zugriff testen
lxc exec zmb-webui -- curl http://localhost:8000/health

Networking Setup

Option A: Bridge (Recommended)

# Container automatisch im Host-Netzwerk
lxc launch images:debian/bookworm zmb-webui
# Container kriegt automatisch IP vom DHCP/LXD-Bridge

Option B: Port-Forward via Host

lxc config device add zmb-webui http proxy \
    listen=tcp:0.0.0.0:9090 \
    connect=tcp:127.0.0.1:8000

# Dann von außen:
curl http://<host-ip>:9090/health

Option C: macvlan (Direct Network)

# Für Production – Container kriegt eigne MAC + IP im Netzwerk
lxc config device add zmb-webui eth0 nic \
    nictype=macvlan \
    parent=eth0

Performance im LXC

CPU-Performance

• x86/AMD64: ~5-10% Overhead vs Bare Metal
• ARM64 (Pi): ~5-10% Overhead
• LXC ist sehr effizient – Python FastAPI läuft ohne Probleme

Memory-Performance

• Nachteil: Container hat seinen eigenen Memory Space
• Vorteil: Memory-Limits können pro Container gesetzt werden
• Empfehlung: Min 1GB für Backend, besser 2GB

ZFS im Container

• Vorteil: Host verwaltet ZFS, Container nutzt Snapshots
• Nachteil: Container kann Pool selbst nicht managen (nur CLI)

Sicherheit

Unprivilegiert vs Privilegiert

# Unprivilegiert (Recommended)
security.privileged=false   # Standard
# User namespacing activ
# Weniger Sicherheits-Risiken

# Privilegiert (nur wenn ZFS management im Container nötig)
security.privileged=true    # Risikanter!
# Volle Root-Zugriffe im Container

Für diesen Use-Case

Unprivilegiert ist OK weil:

• ZFS Management bleibt auf Host
• File Manager hat nur Read/Write auf /tank/share
• System Users sind container-lokal

Zusammenfassung

Host (Bare Metal / VM)
├── ZFS Pool (tank) - Host verwaltet
│   ├── /tank/share - gemountet in LXC
│   └── Snapshots, Scrub - Host macht alles
│
└── LXC Container (zmb-webui)
    ├── FastAPI Backend :8000
    ├── Zugriff auf /tank/share (R/W)
    ├── File Manager funktioniert
    ├── System Users lokal
    └── Port 9090 → Host Port Mapping

Ergebnis: Backend läuft überall – Pi, x86, AMD64, oder im LXC!