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
# Server stack, published over HTTPS by the reverse proxy you already run (Traefik, Caddy, nginx, ...).
# Your proxy reaches the dashboard on 127.0.0.1:5173. A proxy in Docker can reach frontend:8080 instead, with the
# frontend attached to the proxy's network (as deploy/traefik.yml does); never attach the proxy to this stack's
# `front` network, where the backend and the collector gate trust whatever reaches them.
# Set COMPOSE_FILE in .env, adding the ready-made file for your proxy from deploy/ if there is one
# (see docs/deployment.md), then run a plain `docker compose pull && docker compose up -d`:
# COMPOSE_FILE=docker-compose.server.yml:deploy/traefik.yml (Traefik)
# COMPOSE_FILE=docker-compose.server.yml (any other reverse proxy)
# The Infradeck images are the published, signed ones of the version below, which is always the version of this
# checkout (check out a release tag, e.g. `git checkout v1.0.0`). To build them from source instead, add
# deploy/build.yml to COMPOSE_FILE and use `docker compose up -d --build`.
# Nothing here needs editing: your settings come from .env (see example.env),
# so checking out a newer tag 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.
services:
postgres:
image: postgres:16.15-alpine@sha256:aa6cb33cf4c19c765cefcf48d96176258800870a9a1e930ad126200f9d825139
container_name: infradeck-postgres
restart: unless-stopped
# The image's entrypoint prepares the data folder as root (owner and 0700 mode), then runs PostgreSQL as the
# postgres user, which keeps none of these. Its socket and lock files live in memory.
cap_drop: [ALL]
cap_add: [CHOWN, DAC_READ_SEARCH, FOWNER, SETUID, SETGID]
read_only: true
tmpfs:
- /var/run/postgresql:uid=70,gid=70
- /tmp
security_opt:
- no-new-privileges:true
networks: [data]
environment:
POSTGRES_DB: ${POSTGRES_DB:-infradeck}
POSTGRES_USER: ${POSTGRES_USER:-infradeck}
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in .env}
volumes:
- postgres_data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER:-infradeck} -d $${POSTGRES_DB:-infradeck}"]
interval: 10s
timeout: 5s
retries: 5
redis:
image: redis:7.4.12-alpine@sha256:c5d34a98396a4775e223c74e929162c35c5a2182901ba26b50ade939941ce14b
container_name: infradeck-redis
restart: unless-stopped
networks: [data]
# Needs a password: Redis holds the login sessions, so nothing that can merely reach it on the network
# may use it. Generate one with `openssl rand -hex 24` (letters and digits only, so it fits in a URL).
# Through the image's entrypoint, which hands /data to the redis user and drops root before Redis starts.
command: ["sh", "-c", "exec docker-entrypoint.sh redis-server --appendonly yes --requirepass \"$$REDIS_PASSWORD\""]
# Only what that hand-over needs: reading and chowning /data, and switching to the redis user.
cap_drop: [ALL]
cap_add: [CHOWN, DAC_READ_SEARCH, SETUID, SETGID]
read_only: true
security_opt:
- no-new-privileges:true
environment:
REDIS_PASSWORD: ${REDIS_PASSWORD:?Set REDIS_PASSWORD in .env (generate one with openssl rand -hex 24)}
volumes:
- redis_data:/data
healthcheck:
test: ["CMD-SHELL", "REDISCLI_AUTH=\"$$REDIS_PASSWORD\" redis-cli ping | grep -q PONG"]
interval: 10s
timeout: 5s
retries: 5
backend:
image: ghcr.io/karloks2005/infradeck/backend:1.0.0
container_name: infradeck-backend
restart: unless-stopped
# Runs as an unprivileged user (see the Dockerfile) with no capabilities and a read-only filesystem.
cap_drop: [ALL]
read_only: true
tmpfs:
- /tmp
security_opt:
- no-new-privileges:true
networks: [data, front]
environment:
DATABASE_URL: postgresql+psycopg://${POSTGRES_USER:-infradeck}:${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in .env}@postgres:5432/${POSTGRES_DB:-infradeck}
REDIS_URL: redis://:${REDIS_PASSWORD:?Set REDIS_PASSWORD in .env (generate one with openssl rand -hex 24)}@redis:6379/0
# Served over HTTPS by your reverse proxy, 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://${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}
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}
# Email notifications (Account → Notifications). Off unless SMTP_HOST and SMTP_FROM are set.
SMTP_HOST: ${SMTP_HOST:-}
SMTP_PORT: ${SMTP_PORT:-587}
SMTP_STARTTLS: ${SMTP_STARTTLS:-true}
SMTP_USER: ${SMTP_USER:-}
SMTP_PASSWORD: ${SMTP_PASSWORD:-}
SMTP_FROM: ${SMTP_FROM:-}
# Limits on what collectors can do. A check-in must come at least this share of the check interval after the
# previous one (0 switches it off); the install holds at most MAX_SERVERS; /docs is off unless enabled.
INGEST_MIN_SPACING_RATIO: ${INGEST_MIN_SPACING_RATIO:-0.25}
MAX_SERVERS: ${MAX_SERVERS:-200}
ENROLL_RATE_LIMIT: ${ENROLL_RATE_LIMIT:-30}
ENABLE_API_DOCS: ${ENABLE_API_DOCS:-false}
# Setup token for the very first account. Empty: one is generated and printed in the backend log.
ADMIN_BOOTSTRAP_TOKEN: ${ADMIN_BOOTSTRAP_TOKEN:-}
# How long a token from "Connect a server" stays valid, in seconds.
JOIN_TOKEN_TTL_SECONDS: ${JOIN_TOKEN_TTL_SECONDS:-900}
# Key that encrypts stored secrets such as two-factor secrets (generate: docker compose run --rm backend python -m src.backend.secrets_box).
SECRETS_KEY: ${SECRETS_KEY:-}
# 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
# Runs the incident agent's jobs (diagnoses) from the queue in Redis, apart from the backend, so a slow or
# stuck model never holds up the API. Stopping it only delays diagnoses; everything else keeps working.
# It needs the database, Redis and the internet (the model provider), and nothing else. See docs/containers.md.
agent-worker:
image: ghcr.io/karloks2005/infradeck/backend:1.0.0
container_name: infradeck-agent-worker
restart: unless-stopped
command: ["python", "-m", "src.agent.worker"]
networks: [data, front]
environment:
DATABASE_URL: postgresql+psycopg://${POSTGRES_USER:-infradeck}:${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in .env}@postgres:5432/${POSTGRES_DB:-infradeck}
REDIS_URL: redis://:${REDIS_PASSWORD:?Set REDIS_PASSWORD in .env (generate one with openssl rand -hex 24)}@redis:6379/0
# Decrypts the agent's API key, which Admin › Incident agent stores encrypted.
SECRETS_KEY: ${SECRETS_KEY:-}
PYTHONDONTWRITEBYTECODE: "1"
cap_drop: [ALL]
read_only: true
tmpfs:
- /tmp
security_opt:
- no-new-privileges:true
healthcheck:
test: ["CMD", "python", "-m", "src.agent.worker", "--health"]
interval: 30s
timeout: 5s
retries: 3
depends_on:
backend:
condition: service_healthy
# Monitors the machine running this stack. Other servers use collector-compose.yml.
collector:
image: ghcr.io/karloks2005/infradeck/collector:1.0.0
container_name: infradeck-collector
restart: unless-stopped
networks: [collector]
environment:
# Through the gate's internal listener (not published); the public listener refuses collectors.
INFRADECK_API_URL: http://collector-gate:8080/api
# Marks this collector as the machine running the dashboard (the charts at the top).
INFRADECK_DASHBOARD_HOST: "true"
# Nothing to configure: this machine shows up under "New servers detected"
# on the dashboard. An optional enrollment key skips that approval.
INFRADECK_ENROLL_KEY: ${INFRADECK_ENROLL_KEY:-}
INFRADECK_SERVER_NAME: ${INFRADECK_SERVER_NAME:-}
# Optional internet check, off when empty: comma-separated host:port targets this collector tries to reach.
INFRADECK_CONNECTIVITY_TARGETS: ${INFRADECK_CONNECTIVITY_TARGETS:-}
# Docker data comes through the read-only proxy; the collector has no Docker socket.
INFRADECK_DOCKER_HOST: /run/docker-proxy/docker.sock
INFRADECK_CHECK_INTERVAL_SECONDS: ${INFRADECK_CHECK_INTERVAL_SECONDS:-60}
INFRADECK_MACHINE_ID: ${INFRADECK_MACHINE_ID:-}
volumes:
- /proc:/host/proc:ro
- /:/hostfs:ro
- collector_state:/var/lib/infradeck-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 reads only what root owns or everyone may
# read, not other users' private files, even though / is mounted. Root-owned files (/etc/shadow,
# /root/.ssh, a root-owned .env) stay readable; see SECURITY.md.
cap_drop: [ALL]
read_only: true
security_opt:
- no-new-privileges:true
# Lets availability "Ping" checks send ICMP echo through an unprivileged datagram socket for the
# container's own group only. This grants no capability and no raw sockets; without it, ping checks
# simply report that ICMP is not permitted. Namespaced to this container.
sysctls:
- net.ipv4.ping_group_range=0 0
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:1.31.8-alpine@sha256:713fc2ebfd92e8217db451477182ee91944b123d2b1ee9fd5a8c6e91ca6c3a11
container_name: infradeck-collector-gate
restart: unless-stopped
networks: [front, collector]
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 six kinds of read request 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:
image: ghcr.io/karloks2005/infradeck/docker-proxy:1.0.0
container_name: infradeck-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"]
image: ghcr.io/karloks2005/infradeck/system-helper:1.0.0
container_name: infradeck-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
# Optional and off by default: names the process behind each listening port for the Network tab.
# Enable with: docker compose --profile port-owners up -d
# This is the most privileged piece of the stack. Seeing which process holds a socket means looking into
# other users' processes, which needs the host's /proc, CAP_SYS_PTRACE, CAP_DAC_READ_SEARCH and no
# AppArmor confinement. Together those can read any file on the host, so it gets no network, a
# read-only filesystem, and publishes only protocol, port and process name. Read SECURITY.md first.
port-owners:
profiles: ["port-owners"]
image: ghcr.io/karloks2005/infradeck/system-helper:1.0.0
container_name: infradeck-port-owners
restart: unless-stopped
user: "0:0"
cap_drop: [ALL]
cap_add: [SYS_PTRACE, DAC_READ_SEARCH]
network_mode: none
read_only: true
security_opt:
- no-new-privileges:true
- apparmor=unconfined
environment:
INFRADECK_HELPER_MODE: port-owners
volumes:
- /proc:/host/proc:ro
- system_events:/out
frontend:
image: ghcr.io/karloks2005/infradeck/frontend:1.0.0
container_name: infradeck-frontend
restart: unless-stopped
# Runs as the unprivileged nginx user (see the Dockerfile) with no capabilities and a read-only filesystem;
# it writes only its cache, its pid file and the TRUSTED_PROXIES settings, all in memory.
cap_drop: [ALL]
read_only: true
tmpfs:
- /tmp:uid=101,gid=101
- /var/cache/nginx:uid=101,gid=101
- /etc/nginx/trusted-proxies:uid=101,gid=101
security_opt:
- no-new-privileges:true
environment:
# Address or network of your reverse proxy; empty trusts nobody's X-Forwarded-For.
TRUSTED_PROXIES: ${TRUSTED_PROXIES:-}
# Serves the dashboard and proxies /api to the backend; your reverse proxy 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}:8080"
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: [front]
depends_on:
backend:
condition: service_healthy
networks:
# Three networks keep each container to what it needs. Redis and PostgreSQL are on `data` only, which has no
# route out; the collector is on `collector` only and can reach nothing but the gate.
data:
internal: true
front:
collector:
volumes:
postgres_data:
redis_data:
collector_state:
system_events:
docker_proxy_socket: