ZMB Webui - Installation Guide

ZMB Webui ist eine moderne Web-UI für ZFS und Samba/NFS Verwaltung auf Linux-Systemen. Dieses Dokument beschreibt die Installation auf Ubuntu/Debian.

Zielplattformen:

• Raspberry Pi (ARM64, 4GB RAM+)
• Debian/Ubuntu Server (x86_64 oder ARM64)
• LXC Container

Voraussetzungen

System

• OS: Ubuntu 20.04+ oder Debian 11+
• RAM: Minimal 2GB (4GB empfohlen)
• Disk: Minimal 500MB für Installation
• Root-Zugang erforderlich

Abhängigkeiten

# ZFS und System-Tools
apt-get update
apt-get install -y \
  python3.9+ \
  python3-pip \
  python3-venv \
  zfsutils-linux \
  samba \
  nfs-kernel-server \
  nginx \
  curl \
  git

# Node.js (für Frontend-Build)
# Optional, nur wenn du das Frontend selbst bauen möchtest
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
apt-get install -y nodejs

# Samba-Admin-Tools
apt-get install -y samba-client samba-dsdb-modules

Installation

1. Repository klonen

cd /opt
git clone https://gitea.perlbach24.de/patrick/zmb-webui.git
cd zmb-webui

2. Backend Setup

2.1 Python Virtual Environment erstellen

cd backend
python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip setuptools wheel
pip install -r requirements.txt

2.2 Admin-Benutzer erstellen

python3 << 'EOF'
from services.auth import auth_service

# Erstelle einen Admin-Benutzer
username = input("Benutzername: ")
password = input("Passwort: ")

auth_service.add_user(username, password)
print(f"✓ Benutzer '{username}' erstellt")
EOF

Oder über System-Benutzer:

# Erstelle einen System-Benutzer
useradd -m -s /bin/false webadmin
echo "webadmin:mypassword123" | chpasswd

# Der Benutzer kann sich dann mit diesem Passwort anmelden

3. Frontend Setup

3.1 Frontend bauen (empfohlen auf schnellerem System)

Option A: Lokal bauen und deployen (schneller)

cd frontend

# Abhängigkeiten installieren
npm install

# Build für statischen Export
npm run build
# Erstellt ./out/ mit fertigen HTML-Dateien

# Output prüfen
ls -la out/ | grep -E "\.html|index"

Option B: Direkt auf dem Ziel-System bauen

# Auf dem Ziel-System
ssh root@192.168.1.179  # oder deine IP

cd /opt/zmb-webui/frontend
npm install
npm run build

4. Deployment auf Ziel-System

4.1 Backend deployen

# Von deinem lokalen Rechner
scp -r backend root@192.168.1.179:/opt/zmb-webui/

# Oder via rsync
rsync -avz backend/ root@192.168.1.179:/opt/zmb-webui/backend/

4.2 Frontend deployen

# Von deinem lokalen Rechner (nach npm run build)
rsync -avz --delete frontend/out/ root@192.168.1.179:/opt/zmb-webui/frontend/

5. Systemd Service Setup

5.1 Service-Datei erstellen

sudo cp deploy/zfs-manager-backend.service /etc/systemd/system/zmb-webui-backend.service

Überprüfe die Datei:

sudo cat /etc/systemd/system/zmb-webui-backend.service

Inhalt sollte etwa so aussehen:

[Unit]
Description=ZMB Webui Backend API
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/zmb-webui/backend
Environment="PATH=/opt/zmb-webui/venv/bin"
ExecStart=/opt/zmb-webui/venv/bin/python -m uvicorn main:app --host 0.0.0.0 --port 8000
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

5.2 Service aktivieren und starten

sudo systemctl daemon-reload
sudo systemctl enable zmb-webui-backend
sudo systemctl start zmb-webui-backend

# Status prüfen
sudo systemctl status zmb-webui-backend

6. Nginx Konfiguration

6.1 Nginx Config erstellen

sudo tee /etc/nginx/sites-available/zmb-webui > /dev/null << 'EOF'
server {
    listen 8090 ssl http2;
    listen [::]:8090 ssl http2;
    
    server_name _;
    
    # SSL-Zertifikate (self-signed für Entwicklung)
    ssl_certificate /etc/nginx/ssl/zmb-webui.crt;
    ssl_certificate_key /etc/nginx/ssl/zmb-webui.key;
    
    root /opt/zmb-webui/frontend;
    index index.html;
    
    # Frontend - statische HTML
    location / {
        try_files $uri $uri/ /index.html;
        expires 1h;
        add_header Cache-Control "public, max-age=3600";
    }
    
    # Backend API - Proxy
    location /api/ {
        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;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 60s;
    }
    
    # WebSocket
    location /ws {
        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_read_timeout 86400;
    }
    
    # Health check
    location /health {
        proxy_pass http://127.0.0.1:8000/health;
    }
}
EOF

6.2 Self-signed SSL-Zertifikat erstellen

# SSL-Verzeichnis erstellen
sudo mkdir -p /etc/nginx/ssl

# Self-signed Zertifikat (gültig 365 Tage)
sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout /etc/nginx/ssl/zmb-webui.key \
  -out /etc/nginx/ssl/zmb-webui.crt \
  -subj "/CN=zmb-webui/O=Home/C=DE"

sudo chmod 600 /etc/nginx/ssl/zmb-webui.key

6.3 Nginx aktivieren und neustarten

sudo ln -s /etc/nginx/sites-available/zmb-webui /etc/nginx/sites-enabled/
sudo rm -f /etc/nginx/sites-enabled/default

# Konfiguration testen
sudo nginx -t

# Neustarten
sudo systemctl restart nginx

7. Samba Registry Setup (optional aber empfohlen)

# Samba konfigurieren um Registry statt smb.conf zu nutzen
sudo bash /opt/zmb-webui/deploy/setup-samba-registry.sh

Oder manuell:

# Minimale smb.conf erstellen
sudo tee /etc/samba/smb.conf > /dev/null << 'EOF'
[global]
    include = registry
EOF

# Samba neustarten
sudo systemctl restart smbd

Erste Schritte

1. Zugriff auf WebUI

Öffne in deinem Browser:

https://192.168.1.179:8090

(Ersetze die IP mit deiner Ziel-System IP)

2. Login

• Benutzername: Der Admin-Benutzer, den du erstellt hast
• Passwort: Das Passwort, das du gesetzt hast

3. Navigation

Nach Login siehst du:

• Dashboard - Pool Status, Quick Stats
• Shares - Samba und NFS Shares verwalten
• File Sharing - Samba Global Config (Samba Registry Parameter)
• Navigator - Datei-Browser
• Identities - Benutzer und Gruppen
• Logs - System Logs

Samba Global Configuration

Die Samba Global Configuration wird vom Samba Registry gelesen:

# Zeige alle Global Parameters
net conf list

# Zeige einen Parameter
net conf getparm global "log level"

# Setze einen Parameter
net conf setparm global "log level" 3

Diese Parameter können auch über die WebUI unter /shares → "Samba Config" Tab bearbeitet werden.

NFS Configuration

NFS Exports werden in /etc/exports gespeichert:

# Zeige alle Exports
cat /etc/exports

# Reload nach Änderungen
exportfs -r

Diese können auch über die WebUI unter /shares → "NFS" Tab bearbeitet werden.

Troubleshooting

Backend startet nicht

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

# Manuell starten (für Fehlerausgabe)
cd /opt/zmb-webui/backend
source venv/bin/activate
python -m uvicorn main:app --host 0.0.0.0 --port 8000

Frontend lädt nicht

# Nginx logs
sudo tail -f /var/log/nginx/error.log

# Überprüfe Dateien
ls -la /opt/zmb-webui/frontend/

Samba Fehler

# Samba Config testen
sudo testparm -s

# Samba Logs
sudo tail -f /var/log/samba/log.smbd

API Fehler 401 (Unauthorized)

• Token ist abgelaufen → Neu anmelden
• Falsche Anmeldedaten → Benutzer überprüfen

# Benutzer überprüfen/erstellen
cd /opt/zmb-webui/backend
source venv/bin/activate
python3 << 'EOF'
from services.auth import auth_service
auth_service.add_user("admin", "newpassword")
EOF

Performance Optimierung

Auf Raspberry Pi

# Gunicorn mit weniger Workers (spart RAM)
# In zmb-webui-backend.service:
# ExecStart=/opt/zmb-webui/venv/bin/gunicorn main:app \
#   --workers 2 --worker-class uvicorn.workers.UvicornWorker \
#   --bind 0.0.0.0:8000

# Cache TTL erhöhen (in services/zfs_runner.py)
CACHE_TTL = 120  # 2 Minuten statt 30 Sekunden

# Memory Monitor
free -h
watch -n 1 free -h

Auf x86_64 Server

# Mehr Workers nutzen
ExecStart=... --workers 4 ...

# Redis Cache (optional)
# Siehe CLAUDE.md für Details

Automatisches Update von Gitea

# Deploy-Script kopieren
cp deploy/update-from-gitea.sh /opt/zmb-webui/

# Executable machen
chmod +x /opt/zmb-webui/update-from-gitea.sh

# Cronjob erstellen (tägliches Auto-Update)
sudo tee /etc/cron.daily/zmb-webui-update > /dev/null << 'EOF'
#!/bin/bash
cd /opt/zmb-webui
./update-from-gitea.sh
EOF
sudo chmod +x /etc/cron.daily/zmb-webui-update

Sicherheit

⚠️ Für Produktion:

1. SSL-Zertifikat: Self-signed durch echtes Zertifikat ersetzen
2. CORS: In backend/main.py ändern:

   allow_origins = ["https://deine-domain.de"]  # statt ["*"]
   

3. Passwörter: Starke Passwörter verwenden
4. Firewall: Port 8090 nur für vertrauenswürdige IPs freigeben
5. Updates: Regelmäßig git pull und neu bauen

Dateistruktur nach Installation

/opt/zmb-webui/
├── backend/
│   ├── venv/                 # Python Virtual Environment
│   ├── main.py
│   ├── routers/              # API Endpoints
│   ├── services/             # Business Logic
│   ├── models/               # Pydantic Models
│   ├── requirements.txt
│   └── README.md
├── frontend/
│   ├── _next/                # Next.js Build Output
│   ├── app/                  # Next.js Pages
│   ├── components/           # React Components
│   ├── lib/                  # Utilities & API Client
│   ├── public/               # Static Files
│   ├── package.json
│   ├── *.html                # Generated Static Pages
│   └── README.md
├── deploy/
│   ├── zfs-manager-backend.service
│   ├── setup-samba-registry.sh
│   ├── update-from-gitea.sh
│   └── samba-template.conf
├── INSTALLATION.md           # Diese Datei
├── CLAUDE.md                 # Entwickler-Dokumentation
└── README.md                 # Feature-Übersicht

Weitere Dokumentation

• CLAUDE.md - Architektur, Entwicklung, Deployment
• backend/README.md - API-Endpoints, curl Beispiele
• frontend/README.md - Frontend-Konfiguration, Build-Options

---

Support: Bei Fragen oder Problemen, siehe CLAUDE.md oder kontaktiere patrick@perlbach24.de