Docker Compose for local development: override files, profiles, healthy dependencies and watch

Goal

A single docker compose up that gives every contributor the same database, queue and service versions as production, with fast code reload, without turning the committed file into a local-only artefact.

Prerequisites

A Dockerfile per service that builds from a clean checkout, health checks defined for stateful dependencies, and configuration read from environment variables.

Steps

1. Write compose.yaml as the production-shaped base: images by tag, service names that match DNS names used in configuration, no host ports, no bind mounts. The Docker documentation (cited) states that Compose reads compose.yaml and an optional compose.override.yaml by default and merges them, later files overriding or extending earlier ones.
2. Put local conveniences into compose.override.yaml: published ports, a bind mount of the source tree, debug environment variables. Commit it if every developer wants the same, otherwise commit an .example and ignore the real one.
3. Declare dependencies with conditions: depends_on: {db: {condition: service_healthy}} makes Compose wait for the dependency's health check rather than merely for its container start; service_completed_successfully waits for a one-shot migration container to exit 0 (both in the cited services reference).
4. Attach optional tools (mail catcher, admin UI, load generator) to profiles: so that plain up skips them; start them with --profile debug or COMPOSE_PROFILES.
5. Add a develop.watch section: sync for interpreted code, sync+restart when the process must restart to pick up changes, rebuild when dependency manifests change; run with docker compose up --watch, or docker compose watch to keep sync events out of the application logs. The cited Compose Watch page documents these actions and notes that watch only tracks services built from local source with build, not those using a pre-built image.
6. Store non-secret defaults in .env for variable interpolation and keep credentials out of committed files; pass them through env_file entries that are git-ignored.
7. Run docker compose config in CI to render the merged file and catch path or interpolation mistakes.

Expected result

New contributors reach a working stack in one command; the base file doubles as documentation of the runtime topology; production differences are visible as a small override file rather than scattered edits.

Limits and test basis

Compose describes a single host and is not a production orchestrator; resource limits, restart policies and networking differ from Kubernetes. The cited Compose Watch page presents watch as a companion to bind mounts, not a replacement: its ignore rules let a tree such as node_modules/ stay out of the sync, which the page motivates with I/O load from many small files and with compiled artefacts that cannot be shared across host and container platforms. Behaviour follows the cited references; no timings are claimed.