What are health checks in Docker and how do they work?
Learn what Docker health checks are, how the HEALTHCHECK instruction works with interval, timeout and retries, and how orchestrators use healthy status.
Expected Interview Answer
A Docker health check is a command Docker runs periodically inside a container to test whether the application is actually working, reporting the container as healthy, unhealthy, or starting rather than just running.
You define it with the HEALTHCHECK instruction in a Dockerfile or a healthcheck block in Compose, specifying a test command plus interval, timeout, retries, and an optional start-period. Docker executes the command on the schedule; exit code 0 means healthy and 1 means unhealthy. After the configured number of consecutive failures the status flips to unhealthy. This matters because a process can be 'running' while the app is deadlocked or unable to serve requests, and orchestrators use health status to restart, gate traffic, or hold rollouts.
- Detects apps that are running but not actually serving
- Lets orchestrators restart or replace unhealthy containers
- Gates dependent services until dependencies are ready
- Provides visible status via docker ps and docker inspect
- Improves rollout safety and reduces user-facing downtime
AI Mentor Explanation
A health check is the physio doing a quick fitness test on a fielder between overs — a short sprint and a stretch — rather than just seeing them stand on the field. Standing there is 'running'; passing the fitness test is 'healthy'. Fail it a few times in a row and the twelfth man is sent on as a substitute.
Step-by-Step Explanation
Step 1
Define the test
Add HEALTHCHECK with a CMD that probes real functionality, e.g. curl -f http://localhost:8080/health, exiting 0 for healthy and non-zero for unhealthy.
Step 2
Set timing
Configure --interval (how often), --timeout (max run time), --retries (consecutive failures before unhealthy), and --start-period (grace for slow boot).
Step 3
Docker runs it
Docker executes the command inside the container on schedule and records each result.
Step 4
Status transitions
Container starts as 'starting', becomes 'healthy' on a passing check, or 'unhealthy' after --retries consecutive failures.
Step 5
Consumers react
docker ps shows the status; Compose depends_on: condition: service_healthy and orchestrators use it to gate traffic or restart.
What Interviewer Expects
- Difference between 'running' and 'healthy'
- Knowledge of HEALTHCHECK options: interval, timeout, retries, start-period
- Exit code semantics (0 healthy, 1 unhealthy)
- The starting/healthy/unhealthy status lifecycle
- How orchestrators and Compose use health status
Common Mistakes
- Confusing container 'running' with the app being healthy
- Probing something trivial (like a TCP port) instead of real functionality
- Forgetting --start-period so slow-booting apps flap as unhealthy
- Setting intervals so aggressive they add load or cause false negatives
- Assuming Docker auto-restarts unhealthy containers without a restart policy or orchestrator
Best Answer (HR Friendly)
“A health check is a small test Docker runs inside a container to confirm the app is genuinely working, not just switched on. If the test keeps failing, Docker marks the container unhealthy so the system can restart it or stop sending it traffic.”
Code Example
FROM node:20-alpine
WORKDIR /app
COPY . .
RUN npm ci --omit=dev
# Probe a real endpoint; unhealthy after 3 consecutive failures
HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
CMD wget --spider -q http://localhost:3000/health || exit 1
EXPOSE 3000
CMD ["node", "server.js"]services:
api:
build: .
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
interval: 30s
timeout: 5s
retries: 3
start_period: 20s
worker:
build: ./worker
depends_on:
api:
condition: service_healthyFollow-up Questions
- What do the exit codes 0 and 1 mean for a Docker health check?
- What is the purpose of --start-period and when do you need it?
- Does Docker automatically restart an unhealthy container on its own?
- How does Compose depends_on with service_healthy use the health status?
- How do Kubernetes liveness and readiness probes compare to Docker HEALTHCHECK?
MCQ Practice
1. What exit code from a health check command marks the container healthy?
Exit code 0 means healthy; exit code 1 means unhealthy. Docker only recognises 0 and 1 for health checks.
2. What does the --start-period option control?
start-period gives a slow-booting app time to initialise; failures during it don't mark the container unhealthy.
3. Why is a health check better than checking if a container is 'running'?
A container can be 'running' while its app is hung or unable to serve; a health check verifies actual functionality.
Flash Cards
Docker health check purpose — Verifies the app is actually working, not just that the container process is running.
Health check exit codes — 0 = healthy, 1 = unhealthy.
Key HEALTHCHECK options — --interval, --timeout, --retries, --start-period.
Status lifecycle — starting -> healthy (on pass) or unhealthy (after N consecutive failures).
Compose usage — depends_on: condition: service_healthy gates a service until its dependency is healthy.