ComposeHealthCheck: Catch Docker Compose Startup Bugs Before They Cost You an Hour

#webdev #devops #docker #kubernetes

If you've ever had your app throw "connection refused" against a database that's clearly running, you already know the problem: depends_on only waits for a container to start, not for the process inside it to actually be ready.

Postgres reports as running well before it's finished initializing. Compose has no idea. Your app tries to connect anyway, and you spend the next hour debugging a race condition that a config change would have fixed.

I built ComposeHealthCheck to catch this class of bug before it happens.

What it checks

Paste your docker-compose.yml and it will:

Flag depends_on entries missing condition: service_healthy on a target that actually defines a healthcheck
Catch healthcheck test commands that call curl or wget, binaries that are often missing in minimal images like alpine or distroless
Warn when timeout or retries are left unset on a healthcheck
Walk the entire depends_on graph and detect circular dependencies, showing the exact cycle (e.g. worker → queue → worker) instead of a generic error
Render a visual startup graph so you can see dependency order at a glance

How it's different from `docker compose config`

docker compose config is the authoritative check for whether your YAML is structurally valid. It won't tell you that your api service probably meant condition: service_healthy instead of the default service_started — that's all valid schema, just not what you meant. ComposeHealthCheck is a complement for exactly that gap: logical mistakes a schema validator has no reason to flag.

Privacy

Everything runs 100% client-side. The YAML is parsed locally in the browser, no network requests are made, and no data leaves your machine — safe to paste a file with real service names, ports, and internal hostnames.