homelab-codex-ws/services/control-plane/docker-compose.yml

services:
  operator-ui:
    build: .
    container_name: control-plane-ui
    user: "1000:1000"
    command: python src/operator_ui.py
    ports:
      # Loopback: node-agent on the VPS runs with network_mode: host and probes
      # localhost:18180/summary directly (_check_control_plane_health in
      # node_agent.py). Tailscale IP: runtime-materializer@PIHA and other mesh
      # consumers reach this as http://100.95.58.48:18180. No 0.0.0.0 — this
      # host previously had NO 0.0.0.0 exemption and /action/mutate has no auth,
      # so a public bind lets anyone on the internet approve remediation
      # actions. Same dual-bind pattern as services/ollama/docker-compose.yml.
      # Requires .env (from env.example) next to this file at deploy — see
      # services/fleet-prometheus/README.md for the "missing .env silently
      # binds 0.0.0.0" gotcha that also applies here.
      - "127.0.0.1:18180:8080"
      - "${TAILSCALE_BIND_IP}:18180:8080"
    volumes:
      - /opt/homelab:/opt/homelab
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/', timeout=3).read()"]
      interval: 30s
      timeout: 10s
      retries: 3

  observer:
    build: .
    container_name: control-plane-observer
    user: "1000:1000"
    command: python /repo/scripts/observer/observer.py
    volumes:
      - /opt/homelab:/opt/homelab
      - ../..:/repo:ro
    restart: unless-stopped
    environment:
      - REPO_ROOT=/repo
      - RUNTIME_PATH=/opt/homelab
    healthcheck:
      test: ["CMD", "test", "-f", "/opt/homelab/state/observer.heartbeat"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 5s

  supervisor:
    build: .
    container_name: control-plane-supervisor
    user: "1000:1000"
    command: python src/supervisor.py
    volumes:
      - /opt/homelab:/opt/homelab
      - ../..:/repo:ro
    restart: unless-stopped
    environment:
      - REPO_ROOT=/repo
      - RUNTIME_PATH=/opt/homelab
    healthcheck:
      # Freshness, not just existence: `test -f` stays true forever once the
      # heartbeat file is created once, even if the reconcile loop has been
      # silently frozen for hours (see 2026-07-15 incident — container reported
      # "healthy" for 24h with a dead loop). Fail if the heartbeat hasn't been
      # touched in the last 180s (loop interval 30s + RECONCILE_TIMEOUT 90s +
      # buffer for a legitimately slow cycle).
      test: ["CMD", "python", "-c", "import os,sys,time; p='/opt/homelab/state/supervisor.heartbeat'; sys.exit(0 if os.path.exists(p) and time.time()-os.path.getmtime(p)<180 else 1)"]
      interval: 60s
      timeout: 5s
      retries: 3
      start_period: 10s

  executor:
    build: .
    container_name: control-plane-executor
    user: "1000:1000"
    group_add:
      - "999"
    command: python src/executor.py
    volumes:
      - /opt/homelab:/opt/homelab
      # Read-only since the redeploy fix: the executor used to run
      # scripts/deploy/deploy-node.sh out of this mount (it never worked — see
      # kb/services/job-deploy-runner.md). Deploys now happen on the node itself, so
      # nothing here needs write access to the checkout.
      - ../..:/repo:ro
      - /var/run/docker.sock:/var/run/docker.sock
    restart: unless-stopped
    environment:
      - REPO_ROOT=/repo
      - RUNTIME_PATH=/opt/homelab
    healthcheck:
      test: ["CMD", "test", "-f", "/opt/homelab/state/executor.heartbeat"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 5s