Docker Compose Health Checks: Ensuring Service Reliability

Health checks are crucial for maintaining reliable containerized applications. This guide covers various health check strategies in Docker Compose.

Basic Health Check Configuration

services:
  web:
    image: nginx:alpine
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

  api:
    image: node:alpine
    healthcheck:
      test: ["CMD-SHELL", "curl -f http://localhost:3000/health || exit 1"]
      interval: 1m
      timeout: 10s
      retries: 3
      start_period: 1m

Health Check Types

1. Command-based Checks

   healthcheck:
     test: ["CMD", "pg_isready", "-U", "postgres"]
     interval: 10s
     timeout: 5s
     start_period: 30s
   

2. Shell-based Checks

   healthcheck:
     test: ["CMD-SHELL", "curl -f http://localhost/health || exit 1"]
     interval: 30s
     start_period: 40s
   

3. Disabled Checks

   healthcheck:
     disable: true
   

Docker Compose 3.x Features

1. Extended Health Check Syntax

   healthcheck:
     test: ["CMD", "curl", "-f", "http://localhost/health"]
     interval: 30s
     timeout: 10s
     retries: 3
     start_period: 40s
     start_interval: 5s
   

2. Conditional Health Checks

   healthcheck:
     test: ${HEALTH_CHECK_TEST:-["CMD", "curl", "-f", "http://localhost"]}
     interval: ${HEALTH_CHECK_INTERVAL:-30s}
   

3. Custom Health Check Scripts

   healthcheck:
     test: ["CMD", "/healthcheck.sh"]
     interval: 1m
     timeout: 10s
     retries: 3
     start_period: 1m
   

Common Health Check Patterns

1. Database Health Check

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

2. Web Application Check

services:
  web:
    image: nginx:alpine
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost"]
      interval: 30s
      start_period: 40s

3. Custom Script Check

services:
  app:
    image: myapp
    healthcheck:
      test: ["CMD", "/healthcheck.sh"]
      interval: 1m
      timeout: 10s
      retries: 3
      start_period: 1m

Docker Swarm Mode Considerations

1. Service Health Monitoring

   services:
     app:
       deploy:
         update_config:
           order: start-first
         restart_policy:
           condition: on-failure
       healthcheck:
         test: ["CMD", "curl", "-f", "http://localhost/health"]
   

2. Rolling Updates

   services:
     app:
       deploy:
         update_config:
           parallelism: 1
           delay: 10s
           failure_action: rollback
       healthcheck:
         test: ["CMD", "curl", "-f", "http://localhost/health"]
   

3. Service Dependencies

   services:
     app:
       depends_on:
         db:
           condition: service_healthy
       healthcheck:
         test: ["CMD", "curl", "-f", "http://localhost/health"]
   

Best Practices

1. Configuration
   • Set appropriate intervals
   • Define reasonable timeouts
   • Configure sufficient retries
   • Use appropriate start_period
2. Implementation
   • Use lightweight checks
   • Avoid resource-intensive tests
   • Implement graceful degradation
3. Monitoring
   • Log health check results
   • Set up alerts
   • Track historical data

Advanced Health Check Features

1. Dependent Services

services:
  app:
    depends_on:
      db:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]

2. Custom Health Endpoints

services:
  api:
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health?detailed=true"]

3. Composite Checks

services:
  app:
    healthcheck:
      test: ["CMD-SHELL", "check-db.sh && check-cache.sh"]

Troubleshooting

1. Check Status

   # View container health status
   docker compose ps
   

2. Inspect Logs

   # Check health check logs
   docker compose logs --tail=100
   

3. Manual Testing

   # Test health check command
   docker compose exec service_name healthcheck-command
   

Integration with Orchestration

1. Docker Swarm
   • Service health monitoring
   • Automatic container replacement
   • Rolling updates
2. Kubernetes
   • Liveness probes
   • Readiness probes
   • Startup probes
3. Custom Solutions
   • External monitoring
   • Alert systems
   • Automated recovery

Remember to regularly review and update your health check configurations as your application evolves.