homelab-dashboard/README.md

Homelab Dashboard

A modern, responsive dashboard for monitoring your homelab infrastructure.

Features

• Service Monitoring: Track health and response times for all your services
• Proxmox Integration: View cluster status, nodes, VMs, and containers
• PBS Integration: Monitor Proxmox Backup Server status
• Camera Viewer: WebRTC-based live camera feeds (via go2rtc)
• Docker Monitoring: Track containers across multiple Docker hosts
• Uptime Kuma Integration: Display uptime stats from your monitoring
• Mobile-Friendly: Responsive design works on all devices

Quick Start

1. Clone and Setup

# Copy the dashboard to your server
scp -r dashboard/ root@your-server:/opt/

# Install dependencies
apt install python3-venv python3-yaml
cd /opt/dashboard
python3 -m venv venv
source venv/bin/activate
pip install fastapi uvicorn httpx jinja2

2. Configure

# Copy the example configs
cp config.yaml.example config.yaml
cp secrets.yaml.example secrets.yaml

# Edit config.yaml with your services
nano config.yaml

# Add your API credentials to secrets.yaml
nano secrets.yaml

# Protect secrets file
chmod 600 secrets.yaml

3. Run

# Test manually
source venv/bin/activate
uvicorn app.main:app --host 0.0.0.0 --port 8000

# Or create a systemd service (see below)

Configuration

config.yaml

The main configuration file defines:

• dashboard: Title, theme, refresh interval
• proxmox: Cluster nodes to monitor
• pbs: Proxmox Backup Server connection
• cameras: go2rtc camera streams
• docker: Docker hosts to monitor
• uptime_kuma: Uptime monitoring integration
• categories: Service category colors and icons
• services: All services to display and monitor
• service_groups: Logical groupings for services

See config.yaml.example for full documentation.

secrets.yaml

Store sensitive credentials separately:

• Proxmox API tokens
• PBS API tokens
• OPNsense API keys
• Service-specific API keys

Important: Never commit secrets.yaml to version control!

Service Configuration

Each service can have:

- name: MyService
  url: https://myservice.example.com    # URL to open on click
  ip: 192.168.1.100                     # IP for health checks
  port: 8080                            # Port for health checks
  category: Apps                        # Category grouping
  icon: server                          # Icon name
  favorite: true                        # Show in favorites
  critical: true                        # Mark as critical
  group: "My Group"                     # Service group
  health_check:                         # Optional custom health check
    url: https://custom-check-url/
    timeout: 10

Available Icons

server, shield, globe, archive, lock, film, star, video, tv, music, search, download, cog, chart, heartbeat, key, git, workflow, book, image, brain, home, camera, message, database

Systemd Service

Create /etc/systemd/system/dashboard.service:

[Unit]
Description=Homelab Dashboard
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/dashboard
ExecStart=/opt/dashboard/venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8000
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Then enable and start:

systemctl daemon-reload
systemctl enable dashboard
systemctl start dashboard

Reverse Proxy (Nginx/NPM)

Example Nginx Proxy Manager configuration:

• Domain: dashboard.yourdomain.com
• Forward Host: 192.168.1.x (dashboard IP)
• Forward Port: 8000
• WebSocket Support: Enable (for live updates)

Requirements

• Python 3.10+
• FastAPI
• Uvicorn
• HTTPX
• Jinja2
• PyYAML

License

MIT License - Feel free to use and modify for your homelab!