zmb-webui/memory/multiarch_requirements.md at 6f6e8555af2f47d1c46722ac40384e311050ca00

Files

T

Claude Code 6d74d874b6 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>

2026-04-22 00:43:05 +02:00

3.8 KiB

Raw Blame History

name, description, type

name	description	type
Multi-Architektur Support	Backend und Frontend müssen auf ARM64, x86, und AMD64 laufen	feedback

Das System muss auf mehreren CPU-Architekturen funktionieren:

Why: Der Pi ist ARM64, aber Production-Server sind oft x86/AMD64. Development kann auf verschiedenen Maschinen stattfinden.

How to apply:

Backend (Python/FastAPI)

✅ Bereits kompatibel – Python ist plattformübergreifend:

Keine CPU-spezifischen Dependencies
subprocess.run() funktioniert überall
Nur: pwd/grp/pathlib/socket = Standard Library (überall verfügbar)

⚠️ Zu achten:

psutil optional (nur in system_info.py, mit Fallback)
Systemd-spezifisch: systemctl, useradd, groupdel – nur auf Linux
ZFS Tools müssen installiert sein (zpool, zfs Binaries)

✓ Test vor Deployment:

# ARM64 Pi:
python3 main.py
# x86/AMD64 Server:
python3 main.py

Frontend (Next.js/React)

⚠️ Wichtig: Next.js baut zu JavaScript/HTML – läuft überall:

npm run build auf jedem OS (Windows/Mac/Linux)
Output ist plattformunabhängig (static HTML/JS)
Runtime (Node.js) auch auf allen Architekturen

⚠️ Aber: Build kann unterschiedlich lange dauern:

Pi: 20-30min (ARM64 ist langsam)
x86/AMD64: 2-5min

Strategie: Build auf stärkerem Server, Deploy überall.

Deployment-Matrix

┌──────────────┬────────────┬────────────┬──────────────┐
│ Architektur  │ Python     │ Next.js    │ ZFS Tools    │
├──────────────┼────────────┼────────────┼──────────────┤
│ ARM64 (Pi)   │ ✓ läuft    │ ✓ läuft    │ ✓ installiert│
│ x86 (32bit)  │ ✓ läuft    │ ✓ läuft    │ ✓ paket      │
│ AMD64 (64bit)│ ✓ läuft    │ ✓ läuft    │ ✓ paket      │
│ x86_64       │ ✓ läuft    │ ✓ läuft    │ ✓ paket      │
└──────────────┴────────────┴────────────┴──────────────┘

Wichtige Gotchas

1. Binaries in subprocess

❌ FALSCH: subprocess.run(["zpool", ...]) – setzt zpool im PATH voraus
✓ RICHTIG: Ist OK, wird z.B. which zpool zur Laufzeit geprüft
Aber: Dokumentation muss erwähnen "ZFS Tools müssen installiert sein"

2. systemd Service

Pi (Debian/Raspberry Pi OS): ✓ Hat systemd
x86 (Ubuntu/Debian): ✓ Hat systemd
AMD64 (CentOS/RHEL): ✓ Hat systemd
Alpine Linux: ✗ Nutzt OpenRC (andere config nötig)

3. File Paths

Pi: /opt/zmb-webui/backend
x86/AMD64: Gleich OK

4. Package Manager

Pi (Debian): apt
Ubuntu: apt
RHEL/CentOS: dnf / yum

Deployment Instructions

Für ARM64 Pi:

sudo bash backend/install.sh
# Autodetekt: Debian-based → apt

Für x86/AMD64 (Debian/Ubuntu):

sudo bash backend/install.sh
# Autodetekt: Debian-based → apt

Für x86/AMD64 (RHEL/CentOS):

# Manuell oder create backend/install-rhel.sh

Zu tun vor Production

✓ Python Code: Schon arch-agnostisch
⚠️ install.sh: Muss os-release checken statt zu assumieren
⚠️ Systemd Service: Optional: create RHEL variant
⚠️ Frontend Build: Dokumentieren dass auf stärkerem System gebaut wird
✓ Dependencies: Alle plattformübergreifend verfügbar

Architektur-Check-Script

# vor Deployment checken:
#!/bin/bash
echo "Architecture: $(uname -m)"
echo "OS: $(lsb_release -ds)"
echo "Python: $(python3 --version)"
echo "ZFS: $(zpool list 2>/dev/null && echo 'installed' || echo 'NOT installed')"
echo "systemd: $(systemctl 2>/dev/null && echo 'yes' || echo 'no')"

3.8 KiB Raw Blame History Unescape Escape