Pouzor
452f3b0860
curl -fsSL https://raw.githubusercontent.com/Pouzor/homelable/main/install.sh | bash Handles fresh install and updates. Pulls prebuilt images, creates .env from .env.example on first run. Update README Quick Start accordingly.
153 lines
4.3 KiB
Markdown
153 lines
4.3 KiB
Markdown
# Homelable
|
|
|
|
Homelable is a self-hosted infrastructure visualization solution. It provides a network scanning feature to accelerate the identification of machines and services deployed on your local infrastructure.
|
|
|
|
Homelable also offers a healthcheck system (WIP) through multiple methods (ping/TCP, /health API, etc.) to get a global overview of online/offline services.
|
|
|
|
|
|
---
|
|
|
|
## Quick Start — Docker
|
|
|
|
```bash
|
|
curl -fsSL https://raw.githubusercontent.com/Pouzor/homelable/main/install.sh | bash
|
|
cd homelable && docker compose up -d
|
|
```
|
|
|
|
Open **http://localhost:3000** — login with `admin` / `admin`.
|
|
|
|
> Change the password before exposing to a network: edit `.env` and update `AUTH_USERNAME` / `AUTH_PASSWORD_HASH`.
|
|
>
|
|
> Generate a new hash: `docker compose exec backend python -c "from passlib.context import CryptContext; print(CryptContext(schemes=['bcrypt']).hash('yourpassword'))"`
|
|
>
|
|
> ⚠️ Keep the single quotes around the hash value in `.env` — bcrypt hashes contain `$` characters that Docker Compose would otherwise misinterpret.
|
|
|
|
### Update
|
|
|
|
Re-run the install script — it detects an existing install and only updates `docker-compose.yml`:
|
|
|
|
```bash
|
|
curl -fsSL https://raw.githubusercontent.com/Pouzor/homelable/main/install.sh | bash
|
|
cd homelable && docker compose pull && docker compose up -d
|
|
```
|
|
|
|
### Build from source
|
|
|
|
```bash
|
|
git clone https://github.com/Pouzor/homelable.git
|
|
cd homelable
|
|
cp .env.example .env
|
|
docker compose up -d
|
|
```
|
|
|
|
---
|
|
|
|
## Proxmox LXC Install
|
|
|
|
Run inside a Debian/Ubuntu LXC container:
|
|
|
|
```bash
|
|
bash <(curl -fsSL https://raw.githubusercontent.com/Pouzor/homelable/main/scripts/lxc-install.sh)
|
|
```
|
|
|
|
This installs the backend as a systemd service and serves the frontend via nginx.
|
|
|
|
---
|
|
|
|
## Configuration
|
|
|
|
All configuration is done via `.env` (copied from `.env.example`):
|
|
|
|
```env
|
|
SECRET_KEY=change_me_in_production
|
|
|
|
# Auth — default: admin / admin
|
|
AUTH_USERNAME=admin
|
|
AUTH_PASSWORD_HASH='$2b$12$...' # bcrypt hash — keep single quotes
|
|
|
|
# CIDR ranges to scan
|
|
SCANNER_RANGES=["192.168.1.0/24"]
|
|
|
|
# How often to check node status (seconds)
|
|
STATUS_CHECKER_INTERVAL=60
|
|
```
|
|
|
|
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` |
|
|
|
|
---
|
|
|
|
## Development Mode
|
|
|
|
**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 and review defaults
|
|
uvicorn app.main:app --reload --port 8000
|
|
```
|
|
|
|
**Frontend:**
|
|
```bash
|
|
cd frontend
|
|
npm install
|
|
npm run dev # http://localhost:5173
|
|
```
|
|
|
|
|
|
---
|