Skip to content

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.

chore: documenting example.env and compose

karloks2005af041a04dd12
diff --git a/docker-compose-example.yml b/docker-compose-example.yml
new file mode 100644
index 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.yml
index 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.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
diff --git a/docker-compose.yml b/docker-compose.yml
index 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_healthy
diff --git a/docker/frontend.Dockerfile b/docker/frontend.Dockerfile
index ab71124..e60e6e1 100644
--- a/docker/frontend.Dockerfile
+++ b/docker/frontend.Dockerfile
@@ -8,6 +8,8 @@ RUN npm ci
COPY src/frontend/ ./
ARG VITE_API_BASE_URL=/api
ENV 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_SECONDS
RUN npm run build
FROM nginx:alpine
diff --git a/example.env b/example.env
new file mode 100644
index 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.