Lesson 10

Health checks and container readiness

This page covers one of the most important real-world Docker ideas: a container can be running while the application inside it is still not ready.

Main idea

Running means the process started. Healthy means the app is actually responding correctly.

Why it matters

Startup order alone does not guarantee that databases, APIs, or apps are fully ready to accept traffic.

Main warning

depends_on helps startup order, but it does not guarantee service readiness by itself.

Running vs healthy

Running Container process started

Healthy Application responds correctly

Important Running is not always enough

Simple readiness flow

Container starts

Docker runs health check

Pass = healthy

Fail = unhealthy

Dockerfile example

HEALTHCHECK CMD curl --fail http://localhost:3000/health || exit 1

Docker calls a health endpoint and marks the container unhealthy if the check fails.

Compose example

services:
  app:
    build: .
    healthcheck:
      test: ["CMD", "curl", "--fail", "http://localhost:3000/health"]
      interval: 10s
      timeout: 5s
      retries: 3

Health check fields

test defines the command Docker should run.
interval defines how often Docker checks.
timeout defines how long one check may take.
retries defines how many failures happen before the container is marked unhealthy.

Common beginner mistakes

Thinking running means ready.
Relying on depends_on alone.
Using a health check command that is not installed in the container.
Making checks too fast for slow-starting apps.

Why health checks are useful

Apps answer clearly
A `/health` endpoint gives Docker a simple way to verify readiness.

Databases need warm-up time
A service can be running but not ready for connections yet.

Docker gets a better signal
Healthy and unhealthy status is more meaningful than running status alone.

Projects become more reliable
Multi-container setups behave more predictably.

Next page: Lesson 11 explores Docker image optimization so your builds become smaller, cleaner, and faster.