/bin/hp_healthcheck returns non-OK status 500 in v0.6.2 - container goes unhealthy

[dillonradio]

Description

Description

The built-in healthcheck binary /bin/hp_healthcheck in the v0.6.2 image
returns a 500 status code, causing the container to be marked as unhealthy
by Docker. This prevents Traefik (and likely other reverse proxies) from
routing traffic to the container as they skip unhealthy containers by default.

Steps to Reproduce

1. Run headplane v0.6.2 using the standard Docker image
2. Wait for the healthcheck to run (30s interval, 5s start period)
3. Container is marked as unhealthy despite the app running correctly on port 3000

Investigation

• The app starts and runs correctly on port 3000
• /admin/ returns HTTP 302 (working correctly)
• The healthcheck binary exits with code 500
• The image contains no shell, curl, or wget making it impossible to
  override with CMD-SHELL
• Overriding with healthcheck: disable: true in docker-compose resolves the issue

Expected Behaviour

/bin/hp_healthcheck should return 0 when the app is running correctly.

Environment

• Headplane version: 0.6.2
• Docker version: 29.4.0, build 9d7ad9f
• Host OS: Linux Mint 22.1

Headplane Version

v0.6.2

Headscale Version

v0.28.0

[linear]

HP-532

[geekau]

Not a bug, is a documentation and implementation problem.

Headplane doesn't have a CMD-SHELL, so you need to use CMD instead.

Check health inside container:

docker exec -it headplane /bin/hp_healthcheck

Returns:

Health check passed.

Can also check health state:

docker inspect headplane --format '{{json .State.Health}}' | jq

Returns:

{
  "Status": "healthy",
  "FailingStreak": 0,
  "Log": [
    {
      "Start": "2026-05-16T23:19:53.401739313+10:00",
      "End": "2026-05-16T23:19:53.446602139+10:00",
      "ExitCode": 0,
      "Output": "Health check passed.\n"
    },
    {
      "Start": "2026-05-16T23:20:23.44711239+10:00",
      "End": "2026-05-16T23:20:23.510670881+10:00",
      "ExitCode": 0,
      "Output": "Health check passed.\n"
    },
    {
      "Start": "2026-05-16T23:20:53.511107622+10:00",
      "End": "2026-05-16T23:20:53.563455543+10:00",
      "ExitCode": 0,
      "Output": "Health check passed.\n"
    },
    {
      "Start": "2026-05-16T23:21:23.563989788+10:00",
      "End": "2026-05-16T23:21:23.617197807+10:00",
      "ExitCode": 0,
      "Output": "Health check passed.\n"
    },
    {
      "Start": "2026-05-16T23:21:53.618481785+10:00",
      "End": "2026-05-16T23:21:53.669367619+10:00",
      "ExitCode": 0,
      "Output": "Health check passed.\n"
    }
  ]
}

Add the following to your docker compose file:

    healthcheck:
      test: ["CMD", "/bin/hp_healthcheck"]
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 30s

Working compose file:

  headplane:
    image: ghcr.io/tale/headplane:latest
    container_name: headplane
    restart: unless-stopped
    networks:
      - mediastack
    ports:
      - "${WEBUI_PORT_HEADPLANE:?err}:3000"
    volumes:
      - "/var/run/docker.sock:/var/run/docker.sock:ro"
      - "${FOLDER_FOR_APPDATA:?err}/headplane/data:/var/lib/headplane"
      - "${FOLDER_FOR_APPDATA:?err}/headplane/config.yaml:/etc/headplane/config.yaml"
      - "${FOLDER_FOR_APPDATA:?err}/headscale/config.yaml:/etc/headscale/config.yaml"
      - "${FOLDER_FOR_APPDATA:?err}/headscale/dns_records.json:/etc/headscale/dns_records.json"
    environment:
      - TZ=${TIMEZONE:?err}
    healthcheck:
      test: ["CMD", "/bin/hp_healthcheck"]
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 30s
    labels:
      - traefik.enable=true
    # ROUTERS
      - traefik.http.routers.headplane.service=headplane
      - traefik.http.routers.headplane.rule=Host(`headplane.${CLOUDFLARE_DNS_ZONE:?err}`) && PathPrefix(`/admin/`)
      - traefik.http.routers.headplane.entrypoints=secureweb
      - traefik.http.routers.headplane.middlewares=authentik-forwardauth@file,security-headers@file,traefik-bouncer@file
    # SERVICES
      - traefik.http.services.headplane.loadbalancer.server.scheme=http
      - traefik.http.services.headplane.loadbalancer.server.port=3000
    # MIDDLEWARES

Documentation and example docker compose file probably need an update.