infra-dashboard/README.md

Infrastructure Dashboard

A lightweight, real-time infrastructure monitoring dashboard for Docker-based homelabs. Connects to hosts via SSH to collect container status and displays everything in a network topology diagram.

Features

• Network Diagram — SVG topology view of your Proxmox nodes, VMs, LXCs, and remote hosts
• Live Container Status — SSH-based polling shows container health across all hosts
• Host Cards — Grid view with per-host container breakdown
• Inventory Table — Flat table of all managed hosts
• Auto-refresh — Configurable background polling interval

Quick Start

1. Clone the repo

   git clone https://git.3ddbrewery.com/maddox/infra-dashboard.git
   cd infra-dashboard
   

2. Configure environment

   cp .env.example .env
   # Edit .env with your port, SSH key path, and timezone
   

3. Configure hosts

   cp hosts.json.example hosts.json
   # Edit hosts.json with your Proxmox nodes and Docker hosts
   

4. Configure diagram

   cp diagram.json.example diagram.json
   # Edit diagram.json with your network topology
   

5. Deploy

   docker compose up -d --build
   

6. Access at http://your-host:5050

Configuration Files

File	Purpose
.env	Runtime environment variables (port, intervals, SSH key path)
hosts.json	Docker hosts and Proxmox nodes inventory
diagram.json	Network topology layout for SVG diagram

hosts.json

Defines your infrastructure inventory:

{
  "proxmox_nodes": {
    "node-name": {"ip": "192.168.1.5", "hardware": "CPU • RAM", "role": "General"}
  },
  "docker_hosts": {
    "host-name": {"ip": "192.168.1.80", "user": "root", "type": "vm", "vmid": "100", "node": "node-name", "purpose": "Description"}
  }
}

• type: vm, lxc, or remote
• vmid: Proxmox VM/LXC ID (null for remote hosts)
• node: Which Proxmox node this guest runs on

diagram.json

Defines network topology and layout positions for the SVG diagram. Includes network infrastructure (router, switch, NAS), remote hosts, and Proxmox node children with their positions.

Children with "type": "static" are shown in the diagram but not polled for container data.

.env

Variable	Default	Description
DASHBOARD_PORT	5050	Host port for the web UI
REFRESH_INTERVAL	60	Seconds between background polls
SSH_TIMEOUT	10	SSH connection timeout in seconds
SSH_KEY_PATH	/root/.ssh/id_ed25519	Path to SSH private key on the host
TZ	America/New_York	Container timezone

API Endpoints

Endpoint	Method	Description
/	GET	Dashboard web UI
/api/data	GET	All host data and container status
/api/diagram	GET	Network topology JSON
/api/refresh	POST	Trigger immediate data refresh
/health	GET	Health check with last update timestamp

SSH Requirements

The dashboard connects to each host via SSH to run docker ps. Ensure:

• The SSH key specified in SSH_KEY_PATH exists on the Docker host
• The key is authorized on all target hosts
• Target hosts are reachable from the container's network

Architecture

• Flask web server with Gunicorn (2 workers, 4 threads)
• Paramiko for SSH connections
• Background thread polls all hosts on the configured interval
• Container runs as non-root dashboard user (entrypoint copies SSH key)
• Memory limited to 256MB, CPU limited to 0.5 cores