Docker Healthcheck

You are a Docker operations engineer. The user wants to add health checks to Docker containers to monitor application status and enable automatic restart on failure.

What to check first

• Run docker --version to confirm Docker is installed
• Verify your application has an endpoint or script that can determine health status (HTTP endpoint, script exit code, etc.)

Steps

1. Identify your health check mechanism—either an HTTP endpoint (e.g., http://localhost:8080/health), a shell command (e.g., curl localhost:8080/health), or a custom script that returns exit code 0 for healthy
2. In your Dockerfile, add a HEALTHCHECK instruction with --interval (check frequency), --timeout (max time to wait), and --retries (failures before unhealthy)
3. Set the CMD parameter to the actual command—wrap HTTP checks with curl or wget, or use your custom script
4. Build the image with docker build -t myapp:latest .
5. When running the container with docker run, Docker will automatically start health checks after the container begins
6. Monitor health status with docker ps (shows (healthy), (unhealthy), or (starting) next to the container name)
7. Check detailed health history with docker inspect --format='{{.State.Health}}' <container_id>
8. For compose stacks, add healthcheck block under each service with test, interval, timeout, and retries keys

Code

# Dockerfile with HEALTHCHECK
FROM node:18-alpine

WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .

EXPOSE 3000

# Install curl for health check command
RUN apk add --no-cache curl

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

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

# docker-compose.yml with healthcheck
version: '3.8'
services:
  web:
    build: .
    ports:
      - "3000:3000"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 5s
    restart: unless-stopped

  db:
    image: postgres:15
    environment:
      POSTGRES_DB: myapp
      POSTGRES_PASSWORD: secret
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5
    volumes:
      - db_data:/var/lib/postgresql/data

volumes:
  db_data:

Note: this example was truncated in the source. See the GitHub repo for the latest full version.

Common Pitfalls

• Treating this skill as a one-shot solution — most workflows need iteration and verification
• Skipping the verification steps — you don't know it worked until you measure
• Applying this skill without understanding the underlying problem — read the related docs first

When NOT to Use This Skill

• When a simpler manual approach would take less than 10 minutes
• On critical production systems without testing in staging first
• When you don't have permission or authorization to make these changes

How to Verify It Worked

• Run the verification steps documented above
• Compare the output against your expected baseline
• Check logs for any warnings or errors — silent failures are the worst kind

Production Considerations

• Test in staging before deploying to production
• Have a rollback plan — every change should be reversible
• Monitor the affected systems for at least 24 hours after the change