zmb-webui/DEPLOYMENT_PI.md

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)

cd frontend
npm run build

• Erstellt optimierte Production-Build in frontend/out/
• Statische Assets werden vorkomprimiert

2. Frontend hochladen (lokal → remote)

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)

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)

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)

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)

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)

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

# 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):

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):

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:

# 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

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:

# 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:

# 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:

# 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

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

# 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

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