Q: Your development and automated integration test pipelines rely on Docker Compose. Developers frequently experience race conditions where API microservices crash during startup with `connection refused` because the PostgreSQL database container is accepting TCP sockets but has not finished initializing its data directory and schema. Furthermore, unconstrained containers consume 100% host CPU, crashing local test runners. You must modernize the `compose.yaml` file to use Compose v2 healthcheck dependencies, secrets, and CPU/memory constraints.
Master modern Docker Compose v2 specification features: depends_on with condition: service_healthy, compose secrets, named volumes, healthcheck intervals, and resource constraints.
depends_on with condition: service_healthy, compose secrets, named volumes, healthcheck intervals, and resource constraints."
Want to master this scenario in a live sandbox? KodeKloud's Docker Certified Associate (DCA) Hands-On Lab Course covers this exact problem with hands-on terminal drills.
🛠️ Production Runbook & Step-by-Step Resolution
Direct Answer: Master modern Docker Compose v2 specification features: depends_on with condition: service_healthy, compose secrets, named volumes, healthcheck intervals, and resource constraints.
Understand Compose v1 vs Compose v2 Specification Evolution
Docker Compose v2 (written in Go, invoked as docker compose) fully replaces legacy Python-based Compose v1 (docker-compose). It introduces native support for service health dependencies, Compose profiles, and environment file interpolation.
# Compose v1 (Deprecated Anti-pattern):
# depends_on: ["db"] -> Only waits for db container to START, not to be READY!
# Compose v2 (Modern Standard):
# depends_on:
# db:
# condition: service_healthy
Implement Database Healthcheck with Readiness Probe
Define an explicit healthcheck block on the PostgreSQL database service using pg_isready with appropriate interval, timeout, and retries parameters.
services:
postgres:
image: postgres:16-alpine
environment:
POSTGRES_DB: app_db
POSTGRES_USER: app_user
POSTGRES_PASSWORD_FILE: /run/secrets/db_password
secrets:
- db_password
volumes:
- postgres_data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U app_user -d app_db"]
interval: 5s
timeout: 3s
retries: 5
start_period: 10s
deploy:
resources:
limits:
cpus: '1.0'
memory: 1024M
Chain Dependent Services Using condition: service_healthy
Configure dependent API services to wait until the database reports healthy before launching, eliminating connection retry loops and race condition startup crashes.
api-service:
build:
context: .
dockerfile: Dockerfile
ports:
- "8080:8080"
environment:
DB_HOST: postgres
depends_on:
postgres:
condition: service_healthy
redis:
condition: service_started
secrets:
- db_password
deploy:
resources:
limits:
cpus: '0.5'
memory: 512M
secrets:
db_password:
file: ./secrets/db_password.txt
volumes:
postgres_data:
Validate Dependency Order and Startup Timings
Execute docker compose up and observe Compose waiting for the database healthcheck to turn green before initiating the API service container.
# Run compose with detailed status
docker compose up -d
# Inspect service health statuses
docker compose ps
# Displays: 'postgres (healthy)', 'api-service (running)'
depends_on: { service: { condition: service_healthy } }. Combining healthchecks with start_period, resource limits, and secrets creates robust, production-mirroring developer environments."
- W
- e
- e
- l
- i
- m
- i
- n
- a
- t
- e
- d
- f
- l
- a
- k
- i
- n
- e
- s
- s
- i
- n
- o
- u
- r
- l
- o
- c
- a
- l
- d
- e
- v
- e
- l
- o
- p
- m
- e
- n
- t
- a
- n
- d
- C
- I
- p
- i
- p
- e
- l
- i
- n
- e
- s
- b
- y
- u
- p
- g
- r
- a
- d
- i
- n
- g
- t
- o
- C
- o
- m
- p
- o
- s
- e
- v
- 2
- a
- n
- d
- c
- o
- n
- f
- i
- g
- u
- r
- i
- n
- g
- `
- c
- o
- n
- d
- i
- t
- i
- o
- n
- :
- s
- e
- r
- v
- i
- c
- e
- _
- h
- e
- a
- l
- t
- h
- y
- `
- o
- n
- a
- l
- l
- d
- a
- t
- a
- b
- a
- s
- e
- a
- n
- d
- c
- a
- c
- h
- e
- d
- e
- p
- e
- n
- d
- e
- n
- c
- i
- e
- s
- .
- S
- e
- r
- v
- i
- c
- e
- s
- n
- o
- w
- o
- r
- c
- h
- e
- s
- t
- r
- a
- t
- e
- t
- h
- e
- i
- r
- b
- o
- o
- t
- s
- e
- q
- u
- e
- n
- c
- e
- d
- e
- t
- e
- r
- m
- i
- n
- i
- s
- t
- i
- c
- a
- l
- l
- y
- ,
- w
- a
- i
- t
- i
- n
- g
- f
- o
- r
- d
- a
- t
- a
- b
- a
- s
- e
- s
- t
- o
- c
- o
- m
- p
- l
- e
- t
- e
- s
- c
- h
- e
- m
- a
- m
- i
- g
- r
- a
- t
- i
- o
- n
- s
- b
- e
- f
- o
- r
- e
- s
- t
- a
- r
- t
- i
- n
- g
- a
- p
- p
- l
- i
- c
- a
- t
- i
- o
- n
- c
- o
- n
- t
- a
- i
- n
- e
- r
- s
- .
Senior hiring managers and bar raisers evaluate how you prioritize during outages. Avoid these common anti-patterns:
-
Structuring Dockerfile instructions inefficiently by copying app source before package manifests when configuring Orchestrating Microservices Docker
Copying code before package manifests (
package.json,go.mod,requirements.txt) invalidates the build cache on every commit, forcing slow full reinstalls. -
Neglecting the PID 1 process reap problem and omitting proper SIGTERM signal forwarding when configuring Orchestrating Microservices Docker
If an application runs as PID 1 without an init system (like
tini), it fails to reap zombie child processes and ignoresSIGTERMsignals, causing unclean 10s timeouts. - Assembling single-stage images containing compilers, build SDKs, and header files in production when configuring Orchestrating Microservices Docker Single-stage builds bloat image size by gigabytes and expose extensive package vulnerabilities; multi-stage builds isolate artifacts into minimal distroless images.
- Confusing container port forwarding on bridge networks with unisolated host networking mode when configuring Orchestrating Microservices Docker Bridge networking utilizes iptables NAT translations which add latency overhead, whereas host networking bypasses the network namespace entirely.