Skip to main content

Single-Node Deployment

Single-node deployment means running the server and one agent together on the same host.

This is the easiest way to get started and is the deployment model used in the Quick Start.

When To Use It​

  • You want the fastest path to a working install.
  • You are monitoring one homelab machine first.
  • You want to validate Docker, file watcher, and systemd behavior before expanding to more nodes.

Canonical Compose Example​

This snippet is pulled from the repo-root docker-compose.yml.

services:
  blackbox-server:
    image: ghcr.io/maxjb-xyz/blackbox-server:latest
    container_name: blackbox-server
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - blackbox-data:/data
    environment:
      JWT_SECRET: "change-me-to-a-long-random-string"
      AGENT_TOKENS: "homelab=change-me-to-a-secret-agent-token"
      WEBHOOK_SECRET: "change-me-to-a-webhook-secret"
      TZ: "America/New_York" # optional: set to your local timezone so container logs match your clock
    networks:
      - blackbox

  blackbox-agent:
    image: ghcr.io/maxjb-xyz/blackbox-agent:latest
    container_name: blackbox-agent
    restart: unless-stopped
    cap_drop:
      - ALL
    cap_add:
      - SETUID
      - SETGID
    security_opt:
      - no-new-privileges:true
    read_only: true
    volumes:
      - blackbox-agent-data:/data
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - /etc:/watch/etc:ro
      - /run/log/journal:/run/log/journal:ro
      - /var/log/journal:/var/log/journal:ro
      - /etc/machine-id:/etc/machine-id:ro
    environment:
      SERVER_URL: "http://blackbox-server:8080"
      AGENT_TOKEN: "change-me-to-a-secret-agent-token"
      NODE_NAME: "homelab"
      WATCH_PATHS: "/watch/etc"
      WATCH_SYSTEMD: "true"
      TZ: "America/New_York" # optional: set to your local timezone so container logs match your clock
    networks:
      - blackbox

volumes:
  blackbox-agent-data:
  blackbox-data:

networks:
  blackbox:
    driver: bridge
  • One blackbox-server container.
  • One blackbox-agent container.
  • One persistent volume for server data.
  • One persistent volume for the agent queue.

Important Notes​

  • Keep the server's /data directory persistent so blackbox.db survives restarts.
  • Keep the agent's /data directory persistent so queued events survive network or server downtime.
  • If you mount host config trees, make sure the agent runtime UID can traverse them.