Docker Compose Healthchecks Checker

Introduction:

Multi-container applications often fail at the boundary between "started" and "ready." A database container can be running while it is still replaying logs, a message broker can have an open process before it accepts clients, and a web service can bind a port before its dependencies are reachable. Docker Compose can start services in dependency order, but startup order is not the same as application readiness.

A Compose healthcheck gives Docker a command to run inside a service container so the container can be reported as healthy, unhealthy, starting, or without a declared health state. The command should test the service condition that downstream containers actually need. A PostgreSQL service is better checked with pg_isready than with a bare TCP probe, and an HTTP API should usually expose a small readiness endpoint that verifies its own startup path.

The most important distinction is the one between a start-only dependency and a ready-gated dependency. Short-form depends_on and condition: service_started only express order. condition: service_healthy asks Compose to wait until the dependency healthcheck passes before creating the dependent service. That condition is only meaningful when the dependency has a real healthcheck, sensible timing, and a command that can succeed in the image.

Healthcheck timing controls how noisy or forgiving the signal is. interval controls how often the probe runs, timeout limits one attempt, retries sets how many failures Docker tolerates, and start_period gives slow services a grace window while they initialize. Timing that is missing or too tight can turn a good command into a flaky signal, especially for databases, brokers, and services that compile assets or run migrations at startup.

Restart behavior answers a different question. A healthcheck reports whether a container is healthy; a restart policy controls whether a stopped or failed container should be started again. Production Compose files commonly need both, while local development files may intentionally leave helper services lighter. A static review can find missing declarations, weak timing, and questionable dependency gates, but it cannot prove that the probe binary exists in the image or that the service remains healthy under real load.

The safest review treats healthchecks as part of a readiness contract. The Compose file should show which services need probes, which dependencies must wait for real readiness, which restarts are owned by Docker or another supervisor, and which gaps still need runtime testing before release.

How to Use This Tool:

Start by choosing the same review posture you would use in a pull request or handoff, then paste or load the Compose YAML and read the gap count against that posture.

1. Enter a meaningful Stack name. The label appears in copied or downloaded structured results so the review can be tied back to the Compose project, environment, or change request.
2. Choose Audit profile. Production handoff is strict about required services and restart ownership, CI dependency gate emphasizes dependency readiness, and Local development review keeps helper-service wording lighter.
3. Set Review scope. Use All runtime services for a release pass, Core app, worker, proxy, and stateful services for a narrower service review, or Readiness dependency targets when the main question is whether depends_on targets have usable probes.
4. Pick Timing review. Standard timing checks expects explicit interval, timeout, and retries. Strict startup timing checks also asks for startup grace. Only invalid timing limits warnings to fragile or invalid timing boundaries.
5. Leave Restart policy audit on for production Compose files unless another orchestrator or host-level supervisor owns restarts. When it is on, missing restart behavior can appear even when a service has a valid healthcheck.
6. Paste the content into Compose YAML, drop a YAML/YML/TXT file on the textarea, browse for a file up to 2 MB, or load the sample stack. The source status line shows the selected file name and character count.
7. If the alert shows Review Compose input, fix that problem before acting on the tables. Empty input asks for a Compose file, invalid YAML reports the parse error, and content without a top-level services map cannot be audited.
8. Use the summary first, then inspect Healthcheck Coverage, Readiness Gate Ledger, Probe Pattern Brief, Coverage Mix Chart, and JSON for the detailed evidence behind the gap count.

Finish by fixing the first missing, disabled, invalid, or weak service row and any readiness edge marked Blocker. Re-run the review after each Compose edit so the selected profile and scope stay consistent.

Interpreting Results:

The headline gap count covers required services whose healthchecks are missing, disabled, or invalid under the selected audit profile and review scope. A 0 gaps result means no required missing-probe gaps were found; it does not prove that the command works in the real image, that the endpoint checks enough dependencies, or that the service survives load.

• Covered means the service has a non-empty healthcheck command and no timing warnings under the selected timing review.
• Weak means the command exists, but timing is missing or fragile. Weak rows do not count as missing gaps, but they should be fixed before depending on service_healthy.
• Missing, Disabled, and Invalid rows count as gaps when the service is required. Disabled healthchecks usually need an explicit reason because they can suppress image-level health behavior.
• Blocker in Readiness Gate Ledger means a service_healthy dependency points at a service without a valid healthcheck. Fix that before trusting the startup sequence.
• Race risk and Start-only rows point to dependencies that may start in order but still become usable later than the dependent service expects.
• Restart review means recovery ownership is unclear for a required production service. Add a restart policy or document the external supervisor.

Use the chart to spot role-level patterns, then verify important services outside the page with docker compose ps, container health state, logs, and one real dependent-service startup. Static YAML review is a preflight check, not a runtime proof.

Technical Details:

Compose healthchecks are service-level declarations. The core field is test, which can be a list beginning with CMD, CMD-SHELL, or NONE, or a string that behaves like shell form. NONE and disable: true suppress health reporting, which is useful only when the image-level healthcheck should be intentionally removed.

Dependency conditions make the health state operational. service_started follows container startup order. service_healthy waits for the dependency healthcheck to pass. service_completed_successfully fits one-shot jobs such as migrations. A service can also request dependency restart propagation with long-form depends_on, but that is separate from container-runtime restart policies.

Rule Core

The review is a deterministic YAML declaration check. Service names, image names, build settings, commands, and environment keys provide role clues; the selected profile and scope decide which roles are required to have healthchecks.

Status Boundaries

Timing Review

Standard timing review expects interval, timeout, and retries. Strict timing review also expects start_period or equivalent startup grace. Lenient timing review skips missing-field notes but still catches fragile numeric relationships.

Coverage Formula

Coverage is calculated only across required services. Optional services can be shown in the tables and chart without lowering the percentage.

For example, four required services with two covered healthchecks produce 50% coverage and two gaps when the remaining required services are missing, disabled, or invalid. Weak healthchecks remain outside the gap count because the command exists, but they still affect readiness confidence.

Limitations and Privacy:

The review is based on the YAML declarations supplied to the page. It does not run containers, execute probe commands, inspect images, open network sockets, or confirm that an endpoint checks every dependency. Treat the result as a preflight audit before runtime testing.

• Pasted Compose text and selected files are parsed in the browser; the checker does not upload the YAML to a server-side parser.
• File loading is limited to YAML, YML, or TXT input up to 2 MB.
• If the full YAML parser cannot load, a limited indentation scan may detect services but lose detailed dependency information.
• Role detection uses service names and common image, command, and environment clues, so unusual service names may need manual review.
• Probe suggestions are starting points. Confirm the command exists in the image and matches the real readiness condition.

Advanced Tips:

• Use Readiness dependency targets when a pull request mainly changes depends_on. That keeps the required set focused on services that other containers actually wait for.
• Switch to Strict startup timing checks for databases, brokers, search services, and cold-starting APIs. A missing start_period is worth fixing before a readiness gate depends on that service.
• Keep Restart policy audit on for production handoff unless restarts are owned elsewhere. If an external supervisor owns recovery, turn the switch off and record that ownership outside the Compose file.
• Read Probe Pattern Brief as a starting point, not as copy-ready policy. Confirm the command exists in the image and checks the real readiness condition before adding it to the Compose file.
• Use Coverage Mix Chart to find role-level patterns, then use Healthcheck Coverage for service-by-service fixes. The chart is useful for review triage, while the table carries the action text.
• If parser warnings mention multiple YAML documents or a fallback scan, validate the same source with docker compose config --quiet before treating the static review as handoff evidence.

Worked Examples:

Orders stack before production handoff

The sample stack contains api, worker, db, and redis. With Production handoff, All runtime services, and Standard timing checks, api and db are covered while worker and redis are missing required probes. The summary reports 2 gaps, and Healthcheck Coverage shows the service-specific action for each missing row.

The same input also demonstrates a readiness blocker. worker depends on redis with condition: service_healthy, but redis has no valid healthcheck. Readiness Gate Ledger marks that edge as Blocker because the requested gate cannot be trusted until Redis has a probe.

CI review focused on dependency targets

A pull request changes only startup ordering, so Review scope is set to Readiness dependency targets. In that scope, services named by depends_on decide the required set. A database with a strong pg_isready healthcheck stays Covered, while a cache with no probe receives a suggested Redis PING pattern. Services outside the dependency target set remain visible without becoming missing-healthcheck gaps.

Weak timing on a real command

A PostgreSQL service can include a useful pg_isready command but omit interval, timeout, and retries. Under Standard timing checks, that row becomes Weak instead of Covered. Under Strict startup timing checks, a missing start_period adds another warning for cold starts.

Invalid YAML before any audit

If the pasted Compose file has broken indentation or an unclosed string, the alert shows Review Compose input with an invalid-YAML message. Fix the YAML first, then confirm Healthcheck Coverage lists the expected service names before using any action, chart, or JSON output.

FAQ:

Glossary:

Healthcheck

A command Docker runs for a service container to decide whether the container is healthy.

service_started

The dependency condition that requires the dependency container to start, without waiting for health readiness.

service_healthy

The dependency condition that waits for the dependency healthcheck to pass before the dependent service is created.

service_completed_successfully

A dependency condition for one-shot jobs that must finish successfully before another service starts.

start_period

A startup grace period that keeps early healthcheck failures from counting while a service initializes.

Readiness blocker

A dependency edge where service_healthy is requested but the dependency lacks a valid healthcheck.

Restart policy

Configuration that states how Docker or a deployment platform should restart a stopped or failed container.

References:

• Compose Specification, Compose Specification.
• Define services in Docker Compose, Docker Docs.
• Control startup and shutdown order in Compose, Docker Docs.
• Start containers automatically, Docker Docs.
• How to deploy an app stack with Docker Compose, Simplified Guide.
• How to set a container restart policy in Docker, Simplified Guide.