Day 23intermediateFeb 23, 2026

Add Health Checks to Your Dockerfiles

A running container isn't necessarily a healthy container — health checks let Docker tell the difference.

dockermonitoringreliability

What

The HEALTHCHECK instruction tells Docker how to test whether a container is still working correctly. Docker periodically runs the specified command inside the container and marks it as healthy, unhealthy, or starting based on the exit code. Orchestrators like Docker Swarm use this to automatically restart unhealthy containers.

Why It Matters

Without health checks, Docker only knows if your process is running, not if it's actually serving requests. A container can be up but deadlocked, out of memory, or returning errors. Health checks give you automatic detection and recovery from these silent failures.

Example

# Basic health check for a web server
FROM nginx:alpine
COPY . /usr/share/nginx/html

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

# Health check for a Node.js API
HEALTHCHECK --interval=15s --timeout=3s --retries=3 \
  CMD node -e "require('http').get('http://localhost:3000/health', (r) => { process.exit(r.statusCode === 200 ? 0 : 1) })"

# Check container health status
# docker inspect --format='{{.State.Health.Status}}' my-container

dockerfile

Common Mistake

Not setting appropriate --start-period, --interval, and --timeout values. Too aggressive intervals waste resources, while too lenient settings delay failure detection. Skipping --start-period causes false unhealthy reports during container startup.

Quick Fix

Start with --interval=30s --timeout=5s --start-period=10s --retries=3 as sensible defaults. Adjust --start-period based on your app's actual startup time, and use a lightweight check like curl -f or wget -q.