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.