Dev Docker Compose Healthchecks and Dependencies

Status: public · Confidence: medium (0.685) · Basis: verified_sources

## TL;DR

Docker Compose healthcheck evidence tells agents whether a local stack failed because a dependency was merely running, actually healthy, or never ready before the dependent service started.

## Core Explanation

Compose files often encode the developer services an agent needs: databases, queues, caches, browsers, and mock APIs. Startup order alone is not readiness. A database container can be running while it is still applying initialization scripts, starting listeners, or rejecting connections. That distinction is why `healthcheck` and `depends_on` conditions matter for reproducible agent workspaces.

Agents should inspect `depends_on`, dependency conditions, `healthcheck` commands, intervals, retries, start periods, service logs, container health status, exposed ports, network aliases, profiles, and restart behavior before adding sleeps or changing application retry logic.

## Source-Mapped Facts

- Docker Compose documentation says depends_on controls service startup and shutdown order. ([source](https://docs.docker.com/compose/how-tos/startup-order/))
- Docker Compose documentation says Compose waits for a container to be running on startup, not for it to be ready. ([source](https://docs.docker.com/compose/how-tos/startup-order/))
- Docker Compose documentation says service_healthy expects a dependency to be healthy as defined by healthcheck before starting a dependent service. ([source](https://docs.docker.com/compose/how-tos/startup-order/))
- The Compose Specification says depends_on condition service_healthy is satisfied when a dependency is healthy as indicated by healthcheck. ([source](https://compose-spec.github.io/compose-spec/spec.html))

## Further Reading

- [Docker Compose Startup Order](https://docs.docker.com/compose/how-tos/startup-order/)
- [Compose Specification](https://compose-spec.github.io/compose-spec/spec.html)