How to Wait for Container X Before Starting Y
The healthcheck property was originally introduced in the 2.1 Compose file format and is now part of the Compose Specification used by recent versions of Docker Compose. This allows a check to be configured in order to determine whether or not containers for a service are “healthy.”
How can I wait for container X before starting Y?
This is a common problem and in earlier versions of docker-compose requires the use of additional tools and scripts such as wait-for-it and dockerize.
healthcheck parameter the use of these additional tools and scripts is often no longer necessary.
Waiting for PostgreSQL to be “healthy”
A particularly common use case is a service that depends on a database, such as PostgreSQL. We can configure docker-compose to wait for the PostgreSQL container to startup and be ready to accept requests before continuing.
The following healthcheck has been configured to periodically check if PostgreSQL is ready using the
pg_isready command. See the documentation for the
pg_isready command here.
healthcheck: test: ["CMD-SHELL", "pg_isready -U postgres"] interval: 10s timeout: 5s retries: 5
If the check is successful the container will be marked as
healthy. Until then it will remain in an
For more details about the healthcheck parameters
retries see the documentation here.
Services that depend on PostgreSQL can then be configured with the
depends_on parameter as follows:
depends_on: postgres-database: condition: service_healthy
Waiting for PostgreSQL before starting Kong
In this complete example docker-compose waits for the PostgreSQL service to be “healthy” before starting Kong, an open-source API gateway. It also waits for an additional ephemeral container to complete Kong’s database migration process.
version: '3.9' # optional since Compose v1.27.0 services: kong-database: image: postgres:9.5 container_name: kong-postgres environment: - POSTGRES_USER=kong - POSTGRES_DB=kong - POSTGRES_HOST_AUTH_METHOD=trust healthcheck: test: ["CMD-SHELL", "pg_isready -U postgres"] interval: 10s timeout: 5s retries: 5 kong-migration: image: kong container_name: kong-migration depends_on: kong-database: condition: service_healthy environment: - KONG_DATABASE=postgres - KONG_PG_HOST=kong-database command: kong migrations bootstrap kong: image: kong container_name: kong restart: always depends_on: kong-database: condition: service_healthy kong-migration: condition: service_started links: - kong-database:kong-database ports: - 8000:8000 - 8443:8443 - 8001:8001 - 8444:8444 environment: - KONG_DATABASE=postgres - KONG_PG_HOST=kong-database - KONG_PG_DATABASE=kong - KONG_ADMIN_LISTEN=0.0.0.0:8001
Test it out with:
docker-compose up -d
Wait until all services are running:
Test by querying Kong’s admin endpoint:
Sample code can be found at https://github.com/peter-evans/docker-compose-healthcheck