ZMB Webui: Complete Project – Rebrand & Initial Clean Commit
ARCHITECTURE ============ Backend: FastAPI + uvicorn (port 8000) - JWT authentication with PAM system users - ZFS CLI wrapper with caching (30-60s TTL) - WebSocket pool status broadcaster (30s interval) - Services: auth, zfs_runner, file_manager, shares, identities, system_info - Routers: pools, datasets, snapshots, shares, identities, navigator, system Frontend: Next.js 15 + TypeScript (static export) - Incremental Static Regeneration (ISR) for weak hardware - Type-safe API client (lib/api.ts) - Dark mode + custom Tailwind theme - Pages: Dashboard, Login, Snapshots, Datasets, Shares, etc. DEPLOYMENT ========== Test Target: 192.168.1.179:8090 (Debian LXC) Production: 10.66.120.3:9090 (Raspberry Pi 4GB ARM64) Updater: Automated Gitea-based deployment (update-test.sh, update-pi.sh) FEATURES COMPLETED ================== Phase 3a: Dashboard Quick Stats (System, CPU, Memory, Storage) - Real-time stats with color-coded progress bars - Responsive grid layout (mobile: 1, tablet: 2, desktop: 4 columns) - ISR-optimized for fast loads on weak hardware REBRANDING ========== Renamed throughout: - Project: 'ZFS Manager' → 'ZMB Webui' - Services: 'zfs-manager' → 'zmb-webui' - Systemd units: zfs-manager-backend → zmb-webui-backend - Configuration files and documentation Co-Authored-By: Patrick <patrick@perlbach24.de>
This commit is contained in:
Claude Code
@@ -0,0 +1,274 @@
|
||||
# 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!
|
||||
Reference in New Issue
Block a user