Pouzor
177 lines
4.8 KiB
Markdown
177 lines
4.8 KiB
Markdown
# Homelable
|
|
|
|
A self-hosted, open-source tool to visually map, document and monitor your homelab infrastructure.
|
|
|
|
Interactive network canvas where each node is a physical machine, VM, LXC container, switch, or device. Nodes show live status, IPs, hostnames, and running services. Edges represent network links.
|
|
|
|
---
|
|
|
|
## Features
|
|
|
|
- **Interactive canvas** — drag, zoom, pan, snap-to-grid (React Flow)
|
|
- **11 node types** — ISP, router, switch, server, Proxmox, VM, LXC, NAS, IoT, AP, generic
|
|
- **Proxmox nested nodes** — VM/LXC rendered inside a resizable Proxmox group container
|
|
- **5 edge types** — ethernet, Wi-Fi, IoT, VLAN (color-coded), virtual
|
|
- **Live status** — per-node checks via ping / HTTP / HTTPS / SSH / TCP / Prometheus
|
|
- **Network scanner** — nmap-based discovery, approve/hide/ignore new devices
|
|
- **Auto-layout** — one-click Dagre hierarchical arrangement
|
|
- **Export** — download canvas as PNG
|
|
- **Dark theme** — neon accent colors, JetBrains Mono for technical values
|
|
- **Self-contained** — SQLite database, single config file, no cloud dependency
|
|
|
|
---
|
|
|
|
## Quick Start — Docker
|
|
|
|
```bash
|
|
git clone https://github.com/you/homelable.git
|
|
cd homelable
|
|
|
|
docker compose up -d
|
|
```
|
|
|
|
Open **http://localhost:3000** — login with `admin` / `admin`.
|
|
|
|
> Change the password before exposing to a network: edit `backend/config.yml` and replace `password_hash` with a new bcrypt hash.
|
|
>
|
|
> Generate a hash: `docker compose exec backend python -c "from passlib.context import CryptContext; print(CryptContext(schemes=['bcrypt']).hash('yourpassword'))"`
|
|
|
|
---
|
|
|
|
## Quick Start — Development
|
|
|
|
**Backend (Python 3.13):**
|
|
```bash
|
|
cd backend
|
|
python3.13 -m venv .venv && source .venv/bin/activate
|
|
pip install -r requirements.txt
|
|
cp .env.example .env # edit SECRET_KEY
|
|
uvicorn app.main:app --reload --port 8000
|
|
```
|
|
|
|
**Frontend:**
|
|
```bash
|
|
cd frontend
|
|
npm install
|
|
npm run dev # http://localhost:5173
|
|
```
|
|
|
|
Default login: `admin` / `admin`
|
|
|
|
---
|
|
|
|
## Proxmox LXC Install
|
|
|
|
Run inside a Debian/Ubuntu LXC container:
|
|
|
|
```bash
|
|
bash <(curl -fsSL https://raw.githubusercontent.com/you/homelable/main/scripts/lxc-install.sh)
|
|
```
|
|
|
|
This installs the backend as a systemd service and serves the frontend via nginx.
|
|
|
|
---
|
|
|
|
## Configuration
|
|
|
|
`backend/config.yml`:
|
|
|
|
```yaml
|
|
auth:
|
|
username: admin
|
|
password_hash: "$2b$12$..." # bcrypt hash
|
|
|
|
scanner:
|
|
ranges:
|
|
- "192.168.1.0/24" # CIDR ranges to scan
|
|
|
|
status_checker:
|
|
interval_seconds: 60 # how often to check node status
|
|
```
|
|
|
|
All settings are also editable in-app via the **Scan Network** button.
|
|
|
|
---
|
|
|
|
## Network Scanner
|
|
|
|
The scanner runs `nmap -sV --open` on your configured CIDR ranges and populates a **Pending Devices** queue. From the sidebar you can then approve (adds a node to the canvas), hide, or ignore each discovered device.
|
|
|
|
### Triggering a scan
|
|
|
|
Click **Scan Network** in the sidebar. The Scan History tab opens automatically and refreshes every 3 seconds until the scan completes. Errors are shown inline and as a toast notification.
|
|
|
|
### macOS / root privileges
|
|
|
|
Some nmap scan types (SYN scan, OS detection) require root. If the scan fails with a permissions error, run it manually with sudo using the included script:
|
|
|
|
```bash
|
|
cd backend
|
|
sudo python ../scripts/run_scan.py 192.168.1.0/24
|
|
|
|
# Multiple ranges:
|
|
sudo python ../scripts/run_scan.py 192.168.1.0/24 10.0.0.0/24
|
|
```
|
|
|
|
Results are written directly to the database and appear as Pending Devices in the UI without restarting the backend.
|
|
|
|
> On Linux the backend process itself can be given the `NET_RAW` capability instead of running as root:
|
|
> ```bash
|
|
> sudo setcap cap_net_raw+ep $(which nmap)
|
|
> ```
|
|
|
|
---
|
|
|
|
## Proxmox Nested Nodes
|
|
|
|
Proxmox nodes render as a resizable group container. VM and LXC nodes can be placed inside:
|
|
|
|
1. Add a **Proxmox VE** node to the canvas
|
|
2. Add a **VM** or **LXC** node — select the Proxmox node in the **Parent Proxmox** dropdown
|
|
3. The child node appears inside the group and moves with it
|
|
4. Select the Proxmox node to reveal resize handles (drag corners to expand)
|
|
|
|
---
|
|
|
|
## Node Check Methods
|
|
|
|
| Method | Description |
|
|
|--------|-------------|
|
|
| `ping` | ICMP ping |
|
|
| `http` | GET request, success if status < 500 |
|
|
| `https` | GET with TLS verify |
|
|
| `tcp` | TCP connect (target: `host:port`) |
|
|
| `ssh` | TCP connect to port 22 |
|
|
| `prometheus` | GET `/metrics` |
|
|
| `health` | GET `/health` |
|
|
|
|
---
|
|
|
|
## Stack
|
|
|
|
| Layer | Tech |
|
|
|-------|------|
|
|
| Frontend | React 18, TypeScript, Vite, React Flow v12, Zustand, Tailwind CSS, Shadcn/ui |
|
|
| Backend | FastAPI, SQLAlchemy async, SQLite, APScheduler, python-nmap |
|
|
| Auth | JWT (python-jose), bcrypt (passlib) |
|
|
| Deployment | Docker Compose, nginx, systemd |
|
|
|
|
---
|
|
|
|
## Development
|
|
|
|
```bash
|
|
# Backend tests
|
|
cd backend && source .venv/bin/activate
|
|
pytest # 40 tests
|
|
|
|
# Backend lint
|
|
ruff check .
|
|
|
|
# Frontend tests
|
|
cd frontend && npm test
|
|
|
|
# Frontend lint + typecheck
|
|
npm run lint && npm run typecheck
|
|
```
|