Docker healthchecks can tell you when a container’s application passes a defined probe, and Docker Compose can use that signal to delay dependent services until a dependency is healthy. They do not, on their own, make deployments faster or guarantee minimal downtime: rollout policy, spare capacity, traffic routing, and rollback are controlled by the platform that runs the containers.
What a Docker healthcheck tells you
A Dockerfile HEALTHCHECK runs a command inside a container and adds a health state alongside its ordinary container status. A container may be running while its health state is still starting or has changed to unhealthy. The check is only as meaningful as its command: a process-exists test is not equivalent to confirming that the application can serve the request your users need.
As an Amazon Associate I earn from qualifying purchases.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minutePC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Docker interprets exit code 0 as success and 1 as failure; exit code 2 is reserved. Passing checks result in healthy status. The configured number of consecutive failures is required before Docker marks the container unhealthy. See Docker’s Dockerfile reference for the instruction and status behavior.
Choose a probe and timing that fit the application
Use a probe that tests the service condition that matters. For an HTTP service, that might be an endpoint that reports whether the app can handle the intended request. A simple process check can pass even while the application is unable to serve traffic. Keep probes inexpensive, and make sure any executable they call is present in the image.
#1 Best Overall
Docker’s current Dockerfile reference documents these defaults. They are defaults, not recommended settings for every workload:
| Setting | Dockerfile default | What it controls |
|---|---|---|
--interval |
30 seconds | Time between checks. |
--timeout |
30 seconds | How long a check can run before it is treated as a failure. |
--start-period |
0 seconds | Grace time for startup failures before they count toward the retry threshold. |
--start-interval |
5 seconds | Check interval during the start period. |
--retries |
3 | Consecutive failures needed to mark the container unhealthy. |
Docker’s HEALTHCHECK documentation explains that a successful check during the start period ends the grace behavior for later failures: “When a health check succeeds during the start period, the container is considered started and all consecutive failures will be counted towards the maximum number of retries.” In practical terms, a service that passes an early probe and then fails will have those subsequent failures count normally.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Rank #2
start_interval requires Docker Engine 25.0 or later. Check the target Engine version before using it. For Compose files, start_interval is documented as introduced in Compose 2.20.2, so both the Compose implementation and Engine must support the feature. See the Compose services healthcheck reference.
Here is an illustrative Dockerfile shape; replace the endpoint and timings with values appropriate to the application, and ensure the image contains curl:
Rank #3
HEALTHCHECK --interval=30s --timeout=5s --start-period=30s --retries=3 \
CMD curl -f http://localhost/health || exit 1Healthcheck output written to standard output or standard error is retained with the health status. Docker currently stores only the first 4096 bytes, so concise, actionable failure messages are more useful when inspecting a bad check.
Make Compose wait for a dependency to be healthy
Compose starts services in dependency order, but the short form of depends_on only ensures a dependency has started. It does not wait for the application inside that service to become ready. When a dependent service must wait for a healthcheck to pass, use long syntax with condition: service_healthy. Docker documents this distinction in its Compose startup-order guide.
This example follows the structure of Docker’s PostgreSQL startup-order example. Its 10-second interval, 10-second timeout, five retries, and 30-second start period are illustrative values, not a universal database recipe:
services:
db:
image: postgres:18
healthcheck:
test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
interval: 10s
timeout: 10s
retries: 5
start_period: 30s
web:
depends_on:
db:
condition: service_healthyThe doubled dollar signs defer variable interpolation to the container environment in Compose. In Compose healthcheck configuration, test can use CMD or CMD-SHELL; Compose settings can override the image’s Dockerfile healthcheck settings. Supported fields include test, interval, timeout, retries, start_period, and, in compatible versions, start_interval.
Best Value
- Docker, Docker Swarm, Docker Compose, Programmer, Developer, Coding, Programming, Software Engineer, Code, DevOps, Deploy, Deployment, Kubernetes, Salt, Puppet, Chef, Terraform, Container, AWS, Azure, Cloud, Geek, Funny, Computer, Software, Tech, IT
- Integration, Scrum, Compile, Compilation, Science, Bug, Debug, Python, Linux, Java, Javascript, Scala, Dotnet, Kotlin
- Lightweight, Classic fit, Double-needle sleeve and bottom hem
Why a healthcheck alone cannot prevent deployment downtime
A healthcheck produces a signal. A runtime or deployment platform decides whether that signal affects rollout progression, replacement, traffic routing, or rollback. Compose separates healthcheck configuration from deployment update configuration, and deployment support can vary by implementation and backend. The Compose Deploy Specification describes start-first and stop-first update-order options where supported; verify that the target environment implements the option you plan to use. A Compose healthcheck by itself is not a zero-downtime deployment plan.
Free tools Windows power users keep installed
One-click scans. No signup required.
Operators often phrase the goal as “How do I deploy new tasks without downtime?” AWS uses that question in ECS support material; “tasks” in this context are ECS runtime units, not a Docker healthcheck setting. ECS documentation shows how a specific platform can combine health signals with rollout controls.
ECS rolling deployments
Amazon ECS rolling deployments progressively replace tasks. The deployment’s minimum healthy and maximum task percentages control how many tasks can remain running during the rollout. ECS also documents failure detection and rollback mechanisms. These are ECS controls, not behavior guaranteed by Docker Engine or Compose. See Amazon ECS rolling deployments.
ECS blue/green deployments
ECS blue/green deployment maintains two environments, validates a new service revision before shifting production traffic, and supports faster rollback. AWS identifies zero-downtime needs as one suitable use case for this ECS-specific approach. Its isolation and pre-switch validation come with the need to run overlapping environments; they should not be generalized to a basic Compose deployment. See Amazon ECS blue/green deployments.
Compare rollout strategies by operational needs
| Consideration | Rolling replacement | Blue/green |
|---|---|---|
| Capacity during rollout | Can avoid the cost of two full environments; the configured task percentages determine overlap. | Requires two environments to coexist during the switch. |
| Traffic change | Tasks are replaced progressively; platform behavior determines how traffic follows the rollout. | Production traffic shifts to the new environment after validation. |
| Validation before production traffic | Depends on the platform’s rollout checks and configuration. | New revision can be validated before traffic shifts. |
| Rollback | ECS documents failure detection and rollback mechanisms; details depend on configuration. | ECS describes faster rollback as an advantage of maintaining separate environments. |
| Stateful services | Plan for compatibility while old and new tasks may coexist and be replaced. | Plan for data and schema compatibility across both environments before switching. |
The right choice depends on whether the platform can overlap old and new capacity, how it routes traffic, whether it validates the new version before switching, and how quickly the service can recover. A healthcheck can contribute to readiness decisions, but it cannot supply those deployment mechanics.
Recommended Free Tools
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
