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,305 @@
|
||||
# ZMB Webui Deployment auf Production-Pi
|
||||
|
||||
**Host:** 10.66.120.3
|
||||
**Status:** Live Production
|
||||
**ZFS Verfügbarkeit:** ✅ ZFS ist auf dem Produktions-Pi verfügbar
|
||||
|
||||
---
|
||||
|
||||
## Deployment-Prozess
|
||||
|
||||
Das Deployment auf dem Production-Pi (10.66.120.3) folgt den gleichen Schritten wie auf dem Entwicklungshost, wird aber mit erhöhten Sicherheitsanforderungen durchgeführt.
|
||||
|
||||
### 1. Frontend bauen (lokal)
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
npm run build
|
||||
```
|
||||
|
||||
- Erstellt optimierte Production-Build in `frontend/out/`
|
||||
- Statische Assets werden vorkomprimiert
|
||||
|
||||
### 2. Frontend hochladen (lokal → remote)
|
||||
|
||||
```bash
|
||||
scp -r frontend/out/* root@10.66.120.3:/opt/zmb-webui/backend/static/
|
||||
```
|
||||
|
||||
- Verteilt alle statischen Assets auf den Production-Pi
|
||||
- Nginx serviert diese Dateien direkt
|
||||
|
||||
### 3. Backend Services hochladen (lokal → remote)
|
||||
|
||||
```bash
|
||||
scp backend/services/*.py root@10.66.120.3:/opt/zmb-webui/backend/services/
|
||||
```
|
||||
|
||||
- Aktualisiert alle Service-Module (ZFS-Operationen, Shares, etc.)
|
||||
- Keine neustart des Services notwendig bis step 5
|
||||
|
||||
### 4. main.py hochladen (lokal → remote)
|
||||
|
||||
```bash
|
||||
scp backend/main.py root@10.66.120.3:/opt/zmb-webui/backend/
|
||||
```
|
||||
|
||||
- Haupt-Applikationsdatei (FastAPI-App)
|
||||
- Wird bei Service-Neustart neu geladen
|
||||
|
||||
### 5. Backend-Service neustarten (remote)
|
||||
|
||||
```bash
|
||||
ssh root@10.66.120.3 "systemctl restart zmb-webui-backend"
|
||||
```
|
||||
|
||||
- Startet den FastAPI-Backend neu
|
||||
- Alle Python-Module werden neu importiert
|
||||
- Wartet ~2 Sekunden für Service-Startup
|
||||
|
||||
### 6. Nginx-Konfiguration validieren und reload (remote)
|
||||
|
||||
```bash
|
||||
ssh root@10.66.120.3 "nginx -t && systemctl reload nginx"
|
||||
```
|
||||
|
||||
- `nginx -t`: Prüft Konfigurationsdatei auf Fehler
|
||||
- `systemctl reload nginx`: Zero-Downtime Reload
|
||||
- Bindet neue statische Assets automatisch ein
|
||||
|
||||
### 7. Health-Check durchführen (lokal)
|
||||
|
||||
```bash
|
||||
curl http://10.66.120.3/api/status
|
||||
```
|
||||
|
||||
- Prüft API-Verfügbarkeit nach Deployment
|
||||
- Erwartet HTTP 200 Response
|
||||
- Retry-Mechanismus: max. 5 Versuche mit 2s Delay
|
||||
|
||||
---
|
||||
|
||||
## Verwendung des Deployment-Scripts
|
||||
|
||||
```bash
|
||||
# Full Deployment (Frontend + Backend)
|
||||
./deploy/deploy.sh --target 10.66.120.3
|
||||
|
||||
# Nur Backend aktualisieren
|
||||
./deploy/deploy.sh --target 10.66.120.3 --backend-only
|
||||
|
||||
# Nur Frontend aktualisieren
|
||||
./deploy/deploy.sh --target 10.66.120.3 --frontend-only
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Sicherheits-Checkliste vor Production-Deployment
|
||||
|
||||
### ⚠️ ZFS_SECRET_KEY
|
||||
|
||||
**MUSS gesetzt sein vor Deployment!**
|
||||
|
||||
Auf dem Production-Pi (10.66.120.3):
|
||||
|
||||
```bash
|
||||
ssh root@10.66.120.3
|
||||
export ZFS_SECRET_KEY=$(openssl rand -hex 32)
|
||||
echo "ZFS_SECRET_KEY=$ZFS_SECRET_KEY" >> /opt/zmb-webui/backend/.env.local
|
||||
|
||||
# Verify
|
||||
cat /opt/zmb-webui/backend/.env.local
|
||||
```
|
||||
|
||||
- Wird für ZFS-Operation-Encryption verwendet
|
||||
- **Nicht im Code hardcoden!**
|
||||
- Pro Umgebung unterschiedlich
|
||||
|
||||
### ⚠️ JWT-Secret ändern
|
||||
|
||||
**MUSS für Production konfiguriert sein!**
|
||||
|
||||
Auf dem Production-Pi (10.66.120.3):
|
||||
|
||||
```bash
|
||||
ssh root@10.66.120.3
|
||||
|
||||
# JWT-Secret generieren
|
||||
JWT_SECRET=$(openssl rand -hex 64)
|
||||
|
||||
# In .env eintragen
|
||||
echo "JWT_SECRET=$JWT_SECRET" >> /opt/zmb-webui/backend/.env.local
|
||||
|
||||
# Service neustarten
|
||||
systemctl restart zmb-webui-backend
|
||||
```
|
||||
|
||||
- Default-Secret aus Development ist UNSICHER
|
||||
- Ändert die Signatur aller bestehenden JWT-Tokens
|
||||
- Alle Clients müssen sich neu authentifizieren
|
||||
|
||||
### ⚠️ API-Keys und Credentials
|
||||
|
||||
Vor Deployment überprüfen:
|
||||
|
||||
```bash
|
||||
# Keine hardcodierten Credentials in Code-Dateien
|
||||
grep -r "password\|api_key\|secret" backend/main.py backend/services/*.py
|
||||
|
||||
# Alle Secrets müssen in .env.local oder Umgebungsvariablen sein
|
||||
# NICHT in git committen!
|
||||
```
|
||||
|
||||
### ⚠️ HTTPS-Zertifikate prüfen
|
||||
|
||||
```bash
|
||||
ssh root@10.66.120.3
|
||||
openssl x509 -in /etc/nginx/ssl/cert.pem -noout -dates
|
||||
```
|
||||
|
||||
- Let's Encrypt Zertifikat sollte gültig sein
|
||||
- Falls expired: `certbot renew` auführen
|
||||
|
||||
---
|
||||
|
||||
## Pre-Deployment Checklist
|
||||
|
||||
- [ ] Alle Secrets in `.env.local` gesetzt (lokal Dev-Kopie für Testing)
|
||||
- [ ] Jest/Unit-Tests laufen lokal erfolgreich
|
||||
- [ ] Frontend-Build ohne Warnings
|
||||
- [ ] Backend ohne Linting-Fehler (`black`, `flake8`)
|
||||
- [ ] Keine hardcodierten Credentials in Git
|
||||
- [ ] ZFS_SECRET_KEY auf Production-Pi bekannt
|
||||
- [ ] JWT-Secret auf Production-Pi aktualisiert
|
||||
- [ ] HTTPS-Zertifikat gültig
|
||||
|
||||
---
|
||||
|
||||
## Post-Deployment Verification
|
||||
|
||||
Nach erfolgreicher Deployment durchführen:
|
||||
|
||||
```bash
|
||||
# 1. Health Check
|
||||
curl -s http://10.66.120.3/api/status | jq .
|
||||
|
||||
# 2. ZFS-Operation testen (z.B. List Pools)
|
||||
curl -s http://10.66.120.3/api/zfs/pools | jq .
|
||||
|
||||
# 3. Shares prüfen
|
||||
curl -s http://10.66.120.3/api/shares | jq .
|
||||
|
||||
# 4. Logs überprüfen
|
||||
ssh root@10.66.120.3 "journalctl -u zmb-webui-backend -n 50 --no-pager"
|
||||
|
||||
# 5. Nginx prüfen
|
||||
ssh root@10.66.120.3 "systemctl status nginx"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Rollback bei Fehlern
|
||||
|
||||
Falls Deployment fehlgeschlagen:
|
||||
|
||||
```bash
|
||||
# Backend-Service auf Vorgänger-Version restarten
|
||||
ssh root@10.66.120.3 "systemctl restart zmb-webui-backend"
|
||||
|
||||
# Wenn Frontend-Assets corrupted:
|
||||
# Letzten Working-Build erneut deployen
|
||||
./deploy/deploy.sh --target 10.66.120.3 --frontend-only
|
||||
|
||||
# Service Logs überprüfen
|
||||
ssh root@10.66.120.3 "journalctl -u zmb-webui-backend -f"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Performance-Tipps für 4GB RAM Pi
|
||||
|
||||
- ISR Frontend: Statische Assets cached von Nginx
|
||||
- Gunicorn: 2 Worker Prozesse
|
||||
- Redis-Cache: 10min TTL für Pool-Lists, 5min für Snapshots
|
||||
- ZFS-Queries: Optimiert mit `--parsable` Output
|
||||
|
||||
Siehe auch: `perf_requirements.md` und `extreme_2gb_optimizations.md`
|
||||
|
||||
---
|
||||
|
||||
## Monitoring nach Deployment
|
||||
|
||||
Dauerhaft überwachen:
|
||||
|
||||
```bash
|
||||
# SSH zum Pi
|
||||
ssh root@10.66.120.3
|
||||
|
||||
# Terminal 1: Live-Logs
|
||||
journalctl -u zmb-webui-backend -f
|
||||
|
||||
# Terminal 2: Resource-Monitor
|
||||
htop
|
||||
|
||||
# Terminal 3: Health-Check Loop (lokal)
|
||||
while true; do
|
||||
curl -s http://10.66.120.3/api/status | jq . && sleep 5 || echo "DOWN"
|
||||
done
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Bekannte Probleme & Lösungen
|
||||
|
||||
### Problem: "Address already in use" on Port 8000
|
||||
|
||||
**Symptom:** Backend Service startet nicht
|
||||
|
||||
```bash
|
||||
ssh root@10.66.120.3
|
||||
lsof -i :8000
|
||||
kill -9 <PID>
|
||||
systemctl restart zmb-webui-backend
|
||||
```
|
||||
|
||||
### Problem: Nginx zeigt alte Frontend-Assets
|
||||
|
||||
**Symptom:** Browser cachet alte CSS/JS
|
||||
|
||||
```bash
|
||||
# Cache clearen
|
||||
ssh root@10.66.120.3
|
||||
rm -rf /var/cache/nginx/*
|
||||
systemctl reload nginx
|
||||
```
|
||||
|
||||
### Problem: ZFS-Operationen fehlgeschlagen
|
||||
|
||||
**Symptom:** API antwortet mit 500, ZFS-Befehle sind blockiert
|
||||
|
||||
```bash
|
||||
ssh root@10.66.120.3
|
||||
|
||||
# ZFS Pool Status überprüfen
|
||||
zpool status
|
||||
|
||||
# ZFS Event Log
|
||||
zpool events
|
||||
|
||||
# ggf. Pool-Import erzwingen
|
||||
zpool import -f
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Kontakt & Support
|
||||
|
||||
**Bei Problemen:**
|
||||
- Logs überprüfen: `journalctl -u zmb-webui-backend`
|
||||
- Health-Endpoint testen: `curl http://10.66.120.3/api/status`
|
||||
- SSH zum Pi und manuell ZFS-Befehl ausführen
|
||||
|
||||
**Documentation:**
|
||||
- `project_cockpit_new.md` — Architektur-Übersicht
|
||||
- `deploy/deploy.sh` — Deployment-Script mit ausführlicher Error-Handling
|
||||
- `perf_requirements.md` — Performance-Tuning
|
||||
Reference in New Issue
Block a user