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.

15.6 KB
Raw Blame
# 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: