Self-hosted monitoring for homelabs: host and container metrics and uptime checks from all your machines in one dashboard, with an optional AI agent that diagnoses incidents and suggests fixes.
Python ai-agentsaiopsdashboarddockerfastapihomelabincident-managementllmmonitoringopenaireactroot-cause-analysisself-hosteduptime-monitoring
chore(deploy): configure the server stack from .env, drop the duplicate example
karloks20056e3c13fa6527
diff --git a/README.md b/README.mdindex 8d34606..9925787 100644--- a/README.md+++ b/README.md@@ -142,41 +142,42 @@ There are two Compose files:| `compose.yml` | Laptop / development (the default when you run `docker compose` without `-f`) | Dashboard on port 5173 on all interfaces; plain HTTP; optional Caddy (`--profile https`). || `docker-compose.server.yml` | Server behind an existing Traefik | Traefik labels and network; HTTPS-only session cookie; only the first account can register; port 5173 bound to `127.0.0.1`; no Caddy; **collector endpoints removed from the public side** and served by a separate collector gate on your VPN address. |-### 1. Fill in the placeholders+### 1. Create `.env` on the server-In `docker-compose.server.yml`, replace every value marked `# CHANGE ME`:+Nothing in `docker-compose.server.yml` needs editing: everything specific to you comes from+`.env`, so `git pull` can always update the file. Start from the production template:-| Setting | Placeholder | Replace with |+```bash+cp example.env .env+```++Then set at least these:++| Setting | Default | Meaning ||---|---|---|-| `traefik.http.routers.homelab.rule` | ``Host(`dashboard.example.com`)`` | Your domain |-| `traefik.http.routers.homelab.entrypoints` | `websecure` | Your Traefik HTTPS entrypoint name |-| `traefik.http.routers.homelab.tls.certresolver` | `letsencrypt` | Your Traefik certificate resolver name |-| `traefik.docker.network` **and** `networks.traefik.name` | `traefik_default` | The Docker network Traefik is attached to (both must match) |+| `POSTGRES_PASSWORD` | *(required)* | A long random password for the bundled database. |+| `DASHBOARD_DOMAIN` | *(required)* | Your domain, without `https://`. Used for the Traefik router. |+| `TRAEFIK_ENTRYPOINT` | `websecure` | Your Traefik HTTPS entrypoint name. |+| `TRAEFIK_CERT_RESOLVER` | `letsencrypt` | Your Traefik certificate resolver name. |+| `TRAEFIK_NETWORK` | `traefik_default` | The Docker network Traefik is attached to. |+| `TRAEFIK_ROUTER` | `homelab` | Name of this dashboard's Traefik router and service; change it only if it clashes with another one. |+| `COMPOSE_FILE` | `docker-compose.server.yml` | Makes plain `docker compose ...` commands use the server file (see below). |Find the network with `docker network ls` or`docker inspect <traefik-container> --format '{{json .NetworkSettings.Networks}}'`.The entrypoint and resolver names are in Traefik's static configuration(`entryPoints:` / `certificatesResolvers:`).-### 2. Create `.env` on the server--```bash-cp .env.example .env-```--Set at least `POSTGRES_PASSWORD`, and add--```bash-COMPOSE_FILE=docker-compose.server.yml-```+### 2. Use the right Compose file-so plain `docker compose ...` commands use the server file. Without it, Compose-picks `compose.yml` (the development stack), and an `up` would replace the-server containers with ones that have no Traefik labels and open registration.+`COMPOSE_FILE=docker-compose.server.yml` in `.env` matters. Without it, Compose picks+`compose.yml` (the development stack), and an `up` would replace the server containers+with ones that have no Traefik labels and open registration.-Don't rename or delete the Compose files in the checkout. `git pull` then can't-update them (or refuses to run), and if both `compose.yml` and-`docker-compose.yml` exist in the folder, Compose silently uses `compose.yml`.+**Don't copy the server file under another name** (for example `docker-compose.yml`). If+both `compose.yml` and `docker-compose.yml` exist, Compose silently uses `compose.yml`, and+a copy won't receive updates. If you made a copy of an older version, move your values+into `.env`, delete the copy, and continue with `docker-compose.server.yml`.### 3. Start it@@ -559,7 +560,9 @@ standard-library Python.| `ADMIN_BOOTSTRAP_TOKEN` | generated at start | Setup token for the first account. Leave empty to have one generated and printed in the backend log until the first account exists. || `FRONTEND_BIND` | `0.0.0.0` (dev), `127.0.0.1` (server file) | Interface for the dashboard's plain-HTTP port. || `FRONTEND_PORT` | `5173` | Dashboard port on the host. |-| `CORS_ORIGINS` | `http://localhost:5173` | Comma-separated origins. Also the allow-list for the cross-site request check: a state-changing request from any other origin is refused unless its `Origin` matches the `Host` the dashboard was reached on. Add your dashboard URL if something in front rewrites `Host`. |+| `DASHBOARD_DOMAIN` | *(required on a server)* | Domain of the dashboard, without `https://` (server file). |+| `TRAEFIK_ENTRYPOINT` / `TRAEFIK_CERT_RESOLVER` / `TRAEFIK_NETWORK` / `TRAEFIK_ROUTER` | `websecure` / `letsencrypt` / `traefik_default` / `homelab` | Your Traefik names (server file). |+| `CORS_ORIGINS` | `http://localhost:5173` (dev), `https://<DASHBOARD_DOMAIN>` (server file) | Comma-separated origins. Also the allow-list for the cross-site request check: a state-changing request from any other origin is refused unless its `Origin` matches the `Host` the dashboard was reached on. Add your dashboard URL if something in front rewrites `Host`. || `LOGIN_RATE_LIMIT` / `LOGIN_RATE_WINDOW_SECONDS` | `5` / `60` | Login attempts per IP and per email. || `REGISTER_RATE_LIMIT` / `REGISTER_RATE_WINDOW_SECONDS` | `3` / `3600` | Registrations per IP. || `COLLECTOR_BIND` / `COLLECTOR_PORT` | `127.0.0.1` / `8081` | Server file: address and port where the collector gate is published. Set the address to your VPN's. |@@ -730,7 +733,6 @@ the `users` table on a fresh volume.```textcompose.yml development stack (default for `docker compose`)docker-compose.server.yml server stack behind Traefik-docker-compose-example.yml template for the server stackcollector-compose.yml collector-only stack for monitored machinesSECURITY.md what each component can touch, and its limitsTESTS.md how to run the tests and what each one checks@@ -801,7 +803,7 @@ same address as everything else.|---|---|| A new machine never shows up under **New servers detected** | `docker logs homelab-collector` on that machine. "Could not reach …" means the address in the command isn't reachable from it (firewall, `localhost`, wrong IP/domain). || Collector log says "Backend no longer accepts server …" | The server was deleted on the dashboard; it is asking to join again, so click **Add** or **Dismiss**. |-| `network traefik_default declared as external, but could not be found` | You're using `docker-compose.server.yml` on a machine without that Traefik network. Use `compose.yml` for development, or fix the network name. |+| `network traefik_default declared as external, but could not be found` | You're using `docker-compose.server.yml` on a machine without that Traefik network. Use `compose.yml` for development, or set `TRAEFIK_NETWORK` in `.env` to the network Traefik is really on. || Dashboard shows old behaviour after a code change or `git pull` | Rebuild **all** services with `docker compose up -d --build` (with `-f docker-compose.server.yml` on a server unless `COMPOSE_FILE` is set) and hard-refresh the browser (Ctrl+Shift+R). || "The machine running the dashboard isn't reporting yet" at the top | The stack's own collector hasn't checked in: add it under **New servers detected**, then wait one check interval. If it is reporting, its image is outdated: `docker exec homelab-collector grep -c dashboard_host /app/collector.py` prints `0`. Rebuild it (`docker compose build --no-cache collector && docker compose up -d collector`). || A server shows only `/` and no **Storage** bars for other disks | Its collector predates per-mount reporting. Install a newer collector image (run a freshly generated command, or `docker compose -f collector-compose.yml up -d --build`). A disk mounted after the collector started appears after a collector restart. |diff --git a/docker-compose-example.yml b/docker-compose-example.ymldeleted file mode 100644index 34c4453..0000000--- a/docker-compose-example.yml+++ /dev/null@@ -1,232 +0,0 @@-# Example production stack for self-hosting, published over HTTPS by an existing Traefik.-# 1. Copy this file: cp docker-compose-example.yml docker-compose.server.yml-# 2. Copy the env file: cp example.env .env (then fill in its values)-# 3. Replace every "CHANGE ME" / <placeholder> value below with your own.-# 4. Start it: docker compose -f docker-compose.server.yml up -d --build-# Tip: put COMPOSE_FILE=docker-compose.server.yml in this server's .env so a plain-# `docker compose ...` uses this file.-services:- postgres:- image: postgres:16-alpine- container_name: homelab-postgres- restart: unless-stopped- environment:- POSTGRES_DB: homelab- POSTGRES_USER: homelab- POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in .env}- volumes:- - postgres_data:/var/lib/postgresql/data- - ./docker/postgres/init:/docker-entrypoint-initdb.d- healthcheck:- test: ["CMD-SHELL", "pg_isready -U homelab -d homelab"]- interval: 10s- timeout: 5s- retries: 5-- redis:- image: redis:7-alpine- container_name: homelab-redis- restart: unless-stopped- command: ["redis-server", "--appendonly", "yes"]- volumes:- - redis_data:/data- healthcheck:- test: ["CMD", "redis-cli", "ping"]- interval: 10s- timeout: 5s- retries: 5-- backend:- build:- context: .- dockerfile: docker/backend.Dockerfile- container_name: homelab-backend- image: homelab-backend:latest- restart: unless-stopped- environment:- DATABASE_URL: postgresql+psycopg://homelab:${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in .env}@postgres:5432/homelab- REDIS_URL: redis://redis:6379/0- GEMINI_API_KEY: ${GEMINI_API_KEY:-}- AGENT_MODEL: ${AGENT_MODEL:-models/gemini-3.5-flash}- # Served over HTTPS via Traefik, so the login cookie is HTTPS-only.- SESSION_COOKIE_SECURE: ${SESSION_COOKIE_SECURE:-true}- # Only the first account can register; set to true to let others sign up.- ALLOW_REGISTRATION: ${ALLOW_REGISTRATION:-false}- CORS_ORIGINS: ${CORS_ORIGINS:-https://<your-domain>} # CHANGE ME: your dashboard URL- SESSION_TTL_SECONDS: ${SESSION_TTL_SECONDS:-86400}- SESSION_COOKIE_NAME: ${SESSION_COOKIE_NAME:-homie_session}- LOGIN_RATE_LIMIT: ${LOGIN_RATE_LIMIT:-5}- LOGIN_RATE_WINDOW_SECONDS: ${LOGIN_RATE_WINDOW_SECONDS:-60}- REGISTER_RATE_LIMIT: ${REGISTER_RATE_LIMIT:-3}- REGISTER_RATE_WINDOW_SECONDS: ${REGISTER_RATE_WINDOW_SECONDS:-3600}- ADMIN_ALERT_WEBHOOK_URL: ${ADMIN_ALERT_WEBHOOK_URL:-}- # Collector endpoints answer only through the collector-gate container (VPN or internal).- COLLECTOR_ACCESS: strict- # Shown in the Connect a server panel: your VPN address for the gate, and pinned images.- COLLECTOR_PUBLIC_URL: ${COLLECTOR_PUBLIC_URL:-}- COLLECTOR_IMAGE: ${COLLECTOR_IMAGE:-}- DOCKER_PROXY_IMAGE: ${DOCKER_PROXY_IMAGE:-}- # No host port: nginx (frontend) reaches the backend over the Compose network,- # and browsers/collectors use https://<domain>/api. Avoids clashing with other- # services on the server. Debug with: docker compose exec backend ...- depends_on:- postgres:- condition: service_healthy- redis:- condition: service_healthy- healthcheck:- test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"]- interval: 10s- timeout: 5s- retries: 5-- # Monitors the machine running this stack. Other servers use collector-compose.yml.- collector:- build:- context: .- dockerfile: docker/collector.Dockerfile- image: homelab-collector:latest- container_name: homelab-collector- restart: unless-stopped- environment:- # Through the gate's internal listener (not published); the public listener refuses collectors.- HOMELAB_API_URL: http://collector-gate:8080/api- # Marks this collector as the machine running the dashboard (the charts at the top).- HOMELAB_DASHBOARD_HOST: "true"- # Nothing to configure: this machine shows up under "New servers detected"- # on the dashboard. An optional enrollment key skips that approval.- HOMELAB_ENROLL_KEY: ${HOMELAB_ENROLL_KEY:-}- HOMELAB_SERVER_NAME: ${HOMELAB_SERVER_NAME:-}- # Optional internet check, off when empty: comma-separated host:port targets this collector tries to reach.- HOMELAB_CONNECTIVITY_TARGETS: ${HOMELAB_CONNECTIVITY_TARGETS:-}- # Docker data comes through the read-only proxy; the collector has no Docker socket.- HOMELAB_DOCKER_HOST: /run/docker-proxy/docker.sock- HOMELAB_CHECK_INTERVAL_SECONDS: ${HOMELAB_CHECK_INTERVAL_SECONDS:-60}- HOMELAB_MACHINE_ID: ${HOMELAB_MACHINE_ID:-}- volumes:- - /proc:/host/proc:ro- - /:/hostfs:ro- - collector_state:/var/lib/homelab-collector- # Summary from the optional system helper (read-only; empty unless that profile runs).- - system_events:/helper:ro- - docker_proxy_socket:/run/docker-proxy:ro- # Read-only host view, no capabilities: as root it then can't read other users' private- # files (SSH keys, .env) even though / is mounted.- cap_drop: [ALL]- read_only: true- security_opt:- - no-new-privileges:true- depends_on:- backend:- condition: service_healthy- collector-gate:- condition: service_started-- # The only way to reach the collector endpoints. Not on the reverse proxy's network, so other- # apps can't register collectors. Publish its VPN listener on your VPN address only: Docker's- # published ports bypass ufw and similar firewalls, so never bind it to 0.0.0.0 and rely on those.- collector-gate:- image: nginx:alpine- container_name: homelab-collector-gate- restart: unless-stopped- ports:- - "${COLLECTOR_BIND:-127.0.0.1}:${COLLECTOR_PORT:-8081}:8081"- volumes:- - ./docker/nginx.collector.conf:/etc/nginx/conf.d/default.conf:ro- read_only: true- tmpfs:- - /var/cache/nginx- - /var/run- cap_drop: [ALL]- cap_add: [CHOWN, SETGID, SETUID]- security_opt:- - no-new-privileges:true- depends_on:- backend:- condition: service_healthy-- # The only container that mounts the Docker socket (a mount flag can't make it read-only).- # It answers three read requests and nothing else. It has no network at all: the collector- # reaches it through a Unix socket in a volume only the two of them share. See SECURITY.md.- docker-proxy:- build:- context: .- dockerfile: docker/docker-proxy.Dockerfile- image: homelab-docker-proxy:latest- container_name: homelab-docker-proxy- restart: unless-stopped- user: "0:0"- cap_drop: [ALL]- read_only: true- security_opt:- - no-new-privileges:true- network_mode: none- volumes:- - /var/run/docker.sock:/var/run/docker.sock- - docker_proxy_socket:/run/docker-proxy-- # Optional: adds OOM-killer process names, kernel errors and crash-vs-clean-shutdown detection.- # Enable with: docker compose --profile system-events up -d- # Its only privilege is CAP_SYSLOG (to read the kernel log); it has no network, a read-only- # filesystem, and sees the host only through the read-only wtmp file. See SECURITY.md.- system-helper:- profiles: ["system-events"]- build:- context: .- dockerfile: docker/system-helper.Dockerfile- image: homelab-system-helper:latest- container_name: homelab-system-helper- restart: unless-stopped- user: "0:0"- cap_drop: [ALL]- cap_add: [SYSLOG]- network_mode: none- read_only: true- security_opt:- - no-new-privileges:true- volumes:- - /var/log/wtmp:/host/wtmp:ro- - system_events:/out-- frontend:- build:- context: .- dockerfile: docker/frontend.Dockerfile- args:- VITE_API_BASE_URL: /api- VITE_LIVE_GRAPH_REFRESH_INTERVAL_SECONDS: ${LIVE_GRAPH_REFRESH_INTERVAL_SECONDS:-3}- container_name: homelab-frontend- restart: unless-stopped- # Serves the dashboard and proxies /api to the backend; Traefik publishes it- # over HTTPS on your domain. The plain-HTTP port is bound to localhost only- # (set FRONTEND_BIND=0.0.0.0 to also allow direct LAN/VPN access).- ports:- - "${FRONTEND_BIND:-127.0.0.1}:${FRONTEND_PORT:-5173}:80"- volumes:- # Public listener only: collector endpoints are refused here (see the collector-gate service).- - ./docker/nginx.strict.conf:/etc/nginx/conf.d/default.conf:ro- networks:- - default- - traefik- labels:- - traefik.enable=true- - traefik.docker.network=<traefik-network> # CHANGE ME: Traefik's Docker network- - traefik.http.routers.<subdomain>.rule=Host(`<your-domain>`) # CHANGE ME: your domain- - traefik.http.routers.<subdomain>.entrypoints=<https-entrypoint> # CHANGE ME: Traefik HTTPS entrypoint- - traefik.http.routers.<subdomain>.tls.certresolver=<cert-resolver> # CHANGE ME: Traefik certificate resolver- - traefik.http.services.<subdomain>.loadbalancer.server.port=80- depends_on:- backend:- condition: service_healthy--networks:- traefik:- external: true- name: <traefik-network> # CHANGE ME: Traefik's Docker network (same as traefik.docker.network above)--volumes:- postgres_data:- redis_data:- collector_state:- system_events:- docker_proxy_socket:diff --git a/docker-compose.server.yml b/docker-compose.server.ymlindex 6d69129..464cbb2 100644--- a/docker-compose.server.yml+++ b/docker-compose.server.yml@@ -1,7 +1,9 @@# Server stack, published over HTTPS by an existing Traefik.# docker compose -f docker-compose.server.yml up -d --build-# Tip: put COMPOSE_FILE=docker-compose.server.yml in this server's .env so a plain-# `docker compose ...` uses this file. Replace every "CHANGE ME" value below.+# Nothing here needs editing: your domain and Traefik names come from .env (see example.env),+# so `git pull` can always update this file. Don't copy it under another name: Compose+# prefers compose.yml (the development stack) when two default-named files exist.+# Tip: put COMPOSE_FILE=docker-compose.server.yml in .env so a plain `docker compose ...` uses it.services:postgres:image: postgres:16-alpine@@ -49,7 +51,7 @@ services:SESSION_COOKIE_SECURE: ${SESSION_COOKIE_SECURE:-true}# Only the first account can register; set to true to let others sign up.ALLOW_REGISTRATION: ${ALLOW_REGISTRATION:-false}- CORS_ORIGINS: ${CORS_ORIGINS:-http://localhost:5173}+ CORS_ORIGINS: ${CORS_ORIGINS:-https://${DASHBOARD_DOMAIN:?Set DASHBOARD_DOMAIN in .env}}SESSION_TTL_SECONDS: ${SESSION_TTL_SECONDS:-86400}SESSION_COOKIE_NAME: ${SESSION_COOKIE_NAME:-homie_session}LOGIN_RATE_LIMIT: ${LOGIN_RATE_LIMIT:-5}@@ -207,11 +209,13 @@ services:- traefiklabels:- traefik.enable=true- - traefik.docker.network=traefik_default # CHANGE ME: Traefik's Docker network- - traefik.http.routers.homelab.rule=Host(`dashboard.karloks.com`) # CHANGE ME: your domain- - traefik.http.routers.homelab.entrypoints=websecure # CHANGE ME: Traefik HTTPS entrypoint- - traefik.http.routers.homelab.tls.certresolver=letsencrypt # CHANGE ME: Traefik certificate resolver- - traefik.http.services.homelab.loadbalancer.server.port=80+ # All values come from .env: DASHBOARD_DOMAIN (required), TRAEFIK_ROUTER, TRAEFIK_ENTRYPOINT,+ # TRAEFIK_CERT_RESOLVER and TRAEFIK_NETWORK (defaults shown).+ - traefik.docker.network=${TRAEFIK_NETWORK:-traefik_default}+ - traefik.http.routers.${TRAEFIK_ROUTER:-homelab}.rule=Host(`${DASHBOARD_DOMAIN:?Set DASHBOARD_DOMAIN in .env}`)+ - traefik.http.routers.${TRAEFIK_ROUTER:-homelab}.entrypoints=${TRAEFIK_ENTRYPOINT:-websecure}+ - traefik.http.routers.${TRAEFIK_ROUTER:-homelab}.tls.certresolver=${TRAEFIK_CERT_RESOLVER:-letsencrypt}+ - traefik.http.services.${TRAEFIK_ROUTER:-homelab}.loadbalancer.server.port=80depends_on:backend:condition: service_healthy@@ -219,7 +223,7 @@ services:networks:traefik:external: true- name: traefik_default # CHANGE ME: Traefik's Docker network (same as traefik.docker.network above)+ name: ${TRAEFIK_NETWORK:-traefik_default} # Traefik's Docker network; same value as the label abovevolumes:postgres_data:diff --git a/example.env b/example.envindex c7327a3..2f8440c 100644--- a/example.env+++ b/example.env@@ -1,12 +1,13 @@-# Environment for docker-compose-example.yml (production / self-hosting).+# Environment for docker-compose.server.yml (production / self-hosting behind Traefik).# Copy to .env next to the compose file and fill in the values:# cp example.env .env# Every variable the compose file reads is listed here. Values shown for# optional settings are the defaults; you can delete any line you don't change.-# Optional: lets a plain `docker compose ...` use the production compose file-# instead of passing -f every time.-# COMPOSE_FILE=docker-compose.server.yml+# Strongly recommended: makes a plain `docker compose ...` use the production compose file.+# Without it Compose picks compose.yml (the development stack) and would replace your server+# containers with ones that have no Traefik labels and open registration.+COMPOSE_FILE=docker-compose.server.yml# =============================================================================# Required@@ -16,10 +17,23 @@# without it. Use a long random string, e.g. the output of: openssl rand -hex 32POSTGRES_PASSWORD=<long-random-password>-# URL(s) the dashboard is opened from, comma-separated. The backend rejects-# browser requests from any other origin. Must match your domain exactly,-# including https:// and without a trailing slash.-CORS_ORIGINS=https://<your-domain>+# The domain the dashboard is served on (no https://, no slash). Used for the Traefik router+# and as the default for CORS_ORIGINS below.+DASHBOARD_DOMAIN=<your-domain>++# Your Traefik setup. Defaults shown; set them to match your Traefik's static configuration+# (entryPoints / certificatesResolvers) and the Docker network it is attached to+# (docker network ls, or: docker inspect <traefik-container> --format '{{json .NetworkSettings.Networks}}').+TRAEFIK_ENTRYPOINT=websecure+TRAEFIK_CERT_RESOLVER=letsencrypt+TRAEFIK_NETWORK=traefik_default+# Name of this dashboard's Traefik router and service; only change it if it clashes with another one.+TRAEFIK_ROUTER=homelab++# URL(s) the dashboard is opened from, comma-separated, if it differs from https://<DASHBOARD_DOMAIN>+# (for example a second address). Browser requests from other origins are rejected. Include+# https:// and no trailing slash. Leave commented to use the default.+# CORS_ORIGINS=https://<your-domain># =============================================================================# AI chat (optional)