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
# Development / laptop stack. For the server behind Traefik use docker-compose.server.yml.
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:
build:
context: .
dockerfile: docker/backend.Dockerfile
container_name: infradeck-backend
image: infradeck-backend:latest
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
# Set to true when the dashboard is served over HTTPS.
SESSION_COOKIE_SECURE: ${SESSION_COOKIE_SECURE:-false}
# This stack has one listener, so collector traffic can't be told apart (the backend's default is strict).
COLLECTOR_ACCESS: open
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}
# 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:-}
# 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:-}
# 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}
# Connect a server panel: images remote hosts install, and the address they reach this dashboard at.
COLLECTOR_IMAGE: ${COLLECTOR_IMAGE:-}
DOCKER_PROXY_IMAGE: ${DOCKER_PROXY_IMAGE:-}
COLLECTOR_PUBLIC_URL: ${COLLECTOR_PUBLIC_URL:-}
# Browsers and remote collectors reach the API through the frontend at /api;
# the direct port is only published on this machine for debugging. 8060 keeps it clear of the
# many other tools that use 8000; set BACKEND_PORT in .env if 8060 is taken too.
ports:
- "127.0.0.1:${BACKEND_PORT:-8060}:8000"
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:
build:
context: .
dockerfile: docker/backend.Dockerfile
image: infradeck-backend:latest
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:
build:
context: .
dockerfile: docker/collector.Dockerfile
image: infradeck-collector:latest
container_name: infradeck-collector
restart: unless-stopped
networks: [front]
environment:
INFRADECK_API_URL: http://backend:8000
# 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
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
# 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:
build:
context: .
dockerfile: docker/docker-proxy.Dockerfile
image: infradeck-docker-proxy:latest
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"]
build:
context: .
dockerfile: docker/system-helper.Dockerfile
image: infradeck-system-helper:latest
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"]
build:
context: .
dockerfile: docker/system-helper.Dockerfile
image: infradeck-system-helper:latest
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:
build:
context: .
dockerfile: docker/frontend.Dockerfile
args:
VITE_API_BASE_URL: /api
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 a reverse proxy in front of this one; empty trusts nobody's X-Forwarded-For.
TRUSTED_PROXIES: ${TRUSTED_PROXIES:-}
networks: [front]
# 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}:8080"
depends_on:
backend:
condition: service_healthy
# Optional public HTTPS entry point: docker compose --profile https up -d
caddy:
image: caddy:2.11.9-alpine@sha256:0bbb055bda6793c999bde78b1b5ce3e89f829fb031af2cf50056ea1246559fee
container_name: infradeck-caddy
profiles: ["https"]
restart: unless-stopped
networks: [front]
environment:
DOMAIN: ${DOMAIN:-localhost}
ports:
- "80:80"
- "443:443"
- "443:443/udp"
volumes:
- ./docker/Caddyfile:/etc/caddy/Caddyfile:ro
- caddy_data:/data
- caddy_config:/config
depends_on:
- frontend
networks:
# Redis and PostgreSQL are reachable only by the backend and the agent worker; the collector can reach the backend
# and nothing else.
data:
internal: true
front:
volumes:
postgres_data:
redis_data:
collector_state:
system_events:
docker_proxy_socket:
caddy_data:
caddy_config: