Add Docker healthchecks

Copy-paste templates for postgres, redis, nginx, mongodb, rabbitmq

Why healthchecks matter

Without a healthcheck, Docker considers a container healthy as soon as it starts — even if the process inside is still initialising. Apps that depends_on: db can crash because they try to connect before postgres is ready to accept connections.

❌ No healthcheck — depends_on condition: service_healthy will fail

services:
  db:
    image: postgres:15
    # No healthcheck — Docker has no way to know when postgres is ready

Healthcheck templates

PostgreSQL

healthcheck:
  test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER:-postgres}"]
  interval: 10s
  timeout: 5s
  retries: 5
  start_period: 10s

MySQL / MariaDB

# MySQL
healthcheck:
  test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
  interval: 10s
  timeout: 5s
  retries: 5
  start_period: 10s

# MariaDB
healthcheck:
  test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
  interval: 10s
  timeout: 5s
  retries: 5
  start_period: 10s

Redis

healthcheck:
  test: ["CMD", "redis-cli", "ping"]
  interval: 10s
  timeout: 3s
  retries: 5
  start_period: 5s

nginx

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

MongoDB

healthcheck:
  test: ["CMD", "mongosh", "--eval", "db.adminCommand('ping')"]
  interval: 10s
  timeout: 5s
  retries: 5
  start_period: 10s

RabbitMQ

healthcheck:
  test: ["CMD", "rabbitmq-diagnostics", "-q", "ping"]
  interval: 10s
  timeout: 5s
  retries: 5
  start_period: 15s

Using healthchecks with depends_on

✅ App waits until postgres is genuinely ready

services:
  app:
    image: myapp
    depends_on:
      db:
        condition: service_healthy
  db:
    image: postgres:15
    environment:
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER:-postgres}"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 10s

Verify healthcheck status

# Check container health status
docker ps
# Look for (healthy) or (unhealthy) in STATUS column

# Inspect health check details
docker inspect --format='{{json .State.Health}}' your_container

# Watch health status in real time
watch docker ps

Auto-inject healthchecks into your compose file

The Docker Auditor detects missing healthchecks and the ⚡ Inject Fixes button generates the correct template for each service by image name.

Open Docker Auditor →

Frequently Asked Questions

What's the difference between interval and start_period?

interval is how often Docker runs the health check once the container is running. start_period is a grace period at startup during which failures don't count — useful for slow-starting services. Use start_period to avoid false unhealthy status during initialisation.

My container shows (unhealthy) — what do I do?

Run docker inspect --format='{{json .State.Health}}' CONTAINER_NAME to see the output of recent health check runs. The Log field shows the exact output and exit code of each check. Common issues: command not found in the image, wrong port, service not ready in time.

Do healthchecks affect performance?

Minimally. A pg_isready check every 10 seconds is negligible overhead. The default interval is 30 seconds if not specified. Avoid heavyweight checks (full query execution) on high-traffic databases — use the built-in readiness commands instead.

ConfigClarity