Claude Code
92bed208e0
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>
207 lines
4.0 KiB
Markdown
207 lines
4.0 KiB
Markdown
# 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
|