Container health checks in Docker - Commands & Configuration

Introduction

Sometimes a container might start but not work properly. Container health checks help automatically test if a container is working as expected and restart it if needed.

When you want to make sure a web server inside a container is responding to requests.

When a database container should be restarted if it stops accepting connections.

When you run background jobs and want to detect if they hang or crash.

When you deploy multiple containers and want to keep only healthy ones running.

When you want to automate recovery without manual checks.

Config File - Dockerfile

Dockerfile

FROM nginx:1.23.3

HEALTHCHECK --interval=30s --timeout=5s --start-period=5s --retries=3 \
  CMD curl -f http://localhost/ || exit 1

CMD ["nginx", "-g", "daemon off;"]

This Dockerfile uses the official nginx image.

The HEALTHCHECK instruction runs a command every 30 seconds to check if the nginx server responds on localhost.

If the command fails 3 times in a row, Docker marks the container as unhealthy.

The flags control timing: --interval is how often to check, --timeout is how long to wait for a response, --start-period is the initial delay before starting checks, and --retries is how many failures before marking unhealthy.

Commands

Builds the Docker image named 'my-nginx-healthcheck' using the Dockerfile in the current folder.

Terminal

docker build -t my-nginx-healthcheck .

Expected Output

Sending build context to Docker daemon  2.048kB

Step 1/3 : FROM nginx:1.23.3

 ---> 4bb46517cac3

Step 2/3 : HEALTHCHECK --interval=30s --timeout=5s --start-period=5s --retries=3 CMD curl -f http://localhost/ || exit 1

 ---> Running in 7a8f9b2c3d4e

Removing intermediate container 7a8f9b2c3d4e

 ---> 9f1a2b3c4d5e

Step 3/3 : CMD ["nginx", "-g", "daemon off;"]

 ---> Running in 1b2c3d4e5f6a

Removing intermediate container 1b2c3d4e5f6a

 ---> 7e8f9a0b1c2d

Successfully built 7e8f9a0b1c2d

Successfully tagged my-nginx-healthcheck:latest

→

-t - Names and tags the image for easy reference

Runs a container named 'test-nginx' in detached mode from the image we just built.

Terminal

docker run -d --name test-nginx my-nginx-healthcheck

Expected Output

a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef1234567890

→

-d - Runs the container in the background

→

--name - Assigns a custom name to the container

Lists running containers so we can see our 'test-nginx' container is up.

Terminal

docker ps

Expected Output

CONTAINER ID   IMAGE                  COMMAND                  CREATED          STATUS          PORTS     NAMES

a1b2c3d4e5f6   my-nginx-healthcheck   "nginx -g 'daemon off;'"   10 seconds ago   Up 9 seconds              test-nginx

Shows the health status of the 'test-nginx' container in JSON format.

Terminal

docker inspect --format='{{json .State.Health}}' test-nginx

Expected Output

{"Status":"healthy","FailingStreak":0,"Log":[{"Start":"2024-06-01T12:00:00Z","End":"2024-06-01T12:00:05Z","ExitCode":0,"Output":""}]}

Key Concept

If you remember nothing else from this pattern, remember: container health checks let Docker automatically detect and handle unhealthy containers by running simple commands inside them.

Common Mistakes

Not specifying a HEALTHCHECK in the Dockerfile and expecting Docker to know if the container is healthy.

Without a health check, Docker assumes the container is always healthy as long as it is running.

Add a HEALTHCHECK instruction with a command that tests the container's real functionality.

Using a health check command that always succeeds or never fails.

This makes the health check useless because it never detects problems.

Use a command that actually tests the service, like a curl request to a web server.

Setting too short or too long intervals and timeouts for health checks.

Too short intervals can overload the container; too long delays slow down failure detection.

Choose reasonable values like 30 seconds interval and 5 seconds timeout to balance checks.

Summary

Add a HEALTHCHECK instruction in the Dockerfile to define how Docker tests container health.

Build and run the container image with the health check included.

Use 'docker inspect' to see the container's health status and 'docker ps' to confirm it is running.