Docker Health Check Instruction

One of the new features in Docker 1.12 is how health check for a container can be baked into the image definition. Just like the CMD instruction, there can be multiple HEALTHCHECK instructions in Dockerfile but it takes only the last one.  Docker’s health check instruction supplies important additional information for running containers in complex enviornments. While the “docker ps” command makes it easy to determine if a container is running,  health check instructions lets you specify a command in a Dockerfile for a container-specific way to determine readiness.

Check the output of “docker ps” command


You can see that there is an additional flag “healthy” under STATUS .

Is your container Healthy?

Apart from processing exit codes, Docker, by design, doesn’t know much about the internal workings of containerized applications. When “docker run” is invoked from the command-line interface , it often starts a single process specified using the CMD instruction in a Dockerfile. That determines the result of the “STATUS” column in the docker CLI with the ps command. The -a flag lists all containers, running or not, as shown here:



This output indicates that some containers are actively running while others have exited, either successfully or with an error (“Exited (1)”). Unfortunately, even applications that show a status of “Up About a minute” may serve 500 errors or could be stuck in an infinite loop, it is bad . Adding HEALTHCHECK to the container Dockerfile helps address this issue.

Adding Healthchecks to Docker Containers

To define docker healthcheck in a simple way, docker healthcheck can be any single command which run inside the container and if the command exit code is 0, the container is reported as healthy, and if the output is 1, the container is marked as unhealthy. For example, common verification for web-facing application containers checks the HTTP status code from an app running in a container . This can be done using curl with –fail option. this command can return a status code 1 if any HTTP error code is returned from the service

Here is a simple docker healthcheck command to check the status of nginx webserver which listen on port number 80

HEALTHCHECK CMD curl –fail http://localhost:80/ || exit 1

As you can see, if the http status code is 200 exit code will be 0 and container will be marked as health. If server responds with any error, exit code will be 1 and container is unhealthy. A simple Dockerfile with the above healthcheck




health check can have following options

  • --interval=DURATION (default 30s)
  • --timeout=DURATION (default 30s)
  • --retries=N (default 3)


If the container was started and nginx started listening on port 80 inside container ,  you will see the flag “healthy” under the container status


Health checks take time to complete. When a health check is executing for the first time, the status is shown as “starting” , 


If the healthcheck fails, status will be “unhealthy”


Any health changes trigger a Docker event (heath_status) so you can react to changes without resorting to polling the Docker engine .
Although this feature is new, it promises to help developers build more resilient software in a variety of scenarios: example in load balancing where traffic should not be routed to a container which is marked unhealthy

Leave a Reply

Your email address will not be published. Required fields are marked *