Docker Health Check Configuration for Container Reliability

Overview

The Docker HEALTHCHECK instruction tells Docker how to test whether a container is healthy. Without it, Docker only knows if a container is running, not if the application inside is actually serving requests. Health checks enable orchestrators to restart unhealthy containers automatically.

When to Use

• You run containers in production and need automatic restart on failure
• You use Docker Swarm or Kubernetes and need health status for scheduling
• You want docker ps to show health status (healthy/unhealthy)
• Your app can be running but not responding (deadlocks, memory exhaustion, stuck connections)

Solution

Basic HEALTHCHECK with curl

FROM node:20-alpine

WORKDIR /app

COPY . .
RUN npm ci --omit=dev

HEALTHCHECK --interval=30s --timeout=5s --retries=3 --start-period=10s \
    CMD curl -f http://localhost:3000/health || exit 1

EXPOSE 3000

CMD ["node", "server.js"]

HEALTHCHECK with wget (Alpine images without curl)

FROM node:20-alpine

WORKDIR /app
COPY . .
RUN npm ci --omit=dev

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

EXPOSE 3000
CMD ["node", "server.js"]

HEALTHCHECK with custom script

FROM python:3.12-slim

WORKDIR /app
COPY . .
RUN pip install --no-cache-dir -r requirements.txt

COPY healthcheck.sh /healthcheck.sh
RUN chmod +x /healthcheck.sh

HEALTHCHECK --interval=30s --timeout=10s --retries=3 --start-period=15s \
    CMD /healthcheck.sh

EXPOSE 8000
CMD ["gunicorn", "app:app", "--bind", "0.0.0.0:8000"]

#!/bin/bash
# healthcheck.sh
set -e

# Check if the HTTP endpoint responds
response=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:8000/health)

if [ "$response" = "200" ]; then
    exit 0
else
    echo "Health check failed: HTTP $response"
    exit 1
fi

HEALTHCHECK for PostgreSQL

FROM postgres:16-alpine

HEALTHCHECK --interval=10s --timeout=5s --retries=5 \
    CMD pg_isready -U postgres -d mydb || exit 1

HEALTHCHECK for Redis

FROM redis:7-alpine

HEALTHCHECK --interval=10s --timeout=3s --retries=3 \
    CMD redis-cli ping | grep PONG || exit 1

Docker Compose healthcheck with depends_on

# docker-compose.yml
services:
    api:
        build: .
        ports:
            - "3000:3000"
        healthcheck:
            test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
            interval: 30s
            timeout: 5s
            retries: 3
            start_period: 10s

    worker:
        build: ./worker
        depends_on:
            api:
                condition: service_healthy
            redis:
                condition: service_healthy

    redis:
        image: redis:7-alpine
        healthcheck:
            test: ["CMD", "redis-cli", "ping"]
            interval: 10s
            timeout: 3s
            retries: 3

Health endpoint in Node.js

const http = require("http");

const server = http.createServer((req, res) => {
    if (req.url === "/health" && req.method === "GET") {
        res.writeHead(200, { "Content-Type": "application/json" });
        res.end(JSON.stringify({ status: "healthy" }));
        return;
    }
    // ... other routes
});

server.listen(3000);

Health endpoint in Python (FastAPI)

from fastapi import FastAPI

app = FastAPI()

@app.get("/health")
async def health():
    return {"status": "healthy"}

Explanation

The HEALTHCHECK instruction takes four options:

• --interval: Time between checks (default 30s). Use shorter intervals for critical services.
• --timeout: Max time to wait for a response before marking as failed (default 30s).
• --retries: Consecutive failures before marking unhealthy (default 3).
• --start-period: Grace period before counting failures (default 0s). Gives the app time to boot.

The command must return exit code 0 (healthy) or 1 (unhealthy). Docker runs the command inside the container.

Health states:

• starting: Initial state during start-period. Not counted as failures.
• healthy: Last check returned exit 0.
• unhealthy: retries consecutive checks failed.

In Docker Compose, depends_on with condition: service_healthy waits for a dependency to pass its health check before starting. This solves startup ordering problems.

Variants

Check Method	Image Requirement	Use When
curl -f	curl installed	Standard HTTP check
wget —spider	wget installed	Alpine without curl
Custom script	bash + tools	Multi-step checks
pg_isready	PostgreSQL image	Database readiness
redis-cli ping	Redis image	Cache readiness
node -e	Node.js image	JS-based check

Guidelines

• Always add a HEALTHCHECK to production Dockerfiles.
• Set --start-period to match your app’s startup time (10-30s for most apps).
• Use --interval=30s for general services, 10s for critical infrastructure.
• Keep --timeout short (3-10s). A slow health check is worse than no check.
• Create a dedicated /health endpoint that returns 200 without side effects.
• Check the actual application, not just the port. A TCP open check is not enough.
• Use depends_on with condition: service_healthy in Compose for startup ordering.
• For databases, use built-in tools (pg_isready, redis-cli ping) instead of HTTP.

Common Mistakes

• Not setting --start-period. Slow-starting apps get marked unhealthy before they finish booting.
• Using a health check that hits the database. This adds load and can cause cascading failures.
• Setting --interval too low (1-5s). This wastes CPU and can overload the app with health requests.
• Not creating a dedicated health endpoint. Checking / might return 200 even if the API is broken.
• Forgetting to install curl or wget in the image. The health check silently fails.
• Returning HTTP 200 for error pages. Some frameworks return 200 for all responses, breaking the check.
• Not using depends_on with condition: service_healthy. Containers start before dependencies are ready.

Performance Tips

1. Keep health check commands fast. Target under 1 second execution time:

# Fast: simple HTTP check
curl -sf -m 2 http://localhost:3000/health

# Slow: database query
psql -c "SELECT count(*) FROM large_table"  # Don't do this

2. Use --start-period to avoid false negatives during boot. Set it to your app’s typical startup time plus 50 percent margin:

# App takes ~20s to boot, set start-period to 30s
HEALTHCHECK --start-period=30s --interval=30s --timeout=5s --retries=3 \
    CMD curl -f http://localhost:3000/health

3. Avoid health checks that write to disk. Each check runs frequently and can fill disk with logs:

# Bad: writes to disk every 30s
HEALTHCHECK CMD curl -f http://localhost:3000/health >> /var/log/health.log

# Good: no disk writes
HEALTHCHECK CMD curl -sf http://localhost:3000/health