Self-Hosted NAS Management Platform
A full-stack web interface for managing your Network Attached Storage — file management, RAID monitoring, system telemetry, power control, VPN, and more.
Deployed since January 25, 2026 on Debian 13 (Ryzen 5 5600GT, 16GB RAM).
| Component | Status | Details |
|---|---|---|
| Server | Active | Debian 13, systemd managed |
| Database | PostgreSQL 17.7 | With Alembic migrations |
| Proxy | Nginx | Port 80, rate limiting, security headers |
| Backend | Systemd | 4 Uvicorn workers, auto-restart |
| Testing | 1465 tests | 82 test files, CI/CD via GitHub Actions |
| Monitoring | Prometheus/Grafana | Ready |
- Drag & drop upload with chunked transfer (32MB chunks)
- File preview (images, videos, audio, PDFs, text)
- File sharing with public links, expiration & password protection
- Per-user storage quotas and ownership tracking
- Multi-mountpoint support (multiple RAID arrays)
- Real-time RAID array status (RAID 0, 1, 5, 6, 10)
- SMART disk health monitoring
- RAID setup wizard with guided array creation
- OS-disk protection (prevents formatting boot drives)
- Dev-mode simulation for testing without hardware
- Per-thread CPU usage (Task Manager-style)
- Memory, network throughput, disk I/O metrics
- Historical telemetry with Recharts visualizations
- Monitoring orchestrator with configurable collectors
- Prometheus metrics export
- CPU frequency scaling (AMD Ryzen & Intel)
- PWM fan control with custom temperature curves
- Fan scheduling (time-based curve selection)
- Energy monitoring via Tapo smart plugs (P110/P115)
- Sleep mode management
- WireGuard VPN server with client management
- WebDAV server for network drive mounting
- Samba/SMB sharing
- mDNS/Bonjour auto-discovery
- Pi-hole DNS integration
- JWT authentication with role-based access (admin/user)
- Rate limiting on all endpoints (slowapi)
- Security headers (CSP, HSTS, X-Frame-Options)
- Path jailing for user file isolation
- Audit logging for all security-relevant actions
- Encrypted VPN/SSH keys (Fernet AES)
- Scheduler dashboard with execution history
- Service health monitoring
- Secure read-only database inspection (sensitive fields redacted)
- Cloud import (rclone integration)
- Plugin system
- Self-hosted update mechanism
- System benchmarking
- BaluHost — Web UI (this repo)
- BaluDesk — Desktop sync client (C++/Electron)
- BaluApp — Android app (Kotlin)
- TUI — Terminal UI via Textual (
baluhost-tui)
# Start both backend (port 3001) and frontend (port 5173)
python start_dev.pyThis sets NAS_MODE=dev, creates a simulated RAID1 sandbox in backend/dev-storage/, and provides mock system data. Works on Windows, macOS, and Linux.
Default dev credentials: admin / DevMode2024
Open http://localhost:5173 in your browser.
# Backend
cd backend
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
uvicorn app.main:app --reload --port 3001
# Frontend (separate terminal)
cd client
npm install
npm run devSee Production Quickstart for full instructions.
# Fresh install (modular installer)
sudo ./deploy/install/install.sh
# Or via systemd (if already installed)
sudo systemctl start baluhost-backendProduction runs at /opt/baluhost with:
- 4 Uvicorn workers on port 8000 (behind Nginx)
- Nginx serves static frontend (
client/dist/) and proxies/api/* - PostgreSQL 17.7 for data persistence
- Auto-deploy on push to
mainvia GitHub Actions (self-hosted runner)
push to main → CI checks (GitHub-hosted) → Deploy (self-hosted on NAS)
├── DB backup (pg_dump)
├── git pull + pip install
├── Alembic migrations
├── Frontend build (npm)
├── Service restart
└── Health check (auto-rollback on failure)
See Infrastructure and Emergency Runbook for operational details.
BaluHost/
├── backend/ # Python FastAPI
│ ├── app/
│ │ ├── api/routes/ # 51 API route modules
│ │ ├── services/ # 143 service modules
│ │ ├── models/ # 42 SQLAlchemy ORM models
│ │ ├── schemas/ # 41 Pydantic schemas
│ │ ├── core/ # Config, security, database
│ │ └── middleware/ # Security headers, rate limiting
│ ├── baluhost_tui/ # Terminal UI (Textual)
│ ├── tests/ # 82 test files
│ └── alembic/ # 74 database migrations
├── client/ # React + TypeScript + Vite
│ └── src/
│ ├── pages/ # 31 page components
│ ├── components/ # 30+ component directories
│ ├── api/ # Typed API clients
│ ├── hooks/ # Custom React hooks
│ ├── contexts/ # Auth context
│ └── lib/ # Utilities, formatters
├── deploy/ # Deployment configs
│ ├── nginx/ # Reverse proxy configs
│ ├── systemd/ # Service files
│ ├── samba/ # SMB configuration
│ ├── prometheus/ # Metrics scraping
│ └── grafana/ # Dashboard templates
├── docs/ # Documentation
├── .github/workflows/ # CI/CD pipelines
├── start_dev.py # Dev launcher
└── start_prod.py # Production launcher
Tech Stack:
- Frontend: React 18, TypeScript, Vite, Tailwind CSS, Recharts, Lucide icons
- Backend: FastAPI, SQLAlchemy 2.0, Pydantic, Uvicorn
- Database: SQLite (dev) / PostgreSQL (prod), Alembic migrations
- Testing: Pytest (backend), Vitest + Playwright (frontend)
Interactive API docs at http://localhost:3001/docs (Swagger UI) or /redoc.
All routes prefixed with /api:
| Area | Endpoints | Description |
|---|---|---|
| Auth | /auth/login, /auth/register, /auth/me, /auth/refresh |
JWT authentication |
| Files | /files/list, /files/upload, /files/download, ... |
File CRUD operations |
| Shares | /shares, /shares/public/{token} |
Public link sharing |
| Users | /users (admin) |
User management |
| System | /system/info, /system/storage, /system/raid/*, /system/smart/* |
System & RAID info |
| Monitoring | /monitoring/cpu, /monitoring/memory, /monitoring/network, ... |
Real-time metrics |
| Power | /power/profile, /power/presets |
CPU frequency scaling |
| Fans | /fans/config, /fans/status |
Fan control & curves |
| Energy | /energy/stats |
Power consumption |
| Tapo | /tapo/plugs, /tapo/readings |
Smart plug integration |
| VPN | /vpn/clients, /vpn/config |
WireGuard management |
| Backup | /backup, /backup/{id}/restore |
Backup & restore |
| Sync | /sync/folders, /sync/conflicts |
Desktop sync |
| Mobile | /mobile/register, /mobile/devices |
Mobile device pairing |
| Schedulers | /schedulers, /schedulers/{name}/run-now |
Scheduler control |
| Admin | /admin-db/*, /admin/* |
Database inspection, services |
| Logging | /logging/audit, /logging/disk-io |
Audit trail |
| Pi-hole | /pihole/* |
DNS management |
| Plugins | /plugins/* |
Plugin system |
NAS_MODE=dev # dev or prod
SECRET_KEY=... # 32+ chars required in prod
TOKEN_SECRET=... # 32+ chars required in prod
DATABASE_URL=... # PostgreSQL URL (prod)
NAS_STORAGE_PATH=./dev-storage
NAS_QUOTA_BYTES=5368709120
TELEMETRY_INTERVAL_SECONDS=3.0VITE_API_BASE_URL=http://localhost:3001The Vite dev server proxies /api requests to port 3001 automatically (see client/vite.config.ts).
# Backend
cd backend
python -m pytest # All tests
python -m pytest tests/test_permissions.py # Specific test
python -m pytest -v # Verbose
# Frontend
cd client
npm run test # Vitest unit tests
npm run test:e2e # Playwright E2E tests
npm run build # Type-check + production build| Document | Description |
|---|---|
| Technical Documentation | Complete feature reference |
| Architecture | System design & patterns |
| Production Readiness | Deployment checklist |
| Production Quickstart | Getting started in prod |
| User Guide | End-user manual |
| API Reference | Full API documentation |
| Security Policy | Security guidelines |
| Contributing | Contribution workflow |
| Changelog | Version history |
| TODO | Roadmap |
docs/
├── api/ # API documentation
├── deployment/ # Deployment & ops guides
├── features/ # Feature-specific docs
├── getting-started/ # User guide & dev checklist
├── monitoring/ # Monitoring & telemetry setup
├── network/ # Network & VPN configuration
├── security/ # Security & audit logging
└── storage/ # RAID & backup guides
| Metric | Count |
|---|---|
| Version |  |
| Backend code | ~120,000 lines |
| Frontend code | ~67,000 lines |
| Test functions | 1465 |
| API route modules | 51 |
| Service modules | 143 |
| Database models | 42 |
| Database migrations | 74 |
| Frontend pages | 31 |
| CI/CD workflows | 7 |
Created by Xveyn