zmb-webui/PHASE1_SUMMARY.md

Phase 1: FastAPI Backend – Abgeschlossen ✓

Was wurde gebaut

Komplettes FastAPI-Backend für ZMB Webui mit:

• ✅ Alle ZFS-Operationen (Pool, Dataset, Snapshot)
• ✅ File Manager (Browse, Upload, Download) wie cockpit-files
• ✅ JWT Authentication mit bcrypt
• ✅ Caching (30s-300s TTL)
• ✅ Production-ready Systemd Service
• ✅ User Management CLI Tool
• ✅ Comprehensive Documentation

Dateistruktur

backend/
├── main.py                          # FastAPI App (1-Click Run)
├── requirements.txt                 # Python Dependencies
├── install.sh                       # Auto-Installation für Pi
├── manage_users.py                  # User Management CLI
├── README.md                        # API Documentation
│
├── services/
│   ├── zfs_runner.py               # ZFS Subprocess Wrapper + Caching
│   ├── auth.py                     # JWT Token Generation/Verification
│   └── file_manager.py             # File Browser, Upload, Download
│
├── routers/
│   ├── auth.py                     # POST /api/auth/login
│   ├── pools.py                    # GET/POST Pool Operations
│   ├── datasets.py                 # GET/POST/DELETE Dataset CRUD
│   ├── snapshots.py                # GET/POST/DELETE Snapshot CRUD
│   └── files.py                    # GET/POST/DELETE File Manager
│
├── models/
│   ├── pool.py                     # Pool, PoolStatus, PoolHealth
│   ├── dataset.py                  # Dataset, DatasetType
│   ├── snapshot.py                 # Snapshot
│   └── auth.py                     # User, Token, TokenData
│
└── config/
    └── users.json                  # Default Admin User

deploy/
└── zmb-webui-backend.service     # Systemd Service (2 Workers, 512MB RAM limit)

API Endpoints

Authentication

POST /api/auth/login              # Login mit Username/Passwort
POST /api/auth/verify             # Token Verifikation

Pools

GET  /api/pools                   # List aller Pools
GET  /api/pools/{name}            # Pool Status + VDEV-Baum
POST /api/pools/{name}/scrub      # Start Scrub

Datasets

GET  /api/datasets                # List Datasets (max depth 2)
POST /api/datasets                # Create Dataset
DELETE /api/datasets/{name}       # Delete Dataset

Snapshots

GET  /api/snapshots               # List Snapshots (limit 50)
POST /api/snapshots               # Create Snapshot
DELETE /api/snapshots/{name}      # Delete Snapshot
POST /api/snapshots/rollback      # Rollback to Snapshot

Performance-Features (für 4GB RAM Pi)

✅ Caching Layer:

• Pool Status: 30s TTL
• Snapshots/Datasets: 60-120s TTL
• In-Memory Cache (kein Redis nötig)

✅ Resource Limits:

• gunicorn: 2 Worker
• Memory: 512M soft / 768M hard
• Timeout: 30s
• Max Requests per Worker: 500 (Memory-Leak Prevention)

✅ ZFS Optimization:

• Queries mit Depth-Limit (max 2 Ebenen)
• Snapshots limitiert auf 50 (konfigurierbar)
• Subprocess Timeout: 5s
• Lazy Parsing (streaming output)

Installation auf dem Pi

# 1. Backend kopieren
scp -r backend root@10.66.120.3:/tmp/zmb-webui-backend

# 2. Installation durchführen
ssh root@10.66.120.3
cd /tmp/zmb-webui-backend
sudo bash install.sh

# 3. Service starten
sudo systemctl start zmb-webui-backend
sudo systemctl enable zmb-webui-backend

# 4. Test
curl http://10.66.120.3:8000/health

Default Credentials

Admin User (nach Installation):

• Username: admin
• Password: admin123
• ⚠️ SOFORT ÄNDERN!

# Passwort ändern auf dem Pi:
python3 /opt/zmb-webui/backend/manage_users.py change-password admin <newpassword>

Login-Flow

# 1. Login
curl -X POST http://10.66.120.3:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}'

# Response:
# {"access_token":"eyJhbGc...","token_type":"bearer"}

# 2. API Request mit Token
TOKEN="eyJhbGc..."
curl http://10.66.120.3:8000/api/pools \
  -H "Authorization: Bearer $TOKEN"

Testing

Lokal testen (ohne ZFS nötig)

# Nur Python-Syntax checken
python3 -m py_compile main.py models/*.py routers/*.py services/*.py

Auf dem Pi testen

# Health Check
curl http://10.66.120.3:8000/health

# Login
curl -X POST http://10.66.120.3:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}'

# List Pools
TOKEN="<token from login>"
curl http://10.66.120.3:8000/api/pools \
  -H "Authorization: Bearer $TOKEN"

# List Snapshots
curl "http://10.66.120.3:8000/api/snapshots?limit=10" \
  -H "Authorization: Bearer $TOKEN"

Troubleshooting

Backend startet nicht

# Logs anschauen
journalctl -u zmb-webui-backend -f

# Service Status
systemctl status zmb-webui-backend

Memory-Probleme

# Memory Usage checken
ps aux | grep uvicorn

# Service neustarten
systemctl restart zmb-webui-backend

# Oder: Cron Job für tägliche Restart (wenn nötig)
0 3 * * * systemctl restart zmb-webui-backend

Snapshots dauern zu lange

# Cache leeren
curl -X POST http://10.66.120.3:8000/api/pools/clear-cache \
  -H "Authorization: Bearer $TOKEN"

# Oder: Limit in URL erhöhen
curl "http://10.66.120.3:8000/api/snapshots?limit=100"

Next Steps

• ✅ Phase 1: Backend fertig
• ⏳ Phase 2: Next.js Frontend bauen
• ⏳ Phase 3: WebSocket + Advanced Features
• ⏳ Phase 4: Alerts + Full Deployment

Notes

• No Docker! (wie gewünscht) – Direkter systemd deployment
• Performance-optimiert für ARM64 Raspberry Pi
• JWT Auth statt Session-basiert (für API-Nutzung ideal)
• Minimal Dependencies (nur FastAPI, Pydantic, python-jose, passlib)