Health checks in Compose in Docker - Step-by-Step Execution

Process Flow - Health checks in Compose

Start container

↓

Run health check command

↓

Check command exit code

↓

Mark container

↓

Wait interval

Docker Compose starts the container, runs the health check command repeatedly, and marks the container healthy or unhealthy based on the command's success or failure.

Execution Sample

Docker

services:
  web:
    image: nginx
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost"]
      interval: 10s
      timeout: 5s
      retries: 3

Defines a health check for the 'web' service that tries to curl localhost every 10 seconds, marking unhealthy after 3 failures.

Process Table

Step	Action	Health Check Command Result	Health Status	Retries Count	Next Action
1	Container starts	N/A	starting	0	Run health check command
2	Run health check command	Success (exit 0)	healthy	0	Wait 10 seconds
3	Wait interval	N/A	healthy	0	Run health check command again
4	Run health check command	Failure (exit 1)	healthy	1	Retry health check
5	Run health check command	Failure (exit 1)	healthy	2	Retry health check
6	Run health check command	Failure (exit 1)	unhealthy	3	Mark container unhealthy
7	Stop retries	N/A	unhealthy	3	Stop health checks or alert
8	Container stopped or fixed	N/A	N/A	N/A	End
9	Exit	N/A	N/A	N/A	Retries reached limit, health check failed

💡 Retries reached 3 failures, container marked unhealthy and health checks stop or alert triggers.

Status Tracker

Variable	Start	After Step 2	After Step 4	After Step 5	After Step 6	Final
Health Status	starting	healthy	healthy	healthy	unhealthy	unhealthy
Retries Count	0	0	1	2	3	3

Key Moments - 3 Insights

Why does the health status change to unhealthy after three consecutive failures?

Because the health check command failed consecutively (exit code non-zero) three times at steps 4-6, the retries count reaches 3 and the status changes to unhealthy as shown in the execution_table rows 4-6.

What happens when retries reach the maximum count?

At step 6, retries reach 3 failures, so the container is marked unhealthy and health checks stop or alert triggers, as shown in the exit_note and execution_table row 9.

Does the container become healthy immediately after one success?

Yes, at step 2 the health check command succeeds, so the container is marked healthy immediately with retries reset to zero.

Visual Quiz - 3 Questions

Look at the execution table, what is the health status after the first successful health check command?

A starting

B unhealthy

C healthy

D unknown

💡 Hint

Check execution_table row 2 under 'Health Status' column.

At which step does the retries count reach 3 failures?

A Step 6

B Step 5

C Step 4

D Step 7

💡 Hint

Look at the 'Retries Count' column in execution_table rows 4-7.

If the health check command always succeeds, what will happen to the retries count?

A It will increase continuously

B It will reset to zero after each success

C It will stay at 3

D It will become negative

💡 Hint

Refer to variable_tracker row for 'Retries Count' after step 2.

Concept Snapshot

Health checks in Docker Compose:
- Define under service with 'healthcheck' key
- 'test' runs command to check container health
- 'interval' sets how often to run
- 'retries' is max failures before unhealthy
- Container marked healthy if command succeeds
- Marked unhealthy after retries failures

Full Transcript

Docker Compose health checks run a command inside the container repeatedly to check if it is working well. When the container starts, the health check command runs. If it succeeds (exit code 0), the container is marked healthy. If it fails, retries count increases. After the retries limit is reached, the container is marked unhealthy. This process repeats every interval seconds. The health status helps Docker and users know if the container is ready or needs attention.

Practice

1. What is the main purpose of a health check in a Docker Compose service?

easy

A. To restart the container automatically

B. To verify if the container's application is running correctly

C. To build the container image

D. To expose ports to the host machine

Solution

1. Step 1: Understand health check purpose

   Health checks run commands inside the container to confirm the app is working well.

2. Step 2: Differentiate from other Docker tasks

   Restarting, building, and exposing ports are separate Docker tasks, not health checks.

3. Final Answer:

   To verify if the container's application is running correctly -> Option B

4. Quick Check:

   Health check = verify app status [OK]

Hint: Health checks confirm app health inside containers [OK]

Common Mistakes:

• Confusing health checks with container restart policies
• Thinking health checks build images
• Mixing health checks with port mapping

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

easy

A. healthcheck: { run: "curl http://localhost" }

B. health_check: { command: "curl http://localhost" }

C. healthcheck: { test: ["CMD", "curl", "-f", "http://localhost"] }

D. healthcheck: { check: "curl http://localhost" }

Solution

1. Step 1: Recall Docker Compose healthcheck syntax

   The correct key is 'healthcheck' with a 'test' array specifying the command.

2. Step 2: Validate command format

   The 'test' must be an array starting with 'CMD' followed by the command and arguments.

3. Final Answer:

   healthcheck: { test: ["CMD", "curl", "-f", "http://localhost"] } -> Option C

4. Quick Check:

   Use 'healthcheck' with 'test' array [OK]

Hint: Use 'healthcheck' and 'test' array with CMD for commands [OK]

Common Mistakes:

• Using wrong keys like 'health_check' or 'run'
• Passing command as a string instead of array
• Omitting 'CMD' in the test array

3. Given this Compose snippet, what will be the health status if the curl command fails?

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost"]
  interval: 10s
  retries: 3

medium

A. The container will be marked as unhealthy after 3 failed attempts

B. The container will restart automatically after the first failure

C. The container will ignore the failure and stay healthy

D. The container will stop immediately on failure

Solution

1. Step 1: Understand retries and failure effect

   The health check runs every 10 seconds and allows 3 retries before marking unhealthy.

2. Step 2: Identify container behavior on failure

   Failing the test 3 times marks the container unhealthy; it does not restart or stop automatically.

3. Final Answer:

   The container will be marked as unhealthy after 3 failed attempts -> Option A

4. Quick Check:

   Retries control unhealthy marking, not restart [OK]

Hint: Retries count failures before unhealthy status [OK]

Common Mistakes:

• Assuming container restarts on health check failure
• Thinking container stops immediately on failure
• Ignoring the retries setting

4. You added this health check to your Compose file but it never reports healthy:

healthcheck:
  test: curl -f http://localhost || exit 1
  interval: 5s
  retries: 2

What is the problem?

medium

A. The test command must be an array starting with CMD

B. The interval value must be in milliseconds

C. Retries cannot be less than 3

D. The healthcheck key should be under volumes

Solution

1. Step 1: Check healthcheck test syntax

   Docker Compose requires the test command as an array starting with 'CMD' or 'CMD-SHELL'.

2. Step 2: Identify why string command fails

   Using a plain string without array causes Compose to ignore or fail the health check.

3. Final Answer:

   The test command must be an array starting with CMD -> Option A

4. Quick Check:

   Use array with CMD for test command [OK]

Hint: Healthcheck test must be array with CMD or CMD-SHELL [OK]

Common Mistakes:

• Writing test as plain string instead of array
• Misplacing healthcheck under wrong keys
• Using invalid interval units

5. You want a service in Docker Compose to be considered healthy only if a custom script check.sh inside the container returns success within 5 seconds. Which Compose healthcheck configuration is best?

hard

A. healthcheck:
test: ["CMD-SHELL", "./check.sh"]
interval: 10s
retries: 3

B. healthcheck:
test: ["CMD-SHELL", "timeout 5s ./check.sh"]
interval: 10s
retries: 3

C. healthcheck:
test: ["CMD", "./check.sh"]
interval: 5s
retries: 1

D. healthcheck:
test: ["CMD", "./check.sh"]
timeout: 5s
interval: 10s
retries: 3

Solution

1. Step 1: Understand timeout usage in healthcheck

   The 'timeout' key sets max time for the test command to run; here 5 seconds is needed.

2. Step 2: Choose correct test format and timing

   Using 'CMD' with './check.sh' is valid; 'timeout' controls max duration; interval and retries set frequency and tolerance.

3. Final Answer:

   healthcheck: test: ["CMD", "./check.sh"] timeout: 5s interval: 10s retries: 3 -> Option D

4. Quick Check:

   Use 'timeout' key to limit test duration [OK]

Hint: Use 'timeout' key to limit healthcheck command time [OK]

Common Mistakes:

• Using shell timeout inside test instead of 'timeout' key
• Confusing interval and timeout values
• Omitting retries leading to quick unhealthy status