# 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