Home Lab Inventory

Flask inventory system for homelab environments with automatic data collection and a dashboard UI.

Features

• SQLite persistence for inventory, source health, and collection history
• Automatic scheduled polling with manual trigger API
• Connectors for:
  • Proxmox (VM and LXC)
  • Docker hosts
  • Coolify instances
  • Nginx config ingestion from Docker agents
• Dashboard with topology cards and filterable inventory table

Requirements

• Python 3.13+
• UV

Development

1. Install dependencies

uv sync

2. Start app

uv run python3 server.py

3. Optional pre-commit hooks

uv run pre-commit install

Production

python3 main.py

Environment Variables

Core

• APP_NAME default: Home Lab Inventory
• BASE_DIR default: current directory
• DATABASE_PATH default: ${BASE_DIR}/inventory.db
• SCHEDULER_ENABLED default: true
• POLL_INTERVAL_SECONDS default: 300
• INITIAL_COLLECT_ON_STARTUP default: true
• REQUEST_TIMEOUT_SECONDS default: 10
• ADMIN_TOKEN optional, required in X-Admin-Token for manual trigger when set

Proxmox

• PROXMOX_ENABLED default: true
• PROXMOX_ENDPOINTS comma-separated URLs
• Token auth:
  • PROXMOX_TOKEN_ID
  • PROXMOX_TOKEN_SECRET
• Or username/password auth:
  • PROXMOX_USER
  • PROXMOX_PASSWORD
• PROXMOX_VERIFY_TLS default: false

Docker

• DOCKER_ENABLED default: true
• DOCKER_HOSTS comma-separated Docker API endpoints
• DOCKER_HOST single Docker endpoint (used if DOCKER_HOSTS is empty)
• DOCKER_BEARER_TOKEN optional
• DOCKER_AGENT_ENDPOINTS comma-separated inventory agent URLs
• DOCKER_AGENT_TOKEN bearer token used by inventory agents

Docker endpoint examples:

DOCKER_HOST=unix:///var/run/docker.sock
DOCKER_HOSTS=tcp://docker-1:2376,tcp://docker-2:2376,https://docker-3.example/api
DOCKER_AGENT_ENDPOINTS=https://docker-a-agent:9090,https://docker-b-agent:9090,https://docker-c-agent:9090
DOCKER_AGENT_TOKEN=change-me

Coolify

• COOLIFY_ENABLED default: true
• COOLIFY_ENDPOINTS comma-separated URLs
• COOLIFY_API_TOKEN

Nginx (via Docker Agent)

• Nginx config data is collected from each Docker agent endpoint (/api/v1/nginx-configs).
• No separate NPM API credentials are required in the inventory app.

API Endpoints

• GET /api/v1/summary
• GET /api/v1/topology
• GET /api/v1/assets
• GET /api/v1/sources
• GET /api/v1/health
• POST /api/v1/collect/trigger

Docker Notes

• Persist DB with a volume mounted into BASE_DIR or set DATABASE_PATH
• If you need local Docker socket collection, expose Docker API via a secure endpoint or add your preferred socket proxy

Multi-Server Docker Agent Pattern

• For one local Docker host, use DOCKER_HOST=unix:///var/run/docker.sock.
• For multiple Docker servers, run a small inventory agent on each Docker server and poll those agent endpoints from this app.
• Agent responsibilities:
  • Read local Docker socket (/var/run/docker.sock) on that host.
  • Optionally read mounted Nginx configuration files.
  • Expose read-only inventory JSON over HTTPS.
  • Authenticate requests with a bearer token.
  • Return container name, image, state, ports, and networks.
• This avoids exposing Docker daemon APIs directly across your network.

Docker Agent Quick Start

Use the docker_agent/ folder to run one agent per Docker server.

1. On each Docker server, copy the folder and start it:

cd docker_agent
docker compose up -d --build

2. Set an agent token on each server (AGENT_TOKEN) and expose port 9090 only to your inventory app network.

Nginx config support in docker agent:

• Mount your Nginx config directory into the agent container.
• Set NGINX_CONFIG_DIR to the mounted path.
• Query GET /api/v1/nginx-configs on the agent.

Example compose mount in docker_agent/docker-compose.yml:

volumes:
	- /var/run/docker.sock:/var/run/docker.sock:ro
	- /etc/nginx:/mnt/nginx:ro
environment:
	NGINX_CONFIG_DIR: /mnt/nginx

3. In the inventory app .env, set:

DOCKER_ENABLED=true
DOCKER_AGENT_ENDPOINTS=http://docker1.local:9090,http://docker2.local:9090,http://docker3.local:9090
DOCKER_AGENT_TOKEN=change-me

4. Trigger a collection in the UI and confirm docker source reports ok in the Sources panel.