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.

Practice

1. What is the main purpose of a HEALTHCHECK in a Docker container?

easy

A. To restart the Docker daemon automatically

B. To update the container's image

C. To check if the container's application is running correctly

D. To increase the container's CPU usage

Solution

1. Step 1: Understand the role of HEALTHCHECK

   The HEALTHCHECK instruction runs a command inside the container to verify if the app is working properly.

2. Step 2: Identify what HEALTHCHECK does not do

   It does not restart Docker daemon, update images, or increase CPU usage.

3. Final Answer:

   To check if the container's application is running correctly -> Option C

4. Quick Check:

   HEALTHCHECK verifies app status = B [OK]

Hint: HEALTHCHECK tests app inside container, not Docker itself [OK]

Common Mistakes:

• Confusing HEALTHCHECK with Docker daemon restart
• Thinking HEALTHCHECK updates images
• Assuming HEALTHCHECK changes resource usage

2. Which of the following is the correct syntax to add a health check in a Dockerfile?

easy

A. HEALTHCHECK CMD curl -f http://localhost/ || exit 1

B. HEALTHCHECK RUN curl -f http://localhost/ || exit 1

C. HEALTHCHECK EXEC curl -f http://localhost/ || exit 1

D. HEALTHCHECK CHECK curl -f http://localhost/ || exit 1

Solution

1. Step 1: Recall Dockerfile HEALTHCHECK syntax

   The correct syntax uses HEALTHCHECK CMD followed by the command to run.

2. Step 2: Identify incorrect keywords

   RUN, EXEC, CHECK are not valid keywords for HEALTHCHECK instruction.

3. Final Answer:

   HEALTHCHECK CMD curl -f http://localhost/ || exit 1 -> Option A

4. Quick Check:

   HEALTHCHECK uses CMD keyword = C [OK]

Hint: HEALTHCHECK always uses CMD keyword in Dockerfile [OK]

Common Mistakes:

• Using RUN instead of CMD in HEALTHCHECK
• Using EXEC or CHECK which are invalid
• Omitting CMD keyword entirely

3. Given this Dockerfile snippet:

HEALTHCHECK CMD curl -f http://localhost/health || exit 1
CMD ["./start-server.sh"]

What will be the health status if curl fails?

medium

A. unhealthy

B. unknown

C. starting

D. healthy

Solution

1. Step 1: Understand HEALTHCHECK command behavior

   If the command returns a non-zero exit code (like exit 1), Docker marks the container as unhealthy.

2. Step 2: Analyze the curl failure effect

   Since curl -f fails, it triggers exit 1, so health status becomes unhealthy.

3. Final Answer:

   unhealthy -> Option A

4. Quick Check:

   Failed HEALTHCHECK command = unhealthy [OK]

Hint: Failed health check command sets status to unhealthy [OK]

Common Mistakes:

• Assuming failure means healthy
• Confusing 'starting' with unhealthy
• Thinking status stays unknown on failure

4. You wrote this in your Dockerfile:

HEALTHCHECK CMD curl http://localhost/health || exit 1

But your container health status is always starting. What is the likely problem?

medium

A. The container has no network access

B. The HEALTHCHECK syntax is invalid

C. Docker daemon is not running

D. The health check command never succeeds within the start period

Solution

1. Step 1: Understand 'starting' health status meaning

   'starting' means the container is still within the initial grace period before health checks are considered final.

2. Step 2: Analyze why health check stays 'starting'

   If the command never succeeds during this period, Docker keeps status as 'starting'. Syntax is correct, Docker daemon running, and network likely accessible.

3. Final Answer:

   The health check command never succeeds within the start period -> Option D

4. Quick Check:

   Failing health check in start period = starting [OK]

Hint: Starting means health check not yet passed in grace period [OK]

Common Mistakes:

• Assuming syntax error causes 'starting' status
• Blaming Docker daemon when it runs fine
• Ignoring network issues but they are less likely here

5. You want to create a health check that retries 3 times before marking unhealthy and waits 10 seconds between checks. Which Dockerfile snippet correctly sets this up?

hard

A. HEALTHCHECK --timeout=10s --retries=3 CMD curl -f http://localhost/health || exit 1

B. HEALTHCHECK --interval=10s --retries=3 CMD curl -f http://localhost/health || exit 1

C. HEALTHCHECK --interval=3s --retries=10 CMD curl -f http://localhost/health || exit 1

D. HEALTHCHECK --start-period=10s --retries=3 CMD curl -f http://localhost/health || exit 1

Solution

1. Step 1: Identify correct flags for interval and retries

   --interval sets wait time between checks; --retries sets how many failures before unhealthy.

2. Step 2: Match values to requirements

   We want 10 seconds between checks and 3 retries, so --interval=10s --retries=3 is correct. Timeout and start-period are different settings.

3. Final Answer:

   HEALTHCHECK --interval=10s --retries=3 CMD curl -f http://localhost/health || exit 1 -> Option B

4. Quick Check:

   Interval=10s and retries=3 flags = A [OK]

Hint: Use --interval for wait, --retries for failure count [OK]

Common Mistakes:

• Confusing timeout with interval
• Swapping retries and interval values
• Using start-period instead of interval