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

```bash
# 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

```bash
# 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

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

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

### File Manager Zugriff

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

```bash
# 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:**
```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

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

```bash
# 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

```bash
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)

```bash
# 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

```bash
# 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!