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

```bash
# 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!

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

## Login-Flow

```bash
# 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)
```bash
# Nur Python-Syntax checken
python3 -m py_compile main.py models/*.py routers/*.py services/*.py
```

### Auf dem Pi testen
```bash
# 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
```bash
# Logs anschauen
journalctl -u zmb-webui-backend -f

# Service Status
systemctl status zmb-webui-backend
```

### Memory-Probleme
```bash
# 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
```bash
# 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)