Maciej Walkowiak

Docker Compose - waiting until containers are ready

Russia has invaded Ukraine and already killed tens of thousands of civilians, with many more raped and tortured. Ukraine needs your help!

Help Ukraine Now!

Docker Compose since version 2.1.1 has a new flag for the detached mode - --wait.

Running docker-compose -d --wait waits until containers are healthy and only then exits (containers of course still run in the background).

To make it work, it has to be defined what does healthy mean - each container the command is meant to wait for must have defined healthcheck entry in docker-compose.yml.

For example, we can verify that Postgres & MySQL is ready to accept connections with following configuration:

    image: postgres:13.3
      - POSTGRES_USER=test
      - POSTGRES_DB=test
      test: ["CMD", "pg_isready"]
      interval: 3s
      timeout: 5s
      retries: 5

Healthcheck configuration

Let's break down the healthcheck configuration options:

  • test - is a command to run - if it returns 0 - container is healthy, 1 - unhealthy
  • interval - time to wait before first test is made and then between further test invocations
  • timeout - time to wait until test command returns
  • retries - the number of retries to run test until we give up
  • start_period - assumed time that containers need to start and become healthy - if test returns 1 during this time, it is not counted against the number of retries

Here are test commands for some popular containers that I often use:

  • Postgres: [ "CMD", "pg_isready" ]
  • MySQL: [ "CMD", "mysqladmin" ,"ping", "-h", "localhost" ]
  • Redis: [ "CMD", "redis-cli", "--raw", "incr", "ping" ]
  • RabbitMQ: rabbitmq-diagnostics -q ping


And that's how it looks in action:

docker-compose up -d --wait

It is useful especially for chaining commands, for example - start services with Docker Compose and once they are ready, run application:

$ docker-compose up -d --wait && ./mvnw spring-boot:run