You are currently viewing Docker Healthcheck: Everything You Need to Know

Docker Healthcheck: Everything You Need to Know

Docker is a fantastic tool for managing containers, but what if you could make sure your containers stay healthy automatically? That’s where the Docker Healthcheck comes in. 

Docker Healthcheck is like a checkup for containers. It’s a way to ensure they are healthy and working as they should. Just as you go to the doctor for a regular health check, Docker Healthcheck ensures your containers are in good shape and helps catch any issues early on.

To run the docker smoothly on your system and get better performance, you must check its health on a regular basis. Regular healthcheck will help to boost its performance and resolve other issues as well. If you want the best solution to resolve docker errors and issues, then you’re at the right place. 
With this easy guide, we’ll show you what is the Docker Healthcheck and why it’s essential. We’ve made numerous detailed guides for the docker so that you can solve any issues easily. This blog is a part of our Docker consulting services and we’ve tried to cover everything about Docker Healthcheck. Go through this guide to get a better understanding.

What is the Docker Healthcheck?

The Docker Healthcheck is a feature in Docker that allows you to define health checks for your containers. It allows you to specify a command or a script that Docker will periodically run to determine if the container is healthy. This is essential for applications that need to ensure continuous operation and reliability. These health checks help you monitor the status and performance of your containerized applications automatically. 

By using the Healthcheck Command, you can specify a command or script that Docker will run at regular intervals to determine if the container is functioning as expected. If the health check command fails, Docker can take action based on your defined criteria, such as marking the container as unhealthy or initiating a self-healing process.

It’s a way to ensure that your Docker containers are always in good shape by regularly checking their vital signs. If anything goes wrong, Docker can respond accordingly to keep your applications healthy and running smoothly.

Why Use Docker HealthCheck?

We should do Healthchecks regularly and they are vital for several reasons:

Automatic Monitoring: Health checks enable Docker to automatically monitor the container’s status, reducing the need for manual intervention.

Service Discovery: Containers with health checks can be used in orchestration tools like Docker Compose or Kubernetes to facilitate service discovery and load balancing.

Self-Healing: Containers that fail health checks can be automatically replaced, ensuring that your application remains resilient.

Efficient Resource Usage: Containers that are failing health checks don’t consume resources unnecessarily.

Setting Up a Docker HealthCheck

To set up a healthcheck, you need to use the HEALTHCHECK command in your Dockerfile. It’s like telling Docker what to check. Here’s a simple example:

FROM myapp
HEALTHCHECK CMD curl --fail http://localhost:8080/ || exit 1

In this example, it’s saying, “Check if my container is healthy by running curl to see if a web server is working. If it fails, consider the container unhealthy.”

Parameters for Docker Health Check

You can customize your health check with options like:

  • –interval: How often should Docker check? You can say something like every 10 seconds (10s).
  • –timeout: How long should Docker wait for a response from the health check? You might set it to 5 seconds (5s).
  • –start-period: It’s like a waiting time before the first check. Maybe 20 seconds (20s) is good for you.
  • –retries: How many times should Docker try before declaring the container unhealthy? You can set it to a number, like 3.

To execute a Docker health check, you need to specify the interval option, which determines the time interval in seconds between each execution. In addition, we will determine how often you should have regular health checks.

The timeout option determines how long Docker healthchecks will wait for an exit code to be returned. If it takes longer than the specified timeout, the health check will be considered failed, and as a result, your container will be marked as unhealthy.

If you want to control the duration for which your container needs to bootstrap, you can use the start-period option. If the exit code of the Docker health check is greater than zero, the container will not be considered unhealthy. However, if the exit code is 0, it will be considered healthy.

The retries option determines how many simultaneous failures at the docker health check are needed for a container to be marked as unhealthy.

Check Out: Our Blog Post On docker rootless

Executing a Docker healthcheck

A docker health check is a way to determine if a container’s workload is accessible. It doesn’t matter if Docker containers are running or not.

Even if your Docker container is still running, your API server will not be able to process requests if your database stops working. When troubleshooting, it can often result in disappointing experiences.

You can easily check if the docker container is available by running the command “docker ps”. When you include a docker health check, the output of docker ps will show the current state of the container.

Dockerfiles are set up to carry out health checks for Docker containers. The Docker daemon will execute this command 30 seconds after it receives it. Docker health check uses the command’s exit code to determine if your container is healthy:

0 – A container that is functional and in good health.

1 – Workloads could not be working, and containers are unhealthy.

2 – The status code is reserved by Docker and should not be used.

When you use the HEALTHCHECK command in your Dockerfile, the healthiness of a container can be seen in the STATUS column when you run the “docker ps” command.

When a docker container is built, its health is not checked right away. The status will show as “starting” until the first check has been completed.

During this period, the docker container has the ability to execute any necessary startup tasks. When a container successfully passes a Docker health check, it will be marked as healthy. However, if it fails the health check, it will be considered unhealthy.

Using Nginx as a sample

Here’s an example illustrating the functioning of a Docker health check with the Nginx web service. To set up a simple website, you’ll need the following three required files:

An index.html:

// index.html

        <title> Welcome </title>
        <div style="text-align: center; margin-top: 80px;">
            <h2> Docker Health Check </h2>
            <p> A Docker health check is a command that verifies a container's well-being, ensuring it operates as intended and aids in problem prevention or diagnosis.

A Dockerfile:

FROM nginx
COPY index.html /usr/share/nginx/html/index.html

A docker-compose.yml:

version: '3.4'
    image: very-simple-web
      context: ./
      dockerfile: Dockerfile
      - ""
    restart: unless-stopped

Now, the service will be created in the following manner:

docker-compose up -d --build
docker healthcheck

You can see output by going to localhost:8000.

Running Health Checks using Docker HealthCheck command

When you run a container, you can tell Docker to do health checks using the –health-cmd, –health-interval, –health-retries, and –health-timeout options:

docker run --health-cmd="curl --fail http:/localhost:8080/ || exit 1"--health-interval=10s
--health-retries=3 --health-timeout=5s myapp

This tells Docker that whenever it runs this container, it must check the state of the container’s health every 10 seconds. If you can’t check within 5 seconds, try 3 times before giving up.”

Checking Container Health

To see if a container is healthy, you can use the docker inspect command. Do check out for the “Status” field in the output or result. It will tell you if the container is healthy or not.

Docker HealthCheck Example

To set up the healthcheck in a Docker container, you’ll need to use the HEALTHCHECK command in the Dockerfile.

There are two ways you can configure the HEALTHCHECK in Docker. There are:  


which checks the current state of the application within the container by executing the specified command. In this guide, we’ll be using curl to perform a health check. This involves sending a ping to the server and receiving a response. Alternatively, there is another option:


In this guide, we will be using the former method to set up health checks for the container. If you pay close attention, you’ll notice that there is a method to include additional options in the health check command. We’ll discuss the customization qualities in Health Check later on.

So, here is a docker healthcheck example to implement a Health Check in a Docker container. To do this, you’ll need to add a HEALTHCHECK instruction to your Dockerfile.

Docker Healthcheck Everything You Need to Know

The curl command is used to check if the application is running by sending a request to localhost:3000. If the request is successful and returns a status code of 200, the exit code will be 0. However, if the application crashes, the exit code will be 1. Docker’s HEALTHCHECK uses these exit codes to determine the health of the container. Based on that, we can see the current status of the application in the container.

Docker Healthcheck Everything You Need to Know

At first, it will take a little while to begin the health check and update process to determine if the application is in good health or not.

Docker Healthcheck Everything You Need to Know

If the application crashes or exits, it will be marked as unhealthy. To check the status, you can use the command “docker ps”.

Docker Healthcheck Everything You Need to Know

Read more: Our Blog Post On docker restart policy


With this blog, we guided you about Docker Healthcheck command and we tried to cover all the important aspects. The Docker Healthcheck command is a valuable feature for enhancing the reliability and stability of your containerized applications. By defining health checks, you can automate monitoring, ensure timely responses to issues, and create a self-healing container environment. Incorporating health checks into your Docker containers is a best practice for building resilient and efficient containerized applications.

Docker Healthcheck command is like a doctor’s appointment for your containers. It makes sure they’re doing fine, and if not, it lets Docker know. This way, your applications can keep running smoothly without surprises. So, if you want your containers to stay in top shape, consider using Healthcheck – it’s a smart move for container health.

Frequently asked questions (FAQ)

Q1. What Does Docker Healthcheck command Do?

Ans: Docker Healthcheck command is a feature that allows you to set up checks to monitor the status and health of your Docker containers. It runs a specified command or script at defined intervals to determine if the container is functioning properly. If the health check fails, Docker can take actions like marking the container as unhealthy, initiating self-healing, or triggering alerts.

Q2. How to Check the Status of a Docker Container?

Ans: To check the status of a Docker container, you can use the docker ps command. This command will list all the running containers, along with their status. The STATUS column in the output will indicate if the container is healthy or not. Additionally, you can use the docker inspect command followed by the container’s name or ID to get more detailed information, including the health status.

Q3. How to Disable Healthcheck in Docker?

Ans: You can disable health checks in Docker by either not defining a health check in your Dockerfile or by specifying a health check that always returns a healthy status. For example, you can use the HEALTHCHECK NONE instruction in your Dockerfile, which effectively disables health checks. However, it’s generally recommended to keep health checks enabled for better container monitoring and management.

Q4. What Is the Interval for Docker Healthcheck?

Ans: The interval for docker healthcheck can be specified using the –interval option when defining a health check. This option allows you to set the time between health checks. You can specify the interval in seconds (for example, 10s for 10 seconds) or other time units. The interval determines how often Docker runs the health check command to monitor the container’s health.