zmb-webui/INSTALL_GUIDE.md

Installation Guide – All Platforms

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

1. System Check

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)

# 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

# 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

# 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

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

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

Configure Firewall

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

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

# 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

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

# Ideal für production builds

LXC Container

# 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

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

6. Troubleshooting

Installation schlägt fehl

# 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

# 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

# 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

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

# Permission prüfen
stat /tank/share

# ZFS Mount prüfen
zfs list | grep share

7. Updating

# 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

# 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

# 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! 🚀