Docker · Reliability
Docker Health Checks: Test the App, Not Just the Process
Use bounded probes and explicit startup timing to detect an unresponsive application inside a running container.
A container can keep running while its web server stops responding. Docker HEALTHCHECK adds a separate health signal by executing a probe inside the container.
Choose a meaningful probe
Have a small command request a lightweight endpoint on the application’s local port. Ensure the probing executable exists in the final image. A missing curl binary tests packaging failure rather than application health.
Set bounded timing
For example, HEALTHCHECK --interval=30s --timeout=3s --start-period=20s --retries=3 CMD /app/check-health runs your probe with explicit limits. Implement check-health to exit 0 for success and 1 for failure. Avoid the reserved exit code 2.
Allow startup time
The health status starts as starting. A successful probe makes it healthy; consecutive failures eventually make it unhealthy. The start period gives initialization breathing room, although a success during that period starts normal failure counting.
Keep diagnostics useful
Docker stores limited probe output for inspection. Return a short explanation without credentials or sensitive application data. Keep the endpoint inexpensive and free of writes.
Test failure deliberately
Simulate an unresponsive endpoint and inspect the health result. Document separately how your deployment platform responds to an unhealthy container.