feat: Initial code

README.md

@@ -1,33 +1,141 @@
-# Python Flask Webserver Template
+# Home Lab Inventory
 
-Python3 website template including git actions
+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 project requirements
+1. Install dependencies
 ```bash
 uv sync
 ```
-2. Run the dev server
+2. Start app
 ```bash
 uv run python3 server.py
 ```
-3. Alternatively use the virtual environment
-```bash
-source .venv/bin/activate
-```
-You can exit the environment with `deactivate`
-
-For best development setup, you should install the git hook for pre-commit
+3. Optional pre-commit hooks
 ```bash
 uv run pre-commit install
 ```
 
-
 ## Production
-Run using the main.py file
 ```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.