A running container does not guarantee a working application. Docker can tell when the container’s main process exits, but an API can keep running while every request fails. A health check tests application behavior so that failure becomes visible in the container’s health status. section 8.1
An API that looks fine until you use it
A random-number API returns numbers for its first three requests, then returns HTTP 500 for every later request. Its container still shows as Up because the process has not exited. This is the failure a health check needs to reveal. section 8.1
Add a `HEALTHCHECK` instruction to the Dockerfile to run a test inside the container. For the API, the check calls its `/health` endpoint with `curl --fail`. After the API enters its failed state and enough checks fail, Docker reports the container as unhealthy. Inspecting the container shows the health status and check logs; the container itself remains up. section 8.1
Listing 8.1 The HEALTHCHECK instruction in a Dockerfile
FROM diamol/dotnet-aspnet:2e ENTRYPOINT ["dotnet", "/app/Numbers.Api.dll"] HEALTHCHECK CMD curl --fail http:/./localhost:8080/health WORKDIR /app COPY --from=builder /out/ .
The Dockerfile listing places an HTTP check alongside the application entry point. The check tests the application rather than merely confirming that its process exists. section 8.1
A small check utility is an alternative to a shell command. It can use the application’s configuration and libraries, handle retries or branches, and test resources such as database connections or expected certificate files. A multi-stage build can compile the utility and copy it into the final image; the API’s .NET utility replaces the need for `curl` in that image. section 8.3
In Docker Compose, configure when checks run and how failures are judged:
- Set `interval` between checks and `timeout` for the maximum time each check may take. section 8.4
- Set `retries` for consecutive failures before an unhealthy result, and `start_period` to allow startup time before checks begin. section 8.4
- Use `test` to add a check to a service whose image has none. Choose settings that detect failures without excessive work or false alarms from temporary faults. section 8.4
Health checks run periodically, so keep them focused on key application behavior and inexpensive to execute. They differ from dependency checks, which run at startup and can make a container exit when a required service is unavailable. Docker Engine and Compose do not replace a container merely because it is unhealthy; a production container platform can use check results to remove and replace malfunctioning containers. section 8.4 section 8.5
Try an ongoing check
For a Node.js app that simulates increasing memory use, wire the supplied `memory-check.js` into its Dockerfile. Check for enough memory at startup, then run an ongoing health check every five seconds to flag the app as unhealthy once its simulated allocation exceeds the allowed amount. section 8.6
