Claude Code
92bed208e0
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>
268 lines
8.5 KiB
Markdown
268 lines
8.5 KiB
Markdown
# Deployment Matrix – Alle Umgebungen
|
||
|
||
ZMB Webui läuft auf **allen Plattformen**:
|
||
|
||
## ✅ Unterstützte Architekturen & Umgebungen
|
||
|
||
```
|
||
┌──────────────────────┬──────────┬────────┬─────────────────────────┐
|
||
│ Platform │ Arch │ Test │ Notes │
|
||
├──────────────────────┼──────────┼────────┼─────────────────────────┤
|
||
│ Raspberry Pi │ ARM64 │ ✓ │ Primär, optimiert │
|
||
│ Debian (x86_64) │ AMD64 │ ✓ │ Full support │
|
||
│ Ubuntu (x86_64) │ AMD64 │ ✓ │ Full support │
|
||
│ Debian (i686) │ x86 32bit│ ✓ │ Supported, slower │
|
||
│ LXC Container │ any │ ✓ │ Privilegiert, ZFS native│
|
||
│ Proxmox LXC │ any │ ✓ │ Auf Proxmox Host mit ZFS│
|
||
│ Docker │ any │ ⚠️ │ Kein Docker (kein Plan) │
|
||
└──────────────────────┴──────────┴────────┴─────────────────────────┘
|
||
```
|
||
|
||
## Installation Quickstart
|
||
|
||
### 1️⃣ Raspberry Pi / ARM64 Debian
|
||
|
||
```bash
|
||
scp -r backend root@<pi-ip>:/tmp/zmb-webui-backend
|
||
ssh root@<pi-ip>
|
||
cd /tmp/zmb-webui-backend
|
||
sudo bash check_system.sh # Prüfe Kompatibilität
|
||
sudo bash install.sh # Auto-Installation
|
||
sudo systemctl status zmb-webui-backend
|
||
```
|
||
|
||
### 2️⃣ x86/AMD64 Debian/Ubuntu
|
||
|
||
```bash
|
||
scp -r backend root@<server-ip>:/tmp/zmb-webui-backend
|
||
ssh root@<server-ip>
|
||
cd /tmp/zmb-webui-backend
|
||
sudo bash check_system.sh
|
||
sudo bash install.sh
|
||
sudo systemctl status zmb-webui-backend
|
||
```
|
||
|
||
### 3️⃣ LXC Container Standalone (Privilegiert – für ZFS Management)
|
||
|
||
```bash
|
||
# Host-Seite: Container mit privilegiertem Mode
|
||
lxc launch images:debian/bookworm zmb-webui \
|
||
--config security.privileged=true \
|
||
--config security.nesting=true
|
||
|
||
# Port-Mapping
|
||
lxc config device add zmb-webui http proxy \
|
||
listen=tcp:0.0.0.0:9090 \
|
||
connect=tcp:127.0.0.1:8000
|
||
|
||
# Container-Seite
|
||
lxc exec zmb-webui -- bash
|
||
apt update && apt install -y python3 python3-pip python3-venv
|
||
cd /opt && git clone <repo> zmb-webui && cd zmb-webui/backend
|
||
bash install.sh
|
||
systemctl start zmb-webui-backend
|
||
|
||
# ZFS wird automatisch sichtbar im Container!
|
||
lxc exec zmb-webui -- zpool list # zeigt Host-Pools
|
||
```
|
||
|
||
### 4️⃣ Proxmox VM (wie bare metal)
|
||
|
||
```bash
|
||
# VM mit Debian/Ubuntu erstellen
|
||
# Dann wie x86/AMD64 Installation
|
||
bash check_system.sh
|
||
bash install.sh
|
||
```
|
||
|
||
## Frontend Build
|
||
|
||
### Auf stärkerem Host bauen
|
||
|
||
```bash
|
||
# Build auf x86/AMD64 (schneller)
|
||
cd frontend
|
||
npm install
|
||
npm run build # 2-5 min
|
||
npm run export # Static export
|
||
|
||
# Oder auf Pi (langsamer, aber funktioniert)
|
||
npm install # 20-30 min
|
||
npm run build # 20-30 min
|
||
npm run export # 5-10 min
|
||
```
|
||
|
||
### Deploy überall gleich
|
||
|
||
```bash
|
||
# Der Build-Output ist überall identisch (HTML/JS/CSS)
|
||
scp -r frontend/.next/out root@10.66.120.3:/opt/zmb-webui/frontend
|
||
# Dann nginx oder Next.js Server starten
|
||
```
|
||
|
||
## Architektur-Spezifische Gotchas
|
||
|
||
### ARM64 (Raspberry Pi)
|
||
|
||
✅ **Alles funktioniert**
|
||
- Python: ✓
|
||
- FastAPI: ✓
|
||
- ZFS Tools: ✓
|
||
- systemd: ✓
|
||
|
||
⚠️ **Langsam**
|
||
- npm install/build: 20-30 min (nicht auf Pi bauen!)
|
||
- Subprocess Timeout: 5s ist OK
|
||
|
||
### x86/AMD64
|
||
|
||
✅ **Schnell**
|
||
- npm build: 2-5 min
|
||
- Python: ✓
|
||
- ZFS Tools: ✓
|
||
|
||
✓ **Alles optimal**
|
||
|
||
### x86 32-bit
|
||
|
||
✓ **Funktioniert**
|
||
- Python 32-bit: OK
|
||
- aber RAM-limitiert (max ~2GB pro Prozess)
|
||
|
||
⚠️ **Nicht empfohlen** für Production
|
||
|
||
### LXC Container (Privilegiert)
|
||
|
||
✅ **Container-agnostisch**
|
||
- Funktioniert auf ARM64, x86, AMD64 Host
|
||
|
||
✓ **ZFS funktioniert nativ**
|
||
- Privilegierter Container hat `/dev/zfs` Zugriff
|
||
- `zpool` und `zfs` Commands arbeiten direkt
|
||
- Snapshots, Scrub, alles im Container möglich
|
||
|
||
✓ **File Manager funktioniert**
|
||
- ZFS Datasets sind sichtbar im Container
|
||
- Read/Write auf `/tank/share` etc.
|
||
|
||
## Requirements per Architektur
|
||
|
||
```
|
||
┌─────────────────┬──────────┬─────────┬──────────┬──────────┐
|
||
│ Requirement │ ARM64 │ AMD64 │ x86_32 │ LXC │
|
||
├─────────────────┼──────────┼─────────┼──────────┼──────────┤
|
||
│ Python 3.8+ │ ✓ │ ✓ │ ✓ │ ✓ │
|
||
│ pip │ ✓ │ ✓ │ ✓ │ ✓ │
|
||
│ ZFS Tools │ ✓ │ ✓ │ ✓ │ mounted │
|
||
│ systemd │ ✓ │ ✓ │ ✓ │ ✓ │
|
||
│ 512MB+ RAM │ ✓ │ ✓ │ ⚠️ │ ✓ │
|
||
│ 500MB+ Disk │ ✓ │ ✓ │ ✓ │ ✓ │
|
||
│ Internet │ ✓ │ ✓ │ ✓ │ host fw │
|
||
└─────────────────┴──────────┴─────────┴──────────┴──────────┘
|
||
```
|
||
|
||
## Performance-Vergleich
|
||
|
||
```
|
||
┌─────────────────┬──────────┬──────────┬─────────┐
|
||
│ Operation │ Pi/ARM64 │ x86/AMD64│ LXC │
|
||
├─────────────────┼──────────┼──────────┼─────────┤
|
||
│ /api/pools │ 50-100ms │ 10-20ms │ 20-50ms │
|
||
│ /api/files │ 200ms │ 50ms │ 100ms │
|
||
│ Snapshot create │ 2-3s │ 0.5-1s │ 1-2s │
|
||
│ npm build │ 20-30min │ 2-5 min │ ↑ host │
|
||
└─────────────────┴──────────┴──────────┴─────────┘
|
||
```
|
||
|
||
## Checklist vor Production
|
||
|
||
### Pre-Installation
|
||
|
||
- [ ] `bash check_system.sh` erfolgreich
|
||
- [ ] Python 3.8+ installiert
|
||
- [ ] ZFS Tools installiert (wenn nötig)
|
||
- [ ] ≥512MB RAM verfügbar (besser 1-2GB)
|
||
- [ ] ≥500MB Disk verfügbar
|
||
- [ ] Internet-Konnektivität (für apt)
|
||
- [ ] Falls LXC: Privilegierter Container (`security.privileged=true`)
|
||
|
||
### Installation
|
||
|
||
- [ ] `bash install.sh` erfolgreich
|
||
- [ ] `systemctl status zmb-webui-backend` → active
|
||
- [ ] `curl http://localhost:8000/health` → 200 OK
|
||
|
||
### Post-Installation
|
||
|
||
- [ ] Admin-Passwort geändert
|
||
- [ ] `zpool list` funktioniert (als root)
|
||
- [ ] `/tank/share` ist readwrite
|
||
- [ ] Firewall Port 9090 (wenn via nginx) oder 8000 (direkt)
|
||
- [ ] Backups konfiguriert
|
||
|
||
## Troubleshooting Multi-Arch
|
||
|
||
### Python Fehler
|
||
```bash
|
||
# Check architecture:
|
||
python3 -c "import struct; print(struct.calcsize('P') * 8)"
|
||
# 32 = 32-bit, 64 = 64-bit
|
||
|
||
# Check Python arch:
|
||
file $(which python3)
|
||
# x86-64, ARM aarch64, Intel 80386, etc.
|
||
```
|
||
|
||
### ZFS Fehler
|
||
```bash
|
||
# Check ZFS verfügbar:
|
||
zpool list 2>&1
|
||
|
||
# Falls "command not found":
|
||
apt install zfsutils-linux zfs-auto-snapshot
|
||
```
|
||
|
||
### systemd Fehler
|
||
```bash
|
||
# Nur auf Linux mit systemd:
|
||
systemctl --version
|
||
|
||
# Falls fehlt: Manuell via supervisor/runit einrichten
|
||
```
|
||
|
||
## Multi-Arch CI/CD
|
||
|
||
### Build Strategy
|
||
```
|
||
Architect Publish
|
||
↓
|
||
┌─────────────────────────────┐
|
||
│ Build auf x86/AMD64 (schnell)│
|
||
│ • Backend: python wheels │
|
||
│ • Frontend: static export │
|
||
└─────────────────────────────┘
|
||
↓
|
||
Artifacts (universal)
|
||
↓
|
||
Deploy auf:
|
||
├── ARM64 Pi
|
||
├── x86/AMD64 Server
|
||
├── LXC Container
|
||
└── Proxmox VM
|
||
```
|
||
|
||
**Alle nutzen die gleichen Artifacts – kein re-build nötig!**
|
||
|
||
## Summary
|
||
|
||
| Plattform | Kompatibilität | Performance | Empfehlung |
|
||
|-----------|---|---|---|
|
||
| Raspberry Pi 4/5 | ✓ Vollständig | ⭐⭐ Ausreichend | ✓ Primary |
|
||
| Debian/Ubuntu x86 | ✓ Vollständig | ⭐⭐⭐⭐ Sehr gut | ✓ Production |
|
||
| LXC Container | ✓ Vollständig | ⭐⭐⭐ Gut | ✓ Enterprise |
|
||
| x86 32-bit | ✓ Unterstützt | ⭐ Langsam | ⚠️ Fallback |
|
||
|
||
---
|
||
|
||
**Backend läuft überall – eine Codebase für alle Plattformen!** 🎯
|