zmb-webui/README.md

ZMB Webui

Web-UI für ZFS und Samba/NFS-Verwaltung auf Linux-Systemen. Ersetzt Cockpit auf dem Raspberry Pi.

Stack: Python/FastAPI + HTMX + Jinja2 — kein Node.js, kein Build-Schritt.

Zielplattformen:

• Raspberry Pi (ARM64, 4GB RAM+) — Primärziel
• Debian/Ubuntu Server (x86_64 oder ARM64)
• LXC Container (privilegiert)

---

Voraussetzungen

apt-get update
apt-get install -y \
  python3 python3-pip python3-venv python3-pam \
  zfsutils-linux samba nfs-kernel-server nginx curl git

---

Installation

1. Repository klonen

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

2. Python Virtual Environment

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

3. Systemd Service

sudo tee /etc/systemd/system/zmb-webui-backend.service > /dev/null << 'EOF'
[Unit]
Description=ZMB Webui Backend
After=network.target

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

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now zmb-webui-backend
sudo systemctl status zmb-webui-backend

4. Nginx (HTTPS Reverse Proxy auf Port 8090)

# Self-signed Zertifikat
mkdir -p /etc/nginx/ssl
openssl req -x509 -nodes -days 3650 -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"
chmod 600 /etc/nginx/ssl/zmb-webui.key

# Nginx Config
tee /etc/nginx/sites-available/zmb-webui > /dev/null << 'EOF'
server {
    listen 8090 ssl http2;
    listen [::]:8090 ssl http2;
    server_name _;

    ssl_certificate     /etc/nginx/ssl/zmb-webui.crt;
    ssl_certificate_key /etc/nginx/ssl/zmb-webui.key;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_read_timeout 60s;
    }
}
EOF

ln -s /etc/nginx/sites-available/zmb-webui /etc/nginx/sites-enabled/
nginx -t && systemctl restart nginx

5. Samba Registry (empfohlen)

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

systemctl restart smbd

---

Benutzerverwaltung

Jeder Linux-Systembenutzer mit Login-Shell kann sich anmelden. Kein separates User-Management nötig.

# Benutzer anlegen
useradd -m -s /bin/bash username
passwd username

# Zugang entziehen
usermod -s /usr/sbin/nologin username

Der Backend-Dienst muss als root laufen (PAM benötigt /etc/shadow-Zugang).

---

Deployment-Update

# Backend synchronisieren
rsync -a backend/ root@<ziel-ip>:/opt/zmb-webui/backend/

# Service neu starten
ssh root@<ziel-ip> 'systemctl restart zmb-webui-backend'

---

Logs & Diagnose

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

# Service-Status
systemctl status zmb-webui-backend

# API-Docs (lokal)
curl http://localhost:8000/docs

---

Projektstruktur

backend/
├── main.py              # FastAPI App, Router-Mounting
├── routers/             # API-Endpunkte + HTML-Seiten
│   ├── pages.py         # Jinja2-Seitenrouten + HTMX-Fragmente
│   ├── auth.py          # JWT Login
│   ├── pools.py         # ZFS Pools
│   ├── datasets.py      # ZFS Datasets
│   ├── snapshots.py     # ZFS Snapshots
│   ├── shares.py        # Samba/NFS Shares
│   ├── identities.py    # Benutzer/Gruppen
│   ├── navigator.py     # Datei-Browser
│   └── system.py        # System-Infos
├── services/            # Business Logic
├── templates/           # Jinja2 HTML Templates
├── static/              # htmx.min.js, pico.min.css (vendored)
├── models/              # Pydantic Models
└── requirements.txt

---

Hinweise

• ZFS auf LXC: Privilegierter Container benötigt zpool-Binary. ZFS-Verfügbarkeit wird beim Start geprüft, graceful degradation wenn nicht vorhanden.
• Container-Erkennung: systemd-detect-virt — Disk-I/O-Stats werden auf LXC ausgeblendet.
• CORS: Standard * (Entwicklung). Für Produktion ZMB_CORS_ORIGINS Umgebungsvariable setzen.
• Samba Config: Registry-basiert (net conf). Werte mit - am Anfang brauchen ---Separator bei net conf setparm.