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:26:23 +02:00
commit 92bed208e0
108 changed files with 29925 additions and 0 deletions
@@ -0,0 +1,206 @@
+# ZMB Webui Frontend
+
+Modern Next.js 15 web UI for ZFS storage management. Built with TypeScript, Tailwind CSS, and ISR optimization for performance on resource-constrained systems.
+
+## Features
+
+- **Dashboard**: Real-time pool status, capacity visualization, health monitoring
+- **Snapshots**: Create, manage, and delete ZFS snapshots
+- **File Manager**: Browse and manage files (coming soon)
+- **Authentication**: JWT-based login with password hashing
+- **Responsive Design**: Works on mobile, tablet, and desktop
+- **Performance**: ISR (Incremental Static Regeneration) for fast page loads
+- **Dark Mode Ready**: Full dark mode support with Tailwind CSS
+
+## Quick Start
+
+### Prerequisites
+
+- Node.js 18+ (for development)
+- npm or yarn
+- FastAPI backend running on http://localhost:8000
+
+### Local Development
+
+```bash
+# Install dependencies
+npm install
+
+# Start development server
+npm run dev
+
+# Open http://localhost:3000 in your browser
+```
+
+### Production Build
+
+```bash
+# Build for production
+npm run build
+
+# Start production server
+npm start
+
+# Or export to static HTML
+npm run export
+```
+
+## Configuration
+
+Copy `.env.example` to `.env.local` and update the API URL:
+
+```bash
+cp .env.example .env.local
+```
+
+Edit `.env.local`:
+```
+NEXT_PUBLIC_API_URL=http://your-backend-host:8000
+```
+
+## Architecture
+
+### Pages
+
+- `/` - Dashboard (pool overview)
+- `/login` - Authentication
+- `/snapshots` - Snapshot management
+- `/files` - File browser (coming soon)
+
+### Components
+
+- `PoolCard` - Individual pool display with health/capacity
+- `Header` - Navigation and user menu
+- UI components (Card, Button, Badge, Progress)
+
+### API Client
+
+`lib/api.ts` - TypeScript client for FastAPI backend with:
+- Authentication (login/logout)
+- Pool management
+- Snapshot operations
+- File browsing
+- System information
+
+## Performance Optimizations
+
+### For 4GB RAM Systems
+
+- **ISR Strategy**: 
+  - Dashboard revalidates every 30s
+  - Snapshots revalidate every 60s
+  - Static pages cached long-term
+  
+- **Bundle Optimization**:
+  - Tree-shaking for unused imports
+  - Dynamic imports for heavy components
+  - Compression enabled by default
+
+- **Caching**:
+  - Browser caching for assets
+  - In-memory API response caching
+  - Service worker support ready
+
+## Development
+
+### Add a New Page
+
+```bash
+# Create app/new-feature/page.tsx
+mkdir app/new-feature
+touch app/new-feature/page.tsx
+```
+
+### Add a New Component
+
+```bash
+# Create components/MyComponent.tsx
+touch components/MyComponent.tsx
+```
+
+### Use the API Client
+
+```typescript
+import { api } from "@/lib/api"
+
+// Login
+await api.login("admin", "password")
+
+// Get pools
+const pools = await api.getPools()
+
+// Get snapshots
+const snapshots = await api.getSnapshots()
+```
+
+## Deployment
+
+### On Raspberry Pi / ARM64
+
+```bash
+# Build on faster x86 machine
+npm run build
+
+# Copy .next directory to Pi
+scp -r .next pi@10.66.120.3:/opt/zmb-webui/frontend/
+
+# Or build directly on Pi (slower)
+npm run build
+npm start
+```
+
+### With nginx
+
+```nginx
+server {
+    listen 443 ssl http2;
+    server_name zmb-webui.example.com;
+
+    ssl_certificate /path/to/cert.pem;
+    ssl_certificate_key /path/to/key.pem;
+
+    location / {
+        proxy_pass http://localhost:3000;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection 'upgrade';
+        proxy_set_header Host $host;
+        proxy_cache_bypass $http_upgrade;
+    }
+}
+```
+
+### Systemd Service
+
+See `../deploy/zmb-webui-frontend.service` for service configuration.
+
+## Troubleshooting
+
+### Port 3000 already in use
+
+```bash
+# Use different port
+npm run dev -- -p 3001
+```
+
+### API connection refused
+
+Check `.env.local` points to correct backend URL:
+```bash
+NEXT_PUBLIC_API_URL=http://localhost:8000
+```
+
+### Build hangs on ARM64
+
+The Node.js build process can be slow on Raspberry Pi. Either:
+1. Build on faster x86 machine and copy artifacts
+2. Increase available RAM/swap
+3. Use pre-built Docker image
+
+## Contributing
+
+See main project README for contribution guidelines.
+
+## License
+
+Same as parent project