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: documenting example.env and compose
karloks2005af041a04dd12
diff --git a/docker-compose-example.yml b/docker-compose-example.ymlnew file mode 100644index 0000000..930de47--- /dev/null+++ b/docker-compose-example.yml@@ -0,0 +1,138 @@+# 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:-}+ # 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:+ HOMELAB_API_URL: http://backend:8000+ # 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:-}+ HOMELAB_CHECK_INTERVAL_SECONDS: ${HOMELAB_CHECK_INTERVAL_SECONDS:-60}+ HOMELAB_MACHINE_ID: ${HOMELAB_MACHINE_ID:-}+ volumes:+ - /proc:/host/proc:ro+ - /:/hostfs:ro+ - /var/run/docker.sock:/var/run/docker.sock:ro+ - collector_state:/var/lib/homelab-collector+ depends_on:+ backend:+ condition: service_healthy++ 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"+ 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:diff --git a/docker-compose.server.yml b/docker-compose.server.ymlindex ce90419..c0daa73 100644--- a/docker-compose.server.yml+++ b/docker-compose.server.yml@@ -50,6 +50,13 @@ services:# 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}+ 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:-}# 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 ...@@ -78,6 +85,8 @@ services:# on the dashboard. An optional enrollment key skips that approval.HOMELAB_ENROLL_KEY: ${HOMELAB_ENROLL_KEY:-}HOMELAB_SERVER_NAME: ${HOMELAB_SERVER_NAME:-}+ HOMELAB_CHECK_INTERVAL_SECONDS: ${HOMELAB_CHECK_INTERVAL_SECONDS:-60}+ HOMELAB_MACHINE_ID: ${HOMELAB_MACHINE_ID:-}volumes:- /proc:/host/proc:ro- /:/hostfs:ro@@ -93,6 +102,7 @@ services:dockerfile: docker/frontend.Dockerfileargs:VITE_API_BASE_URL: /api+ VITE_LIVE_GRAPH_REFRESH_INTERVAL_SECONDS: ${LIVE_GRAPH_REFRESH_INTERVAL_SECONDS:-3}container_name: homelab-frontendrestart: unless-stopped# Serves the dashboard and proxies /api to the backend; Traefik publishes itdiff --git a/docker-compose.yml b/docker-compose.ymlindex 106fc3a..199a5e8 100644--- a/docker-compose.yml+++ b/docker-compose.yml@@ -95,7 +95,7 @@ services:# Serves the dashboard and proxies /api to the backend. Reach it directly over# LAN/VPN, or put the `https` profile's Caddy in front for a public domain.ports:- - "${FRONTEND_BIND:-0.0.0.0}:${FRONTEND_PORT:-5173}:80"+ - "${FRONTEND_BIND:-0.0.0.0}:${FRONTEND_PORT:-5173}:443"depends_on:backend:condition: service_healthydiff --git a/docker/frontend.Dockerfile b/docker/frontend.Dockerfileindex ab71124..e60e6e1 100644--- a/docker/frontend.Dockerfile+++ b/docker/frontend.Dockerfile@@ -8,6 +8,8 @@ RUN npm ciCOPY src/frontend/ ./ARG VITE_API_BASE_URL=/apiENV VITE_API_BASE_URL=$VITE_API_BASE_URL+ARG VITE_LIVE_GRAPH_REFRESH_INTERVAL_SECONDS=3+ENV VITE_LIVE_GRAPH_REFRESH_INTERVAL_SECONDS=$VITE_LIVE_GRAPH_REFRESH_INTERVAL_SECONDSRUN npm run buildFROM nginx:alpinediff --git a/example.env b/example.envnew file mode 100644index 0000000..99d030b--- /dev/null+++ b/example.env@@ -0,0 +1,119 @@+# Environment for docker-compose-example.yml (production / self-hosting).+# 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++# =============================================================================+# Required+# =============================================================================++# Password for the bundled Postgres database. The stack refuses to start+# without it. Use a long random string, e.g. the output of: openssl rand -hex 32+POSTGRES_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>++# =============================================================================+# AI chat (optional)+# =============================================================================++# Google Gemini API key for the chat assistant. Leave empty to disable chat;+# monitoring works without it. Get one at https://aistudio.google.com/apikey+GEMINI_API_KEY=<your-gemini-api-key>++# Gemini model used by the chat assistant.+AGENT_MODEL=models/gemini-3.5-flash++# =============================================================================+# Accounts and login sessions+# =============================================================================++# When false, only the first account can register; after that, sign-up is+# closed. Set to true to let anyone who can reach the site create an account.+# Only the exact value "true" enables it.+ALLOW_REGISTRATION=false++# Send the login cookie over HTTPS only. Keep true when served through Traefik+# over HTTPS; set to false only if you use the dashboard over plain HTTP,+# otherwise you won't be able to stay logged in.+SESSION_COOKIE_SECURE=true++# How long a login lasts, in seconds (86400 = 24 hours).+SESSION_TTL_SECONDS=86400++# Name of the login cookie. Change it only if it clashes with another app on+# the same domain.+SESSION_COOKIE_NAME=homie_session++# =============================================================================+# Rate limits (brute-force protection)+# =============================================================================++# Failed login attempts allowed per window, counted separately per IP address+# and per email. A successful login resets the count. Over the limit, logins+# get "429 Too many attempts" until the window ends.+LOGIN_RATE_LIMIT=5+LOGIN_RATE_WINDOW_SECONDS=60++# Registration attempts allowed per IP address per window (3600 = 1 hour).+REGISTER_RATE_LIMIT=3+REGISTER_RATE_WINDOW_SECONDS=3600++# =============================================================================+# Alerts (optional)+# =============================================================================++# URL that receives a JSON POST when a health check finds a critical problem.+# Leave empty to disable. Example: https://your-alert-endpoint.example/health+ADMIN_ALERT_WEBHOOK_URL=++# =============================================================================+# Local collector (monitors the machine running this stack)+# =============================================================================++# New machines appear under "New servers detected" on the dashboard and must+# be approved. Set an enrollment key (dashboard: Connect a server -> Advanced)+# to have this machine approved automatically. Leave empty to approve by hand.+HOMELAB_ENROLL_KEY=++# Name shown on the dashboard for this machine. Empty = use its hostname.+HOMELAB_SERVER_NAME=++# How often the collector sends metrics, in seconds. Minimum 15.+HOMELAB_CHECK_INTERVAL_SECONDS=60++# Unique ID of this machine. Empty = read /etc/machine-id from the host.+# Set it only if several machines share the same machine-id (e.g. cloned VMs)+# and would otherwise show up as one server.+HOMELAB_MACHINE_ID=++# =============================================================================+# Dashboard (frontend)+# =============================================================================++# Address and port where the dashboard is served over plain HTTP on the host.+# 127.0.0.1 keeps it reachable only from this machine (Traefik still reaches it+# over the Docker network). Use 0.0.0.0 for direct LAN/VPN access.+FRONTEND_BIND=127.0.0.1+FRONTEND_PORT=5173++# How often live graphs refresh, in seconds (minimum 1). This is baked in when+# the image is built, so rebuild after changing it:+# docker compose up -d --build frontend+LIVE_GRAPH_REFRESH_INTERVAL_SECONDS=3++# =============================================================================+# Not configurable here+# =============================================================================+# The code also reads DATABASE_URL, REDIS_URL, HOMELAB_API_URL, PROMPTS_DIR,+# DOCKER_SOCKET_PATH, HOST_PROC, HOST_ROOT, HOMELAB_STATE_DIR and+# VITE_API_BASE_URL. The compose file sets these to match its own containers,+# volumes and ports, so setting them in .env has no effect.