How to Configure Docker Health Checks

In this tutorial, you'll learn about How to Configure Docker Health Checks. We cover key concepts, practical examples, and best practices.

The Problem

Your Docker container is running but the application inside is broken. Docker reports the container as Up even though the service is not responding. Without health checks, you cannot detect or restart unhealthy containers automatically.

Quick Fix

Step 1: Add a HEALTHCHECK to the Dockerfile

Define a health check that tests the service endpoint:

FROM node:18-alpine

HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1

COPY . /app
CMD ["node", "server.js"]

Step 2: Check container health status

View the health status of running containers:

docker ps

CONTAINER ID   IMAGE     STATUS                            NAMES
a1b2c3d4e5f6   my-app    Up 2 minutes (healthy)            app_container

An unhealthy container shows (unhealthy) instead.

Step 3: Add health check in docker-compose.yml

Define health checks per service without modifying the Dockerfile:

services:
  app:
    image: my-app:latest
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s

Step 4: Add dependency on health

Make one service wait for another to be healthy:

services:
  app:
    image: my-app:latest
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:15
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5

Step 5: Inspect health check logs

View the last health check output:

docker inspect --format='{{json .State.Health}}' app_container

{"Status":"healthy","FailingStreak":0,"Log":[{"Start":"2026-06-24T10:00:00Z","Output":"HTTP/1.1 200 OK"}]}

Alternative Solutions

Use a health check script for complex checks

Run a multi-step health check in a shell script:

#!/bin/sh
curl -f http://localhost:3000/health || exit 1
curl -f http://localhost:3000/db-check || exit 1

Set restart policies for unhealthy containers

Auto-restart when health checks fail:

deploy:
  restart_policy:
    condition: any
    delay: 5s
    max_attempts: 3

Common Mistakes to Avoid

Setting an interval that is too short. Checking every 5 seconds adds unnecessary load. Use 30 seconds for most services.

Forgetting start_period for slow-starting services. A database server may need 10-15 seconds to start. Without start_period, health checks fail prematurely.

Using curl without -f. Without -f, curl exits with 0 even for 404 responses. Always use curl -f to check for HTTP success.

Pro Tips

Use --interval with --timeout shorter than --interval. The timeout must be less than the interval to prevent overlapping health checks.

Use docker inspect to check health history. View the last 5 health check results with docker inspect --format='{{json .State.Health}}' container.

Use HEALTHCHECK NONE to disable inherited checks. In a child Dockerfile, HEALTHCHECK NONE removes a health check from the parent image.

Use docker events to monitor health status changes. Stream Docker events to see when containers become unhealthy: docker events --filter 'event=health_status' --format '{{json .}}'.

Prevention

• Always add a HEALTHCHECK to production containers.
• Use start_period to give slow-starting services time to initialize.
• Set restart: unless-stopped in docker-compose.yml so unhealthy containers restart automatically.