generated from nathanwoodburn/python-webserver-template
142 lines
4.2 KiB
Markdown
142 lines
4.2 KiB
Markdown
# 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.
|