# 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
```bash
uv sync
```
2. Start app
```bash
uv run python3 server.py
```
3. Optional pre-commit hooks
```bash
uv run pre-commit install
```

## Production
```bash
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:
```text
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:
```bash
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`:
```yaml
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:
```text
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.