Docker Compose: Dependencies, Health and Restart

1. The problem: “the container started” does not mean “the service is ready”

In a multi-service stack, container creation/start order is only part of runtime truth. A dependency can be Running while its endpoint is not ready, a migration has not completed, or its healthcheck still fails. A dependency restart also does not automatically imply the dependent service restarts.

The owned artifact is Compose Dependency Health Restart Record v1. It keeps the dependency graph, satisfaction condition, health contract, start/readiness observations, one-shot completion, restart trigger, and recovery evidence separate.

2. The dependency graph first controls order

Compose uses declared dependency relations to control create/start and removal ordering. If web depends on db, the dependency is created and started before the dependent service.

That ordering is important evidence, but it is not readiness or business-correctness evidence. Record graph and startup order independently from health.

3. Short-form depends_on closes only the “started” boundary

With short syntax, dependency services are started before the dependent service, but Compose does not wait for them to become healthy. This distinction causes a common startup race: the process is running while the service cannot yet handle real requests.

One lab fixture has exactly that state: the dependency is Running but ready=false. The correct conclusion is START_ORDER_ONLY_NOT_READY, not “Compose is broken.”

4. Long-form conditions make the dependency contract explicit

Long-form depends_on can declare the satisfaction condition. The three conditions owned by this lesson are service_started, service_healthy, and service_completed_successfully.

Choose the condition from the dependency contract. A long-running service that must accept requests may need more than service_started; a one-shot initializer has a different completion contract from a daemon health contract.

5. service_healthy depends on a healthcheck

service_healthy is meaningful only when the dependency has a defined healthcheck and reaches the expected healthy state. Compose can delay dependent startup until that health condition passes.

A passing healthcheck proves only the probe that was defined. It does not prove every business requirement, data invariant, or downstream authorization.

6. A healthcheck needs an explainable contract

A useful healthcheck identifies what it probes, what it does not probe, and how interval, timeout, retries, and start period shape the observation.

The Record keeps the probe contract separate from the observed health state. Do not expand a narrow probe into a broader readiness or correctness claim.

7. service_completed_successfully is for a one-shot dependency

Some dependencies are not daemons. An initializer or migration job must run and exit successfully. service_completed_successfully therefore has semantics distinct from service_healthy.

The lab includes a one-shot initializer. If its completion result fails, the dependent cannot be considered ready merely because other long-running services are Running.

8. A failure probe must falsify a plausible shortcut

A stack can use short-form dependencies and happen to work on the first run. That happy path does not prove the configuration is correct. Strong evidence introduces a bounded failure.

The fixture deliberately delays dependency readiness. Start-only semantics expose the race; changing the declared condition to service_healthy must change the decisive evidence.

9. depends_on restart: true has a bounded meaning

Current Compose documentation defines dependency restart: true around an explicit Compose-controlled dependency update/restart, causing the dependent service to restart so it can re-establish its relationship.

Do not equate this with a container runtime automatically restarting a crashed dependency under its own restart policy. They are different triggers.

10. Runtime restart policy is a separate layer

Container restart policy controls what the runtime does when a container dies. It is independent from the dependency restart linkage expressed by Compose.

The lab contains one explicit Compose restart case and one runtime crash/restart case. The Record must show why their evidence and expected dependent behavior differ.

11. Shutdown order also follows the dependency graph

Compose also uses dependency order during teardown, removing dependent services before their dependencies. This is useful lifecycle evidence, but it does not replace application-level graceful shutdown design.

This lesson records only the bounded shutdown-order consequence of the dependency graph.

12. Applications still need dependency-failure resilience

Even a precise Compose model cannot guarantee that a dependency will never fail later. Retry, timeout, circuit breaking, and degraded-mode behavior remain application/architecture concerns; depends_on is not a substitute for them.

Keep residual risk and unknowns visible. Configuration success is not proof of full resilience.

13. Compose Dependency Health Restart Record v1

For each dependency, the artifact records the dependent → dependency edge, condition, health or one-shot contract, observed startup state, readiness state, failure injection, explicit restart trigger, runtime restart behavior, recovery observation, and residual assumption.

Keep direct observation, inference, and unknowns separate. If decisive evidence is missing, leave the claim OPEN.

14. Lab and transfer

The lab is fully offline and synthetic. Eight fixtures model event, health, completion, and restart facts for a small stack. No Docker registry, production service, credential, or external network is used.

The transfer case changes a non-hard dependency, the readiness signal, the initializer result, and the restart linkage. Recompute all eight states from the changed evidence rather than copying baseline conclusions.

15. Sources, freshness, and claim boundaries

On 2026-09-19 the official Docker documentation was rechecked: Compose still derives startup/shutdown order from dependencies; Running is distinct from Ready; long-form conditions include service_started, service_healthy, and service_completed_successfully; and dependency restart: true is distinct from automated runtime restart after container death.

These are tool-sensitive claims. The next review is due on 2026-10-17, with earlier requalification after material Compose-documentation or fixture changes.