zmb-webui/INSTALL_GUIDE.md

# Installation Guide – All Platforms

ZMB Webui läuft auf **Raspberry Pi, x86, AMD64, und LXC Container**.

## 1. System Check

```bash
cd backend

# Kompatibilität prüfen (vor Installation!)
bash check_system.sh
```

### Was wird geprüft?
- ✓ Architektur (ARM64, x86_64, i686)
- ✓ OS (Debian, Ubuntu, RHEL, CentOS)
- ✓ Python 3.8+
- ✓ ZFS Tools (zpool, zfs)
- ✓ systemd (für Service)
- ✓ Disk-Platz (≥500MB)
- ✓ Memory (≥512MB)
- ✓ Internet (für apt)

## 2. Installation

### Option A: Bare Metal (Pi, x86, AMD64)

```bash
# Auf dem Ziel-System:
cd backend
sudo bash install.sh
```

Das Script macht automatisch:
1. Architektur Detection
2. OS Detection
3. Virtual Environment erstellen
4. Dependencies via pip installieren
5. Default Admin User setzen
6. systemd Service installieren
7. Service starten & Enable

### Option B: Remote Installation

```bash
# Von deinem Laptop:
scp -r backend root@<target-ip>:/tmp/zmb-webui-backend
ssh root@<target-ip>
cd /tmp/zmb-webui-backend
sudo bash check_system.sh
sudo bash install.sh
```

### Option C: LXC Container

```bash
# Host-Seite:
lxc launch images:debian/bookworm zmb-webui
lxc config device add zmb-webui tank disk \
    source=/tank/share \
    path=/tank/share
lxc config device add zmb-webui http proxy \
    listen=tcp:0.0.0.0:9090 \
    connect=tcp:127.0.0.1:8000

# Container-Seite:
lxc exec zmb-webui -- bash
cd /opt && git clone <repo> zmb-webui && cd zmb-webui/backend
bash check_system.sh
bash install.sh
```

## 3. Verify Installation

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

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

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

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

## 4. Post-Installation

### Change Admin Password (WICHTIG!)

```bash
sudo python3 /opt/zmb-webui/backend/manage_users.py change-password admin
```

### Configure Firewall

```bash
# Expose Port 9090 (if using nginx reverse proxy)
sudo ufw allow 9090/tcp

# Or just 8000 internally + nginx on 9090
sudo ufw allow 9090/tcp  # nginx
# Port 8000 internal nur für nginx
```

### Setup Reverse Proxy (Optional)

```bash
# nginx example:
sudo tee /etc/nginx/sites-available/zmb-webui > /dev/null <<EOF
server {
    listen 9090 ssl http2;
    server_name _;
    
    ssl_certificate /etc/ssl/certs/zmb-webui.crt;
    ssl_certificate_key /etc/ssl/private/zmb-webui.key;
    
    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade \$http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host \$host;
        proxy_set_header X-Real-IP \$remote_addr;
    }
}
EOF

sudo systemctl enable nginx
sudo systemctl start nginx
```

## 5. Platform-Spezific Notes

### Raspberry Pi 4/5 (ARM64)

```bash
# Installiert automatisch für Debian
# Alles läuft native ARM64
# Performance: ~100ms pro Pool-Query

# Hinweis: npm build (~30min) besser auf x86 machen
```

### Debian/Ubuntu x86_64

```bash
# Standard x86-64 Installation
# Performance: ~20ms pro Pool-Query
# npm build: ~5min

# Ideal für production builds
```

### LXC Container

```bash
# Backend läuft im Container
# ZFS Mount vom Host (/tank/share)
# File Manager funktioniert mit gemounteten Shares

# ZFS Pool-Operations:
# - zfs list: funktioniert (liest Host-Pools)
# - zpool scrub: nur vom Host aus

# Unprivilegiert (Recommended):
lxc launch images:debian/bookworm zmb-webui
# vs Privilegiert (nur wenn Pool-Management im Container nötig):
lxc launch images:debian/bookworm zmb-webui --config security.privileged=true
```

### Proxmox VM

```bash
# Wie Bare Metal x86/AMD64
# VM mit ≥2GB RAM empfohlen
# Storage: ≥10GB für /opt/zmb-webui
```

## 6. Troubleshooting

### Installation schlägt fehl

```bash
# 1. check_system.sh erneut laufen
bash check_system.sh

# 2. Dependencies manuell installieren
sudo apt update
sudo apt install python3-venv python3-pip python3-dev
sudo apt install zfsutils-linux zfs-auto-snapshot
```

### Service startet nicht

```bash
# Logs prüfen
sudo journalctl -u zmb-webui-backend -n 50

# Manuell testen
cd /opt/zmb-webui/backend
python3 main.py

# Falls Python-Fehler: Virtual env aktivieren
source /opt/zmb-webui/venv/bin/activate
python3 main.py
```

### API antwortet nicht

```bash
# Port prüfen
sudo netstat -tlnp | grep 8000

# Firewall prüfen
sudo ufw status
sudo ufw allow 8000/tcp

# Prozess prüfen
ps aux | grep uvicorn
```

### File Manager funktioniert nicht

```bash
# /tank/share prüfen
ls -la /tank/share

# Permission prüfen
stat /tank/share

# ZFS Mount prüfen
zfs list | grep share
```

## 7. Updating

```bash
# Backend updaten
cd /opt/zmb-webui/backend
git pull origin main
pip install -r requirements.txt
sudo systemctl restart zmb-webui-backend

# Frontend updaten (später mit Phase 2)
```

## 8. Uninstall

```bash
# Service stoppen
sudo systemctl stop zmb-webui-backend
sudo systemctl disable zmb-webui-backend

# Service entfernen
sudo rm /etc/systemd/system/zmb-webui-backend.service
sudo systemctl daemon-reload

# Verzeichnis entfernen
sudo rm -rf /opt/zmb-webui

# Python Packages entfernen (optional)
sudo rm -rf /root/.venv
```

## 9. Backup

```bash
# Entire installation
sudo tar czf zmb-webui-backup.tar.gz /opt/zmb-webui

# Users config nur
sudo cp /opt/zmb-webui/backend/config/users.json \
    zmb-webui-users-backup.json

# Systemd unit
sudo cp /etc/systemd/system/zmb-webui-backend.service \
    zmb-webui-backend.service.backup
```

## 10. Support Plattformen

| Plattform | Status | Notes |
|-----------|--------|-------|
| Raspberry Pi 4/5 | ✓ Supported | Primary, ARM64 |
| Debian 11/12 x86_64 | ✓ Supported | Production ready |
| Ubuntu 22.04+ x86_64 | ✓ Supported | Production ready |
| RHEL/CentOS 8+ | ✓ Supported | Nutze install-rhel.sh |
| LXC Container | ✓ Supported | Host hat ZFS |
| Alpine Linux | ⚠️ Limited | Nutzt OpenRC statt systemd |
| Docker | ❌ Not Supported | (kein Plan) |

---

**Ready to install? Start with `bash check_system.sh`!** 🚀