Health Checks and Dependencies in Docker Compose

The Problem: Startup Order vs. Readiness

By default, docker-compose up starts all services defined in your docker-compose.yml file concurrently. You might think the depends_on directive solves this, and it's a good first step, but it has a crucial limitation.

Let's start by understanding what depends_on does and, more importantly, what it doesn't do.

As the documentation implies, depends_on in its basic form only ensures that the db container is started before the web container. It does not wait for the PostgreSQL process inside the db container to be fully initialized and ready to accept connections.

The following video demonstrates this exact problem and its consequences.

Relying on application-level retry logic is a workaround, not a solution. A much better approach is to make Docker Compose aware of the health of your services.

Defining "Ready" with Health Checks

To solve the readiness problem, we need a way to ask a container, "Are you actually ready for work?" We do this using the healthcheck directive in our docker-compose.yml.

A health check is a command that Docker runs inside your container periodically. If the command returns a successful exit code (0), the container is marked as healthy. If it returns an error code (1), it's marked as unhealthy.

A healthcheck configuration has several key parameters.

To summarize, the main healthcheck options are:

• test: The command to run to check the health. This is the only mandatory option.
• interval: How often to run the check (e.g., 30s).
• timeout: How long to wait for the command to return before considering it failed (e.g., 10s).
• retries: How many consecutive failures are needed to mark the container as unhealthy (e.g., 3).
• start_period: A grace period for the container to start up before the health check failures are counted (e.g., 40s). This is extremely useful for services like databases that can take a while to initialize.

Connecting Dependencies to Health: The condition Keyword

Now that we can define what it means for a service to be healthy, we can tell other services to wait for that healthy state. We do this by expanding the depends_on syntax to include a condition.

This brings us to the modern, robust way of defining service dependencies.

The three main conditions you will use are:

1. service_started: This is the default behavior if you don't specify a condition. The dependent service starts as soon as the dependency container is created.
2. service_healthy: This is what we want for long-running services. The dependent service waits until the dependency's health check passes successfully.
3. service_completed_successfully: This is perfect for one-off tasks that need to run before your main application starts. A classic example is running a database migration script. The dependent service will wait for the migration container to run its command and exit with code 0.

Here is a practical example showing how to wait for a Flask application to become healthy before starting an Nginx reverse proxy.

Verification and Troubleshooting

Once you've configured your health checks, you need to verify they are working. The docker compose ps command will show the health status in the STATUS column.

If a service is stuck in a starting state or becomes unhealthy, here are a few troubleshooting steps:

1. Check the logs: Use docker compose logs <service_name> to see if the application inside the container is throwing any errors.
2. Inspect the health check details: Run docker inspect <container_name> and look for the Health section in the JSON output. It will show you the output of the last few health checks, which is invaluable for debugging a failing test command.
3. Run the command manually: Use docker compose exec <service_name> <health_check_command> to run your test command directly inside the container and see what it outputs.

version: '3.8'

services:
  web:
    build: .
    ports:
      - "8000:8000"
    depends_on:
      - db
      - cache

  db:
    image: postgres:15-alpine
    environment:
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=password
      - POSTGRES_DB=app

  cache:
    image: redis:7-alpine

version: '3.8'

services:
  web:
    build: .
    ports:
      - "8000:8000"
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_healthy

  db:
    image: postgres:15-alpine
    environment:
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=password
      - POSTGRES_DB=app
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U user -d app"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 10s

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

Conclusion

In this lesson, you've learned how to build more resilient multi-service applications by moving beyond simple startup order to true readiness checks.

Key Takeaways:

• The basic depends_on directive only controls the startup order of containers, not their readiness.
• The healthcheck directive allows you to define a specific command to validate that the application within a container is operational.
• Using depends_on with condition: service_healthy is the standard, robust method for ensuring a service waits for its dependencies to be fully ready.
• The condition: service_completed_successfully is a powerful pattern for handling initialization tasks like database migrations.

In our next lesson, we will continue building on our Docker Compose skills by learning how to manage environment-specific configurations using .env files and multiple compose files. This will allow you to easily switch between development, testing, and production setups without changing your core Compose file.