Docker Compose Healthchecks Checker
Check Docker Compose healthchecks for missing commands, timing risks, blocked readiness dependencies, and role-based coverage before release.| Service | Role | Scope | Healthcheck evidence | Timing / restart | Next action | Copy |
|---|---|---|---|---|---|---|
| {{ row.service }} | {{ row.role }} | {{ row.scope }} | {{ row.status }}{{ row.evidence }} | {{ row.timing_restart }} | {{ row.action }} |
| Service | Dependency | Condition | Health evidence | Posture | Next action | Copy |
|---|---|---|---|---|---|---|
| {{ row.service }} | {{ row.dependency }} | {{ row.condition }} | {{ row.health_evidence }} | {{ row.posture }} | {{ row.action }} |
A running container is not necessarily ready to serve traffic. A database process may exist before recovery finishes, an API may open its port before migrations complete, and a queue worker may start before its broker can accept work. Docker Compose can observe readiness only when a service or its image declares a meaningful healthcheck.
The healthcheck command becomes part of the stack's operating contract. It should test the service capability that a dependent container needs, not merely prove that a process or TCP port exists. A web service might check a local readiness route, while PostgreSQL commonly uses pg_isready and Redis can require a successful PING.
| Dependency condition | What Compose waits for | Typical fit |
|---|---|---|
service_started | The dependency container has started. | A dependent service that performs its own retries. |
service_healthy | The dependency healthcheck has passed. | A database, broker, or API that must be ready before use. |
service_completed_successfully | A one-shot dependency has exited successfully. | A migration, initialization, or setup job. |
Timing fields govern how quickly Docker detects success and failure. The interval sets the probe cadence, the timeout limits one attempt, retries allow transient failures, and the start period gives a cold-starting service time to initialize. These values should reflect the service's actual behavior rather than a copied universal preset.
Health and restart policy solve different problems. Health reports whether a running container can perform its job. Restart policy says what should happen after a container stops. A production service may need both, while an external orchestrator may own restart behavior instead.
A declaration audit can reveal missing commands, disabled checks, fragile timing, and readiness gates that cannot be satisfied. It cannot execute a probe or prove that an endpoint checks every dependency. Runtime evidence remains essential before a release.
How to Use This Tool:
Review the same Compose model that will enter version control or release handoff.
- Paste or load the Compose YAML. Correct a YAML error or missing top-level
servicesmap before interpreting any coverage result. - Choose the review scope. All runtime services excludes detected one-shot jobs, Core service roles focuses on stateful, app, worker, proxy, and scheduler roles, and Readiness dependency targets checks only services named by
depends_on. - Use standard timing for ordinary review, strict timing when explicit cadence and startup grace are required, or lenient timing when only invalid declaration shapes and invalid numeric values should affect classification.
- Keep restart review on for a production handoff when Compose should own recovery. Turn it off when another supervisor owns that responsibility.
- Run the audit and resolve readiness blockers first. Then review missing, disabled, invalid, or timing-review declarations service by service.
Interpreting Results:
Coverage measures strong Compose healthcheck declarations among services required by the selected scope. A service outside that scope remains visible but does not lower the percentage. A declared command that needs timing review is not counted as strong.
- Critical means at least one required healthcheck is disabled or invalid, or a dependency gate is blocked.
- Review means the model found another signal such as missing declaration, timing concern, restart gap, or readiness uncertainty.
- Clear means none of those static signals appeared under the chosen assumptions. It does not prove runtime readiness.
- Verify important fixes with
docker compose config --quiet,docker compose up --wait, container health state, logs, and an application-level request.
Technical Details:
A Compose healthcheck is valid here when its declaration is a mapping with a non-empty string test or a list beginning with CMD or CMD-SHELL. A false healthcheck, disable: true, or a list beginning with NONE is treated as disabled. Positive Compose durations are recognized from nanoseconds through hours.
Rule Core:
| Classification | Exact trigger | Meaning |
|---|---|---|
| Not declared | No service-level healthcheck key. | The image may still contain a Dockerfile healthcheck, but the Compose file does not settle that fact. |
| Disabled | False value, disable: true, or test: ["NONE"]. | Compose explicitly suppresses health reporting. |
| Invalid | Wrong declaration shape, empty command, unsupported list prefix, non-positive duration, or retries below 1. | The declared check cannot be trusted as written. |
| Review timing | The timeout is greater than or equal to the interval, or strict mode lacks interval, timeout, retries, or start period. | The command exists, but timing needs review. |
| Strong declaration | A valid active command with no applicable timing warning. | The static declaration is complete under the selected timing mode. |
Long-form depends_on is evaluated separately from service coverage. A service_healthy edge is ready-gated only when the dependency has a strong declaration. A timing-review check makes the edge a review item; an undeclared check remains uncertain because an image-level check may exist; a disabled or invalid check blocks the requested gate.
Formula Core:
The denominator contains only priority services selected by the current review scope.
C is coverage percent, S is the number of priority services with a strong declaration, and P is the priority-service count. The result retains up to six decimal places. For four priority services with three strong declarations, coverage is 75%.
Service roles and probe suggestions come from names, images, commands, and common product clues. They are review heuristics, not Compose syntax rules. The production profile enables restart-gap review when that check is selected; it does not rewrite Docker's healthcheck semantics.
Limitations and Privacy:
The YAML is parsed in the browser. No image is pulled, container started, probe executed, or network endpoint contacted. Source text is limited to 512 KiB and the review accepts at most 500 services.
- An absent Compose declaration does not prove the image lacks a Dockerfile
HEALTHCHECK. - A syntactically valid command may use a binary that is absent from the image or test the wrong dependency.
- Role detection can misclassify unusual names and custom images.
- A parser fallback or warning weakens dependency evidence. Validate the same source with Docker Compose before release.
References:
- Compose Specification, Compose Specification.
- Define services in Docker Compose, Docker Docs.
- Control startup and shutdown order in Compose, Docker Docs.
- How to deploy an app stack with Docker Compose, Simplified Guide.