From ea6b2503f202224c84050d638566a4e4d703b998 Mon Sep 17 00:00:00 2001 From: Patrick Date: Wed, 22 Apr 2026 01:59:28 +0200 Subject: [PATCH] =?UTF-8?q?Hinzuf=C3=BCgen:=20INSTALLATION.md=20mit=20umfa?= =?UTF-8?q?ssender=20Installationsanleitung?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Systemanforderungen und Abhängigkeiten - Schritt-für-Schritt Backend/Frontend Setup - Systemd Service Konfiguration - Nginx Reverse Proxy Setup mit SSL - Samba Registry Konfiguration - Troubleshooting und Performance-Tipps - Sicherheitsrichtlinien Co-Authored-By: Claude Haiku 4.5 --- INSTALLATION.md | 491 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 491 insertions(+) create mode 100644 INSTALLATION.md diff --git a/INSTALLATION.md b/INSTALLATION.md new file mode 100644 index 0000000..e0b1344 --- /dev/null +++ b/INSTALLATION.md @@ -0,0 +1,491 @@ +# 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 +```bash +# 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 + +```bash +cd /opt +git clone https://gitea.perlbach24.de/patrick/zmb-webui.git +cd zmb-webui +``` + +### 2. Backend Setup + +#### 2.1 Python Virtual Environment erstellen + +```bash +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 + +```bash +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: +```bash +# 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)** + +```bash +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** + +```bash +# 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 + +```bash +# 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 + +```bash +# 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 + +```bash +sudo cp deploy/zfs-manager-backend.service /etc/systemd/system/zmb-webui-backend.service +``` + +Überprüfe die Datei: +```bash +sudo cat /etc/systemd/system/zmb-webui-backend.service +``` + +**Inhalt sollte etwa so aussehen:** +```ini +[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 + +```bash +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 + +```bash +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 + +```bash +# 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 + +```bash +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) + +```bash +# Samba konfigurieren um Registry statt smb.conf zu nutzen +sudo bash /opt/zmb-webui/deploy/setup-samba-registry.sh +``` + +Oder manuell: + +```bash +# 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: + +```bash +# 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: + +```bash +# 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 + +```bash +# 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 + +```bash +# Nginx logs +sudo tail -f /var/log/nginx/error.log + +# Überprüfe Dateien +ls -la /opt/zmb-webui/frontend/ +``` + +### Samba Fehler + +```bash +# 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 + +```bash +# 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 + +```bash +# 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 + +```bash +# Mehr Workers nutzen +ExecStart=... --workers 4 ... + +# Redis Cache (optional) +# Siehe CLAUDE.md für Details +``` + +## Automatisches Update von Gitea + +```bash +# 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: + ```python + 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