Docker and Compose
Docker Compose health checks that test readiness
Write useful Compose health checks and use service_healthy for dependencies without mistaking process startup for readiness.
By AppLaunch Editorial · Reviewed 2026-08-25
Direct answer
A health check should prove the service can perform its critical local function, not merely that its process exists. Keep it fast and deterministic; use dependency conditions when startup order needs readiness, while still making applications retry transient downstream failures.
What this means in plain English
A running process is not always a working application. It may have started but still be loading, waiting for its database or stuck in a state where it cannot answer users. A health check is a small command that asks the service to prove it can do its basic job.
Keep the check quick and local. A web service might answer a simple health page that confirms its own important parts are ready. Do not make every check depend on half the internet, because an unrelated outage would make a healthy container look broken.
What should a health check prove?
| Liveness | Process can keep doing useful work |
|---|---|
| Readiness | Service can accept its intended traffic |
| Dependency | service_healthy gates startup but not every future outage |
A simple example
A database container starts its process in two seconds but needs another twenty seconds before it accepts queries. The web container uses a database health check and waits for a healthy result. It also keeps retrying later, because the database could restart again after launch.
What to do, step by step
1. Choose a lightweight application-aware endpoint or command.
Start here before buying anything or changing several settings at once. It gives you a clear starting point based on liveness: process can keep doing useful work. Write the result down so you can compare it later.
2. Set interval, timeout, retries and start period.
Use the same files, versions and settings that the real project will use. A quick test with an empty or different setup can look successful while completely missing the problem you are trying to solve.
3. Test both success and forced failure.
Try the busiest realistic situation, not the easiest one. Include the people, data, traffic or background work you genuinely expect, then watch for slowdowns and errors rather than relying on a single headline number.
4. Make the application reconnect after dependency restarts.
Finish by checking the result against dependency: service_healthy gates startup but not every future outage. Keep the old setting or release available until you know the change works and can be reversed safely.
One more useful tip
Force the health check to fail during testing. Stop the dependency or return a deliberate error and confirm that the unhealthy state appears, alerts fire and the service recovers in the way you expect.
Common mistakes and how to avoid them
Checking only that a TCP port opens.
This gives a misleading or unsafe result because it leaves out liveness. A better approach is to choose a lightweight application-aware endpoint or command, then check the result before making the change permanent.
Using an external service in every local health check.
This gives a misleading or unsafe result because it leaves out readiness. A better approach is to set interval, timeout, retries and start period, then check the result before making the change permanent.
Relying on depends_on instead of application retries.
This gives a misleading or unsafe result because it leaves out dependency. A better approach is to test both success and forced failure, then check the result before making the change permanent.
Words explained
- Compose
- Docker Compose is a file-based way to describe several containers, their settings, storage and networks as one application.
- health check
- A small test that tells Docker whether the application inside a container is actually working.
Quick checklist
- Choose a lightweight application-aware endpoint or command.
- Set interval, timeout, retries and start period.
- Test both success and forced failure.
- Make the application reconnect after dependency restarts.
Common questions
What is the simple answer?
A health check should prove the service can perform its critical local function, not merely that its process exists. Keep it fast and deterministic; use dependency conditions when startup order needs readiness, while still making applications retry transient downstream failures.
What should I check first?
Start with liveness: process can keep doing useful work. That is usually more useful than choosing from a marketing label or copying somebody else’s setting.
How can I make the change safely?
Choose a lightweight application-aware endpoint or command. Then change one thing at a time, keep a backup or old version, and use the same real-world test after each change.
What is the easiest mistake to avoid?
Checking only that a TCP port opens. Avoiding that one mistake makes the rest of the comparison much more trustworthy.