ZMB Webui: Complete Project – Rebrand & Initial Clean Commit
ARCHITECTURE ============ Backend: FastAPI + uvicorn (port 8000) - JWT authentication with PAM system users - ZFS CLI wrapper with caching (30-60s TTL) - WebSocket pool status broadcaster (30s interval) - Services: auth, zfs_runner, file_manager, shares, identities, system_info - Routers: pools, datasets, snapshots, shares, identities, navigator, system Frontend: Next.js 15 + TypeScript (static export) - Incremental Static Regeneration (ISR) for weak hardware - Type-safe API client (lib/api.ts) - Dark mode + custom Tailwind theme - Pages: Dashboard, Login, Snapshots, Datasets, Shares, etc. DEPLOYMENT ========== Test Target: 192.168.1.179:8090 (Debian LXC) Production: 10.66.120.3:9090 (Raspberry Pi 4GB ARM64) Updater: Automated Gitea-based deployment (update-test.sh, update-pi.sh) FEATURES COMPLETED ================== Phase 3a: Dashboard Quick Stats (System, CPU, Memory, Storage) - Real-time stats with color-coded progress bars - Responsive grid layout (mobile: 1, tablet: 2, desktop: 4 columns) - ISR-optimized for fast loads on weak hardware REBRANDING ========== Renamed throughout: - Project: 'ZFS Manager' → 'ZMB Webui' - Services: 'zfs-manager' → 'zmb-webui' - Systemd units: zfs-manager-backend → zmb-webui-backend - Configuration files and documentation Co-Authored-By: Patrick <patrick@perlbach24.de>
This commit is contained in:
Claude Code
@@ -0,0 +1,299 @@
|
||||
# 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`!** 🚀
|
||||
Reference in New Issue
Block a user