Compose Profiles, Overrides & Environment Parity

The plain-language idea

The earlier Compose lesson in this track covered the basics: one file, multiple services, a shared network where service names resolve as hostnames. That's enough for a single environment. In practice, a team runs the same application in several contexts — a developer's laptop, CI, staging — and each needs slightly different services running. A CI pipeline doesn't need a debugging UI. A laptop doesn't need the same replica count as staging. Copy-pasting the compose file per environment works for a week and then quietly drifts, because nobody remembers to update all three copies when something changes.

Profiles solve the "which services start" half of this: tag a service with one or more profile names, and docker compose up only starts services with no profile (always-on) plus whichever profiles you explicitly request. Multiple compose files merged together solve the "how does a service's config differ per environment" half: a base file holds what's shared everywhere, and a second file layered on top overrides or adds to it for one specific context.

See it in a real thing: a debug tool that skips CI entirely

# docker-compose.yml (base, committed)
services:
  api:
    build: ./api
    ports:
      - "4000:4000"

  db:
    image: postgres:16

  adminer:
    image: adminer
    profiles: ["debug"]
    ports:
      - "8080:8080"

# docker-compose.override.yml (local-only, typically gitignored)
services:
  api:
    volumes:
      - ./api:/app     # bind-mount source for hot reload, dev only
    environment:
      - DEBUG=true

docker compose up                    # api + db only — adminer is skipped
docker compose --profile debug up    # api + db + adminer

adminer (a database admin UI) never starts in CI or on a teammate's machine unless they explicitly ask for the debug profile — it costs nothing to leave declared in the base file. Meanwhile docker-compose.override.yml loads automatically alongside the base file with no extra flag, layering the bind-mount and debug flag on top for local development only, while staging runs from the base file (or its own override) with neither.

What people usually miss

Watch out

• Profile-tagged services aren't excluded from docker compose up --build or dependency resolution the way you'd expect. If an active service depends_on a profile-gated one, Compose starts it anyway regardless of profile — profiles gate direct invocation, not the dependency graph.
• Later files in a -f chain override matching keys, they don't fully replace the service block. docker-compose.yml plus docker-compose.staging.yml merges field-by-field (a list like ports is replaced, not appended, in most Compose versions) — assuming "override" means "wholesale replacement" leads to surprises on list-valued keys specifically.
• A gitignored override file means "works on my machine" can hide real config that teammates don't have. If a bind-mount or env var only exists in someone's local override, a bug that "only reproduces locally" may just be missing config, not a mystery.
• Environment parity is about topology, not just values. Running the same set of services locally as in staging (even with lighter resource limits) catches integration bugs that a hand-rolled local-only Docker setup — one container, mocked dependencies — would never surface until staging or prod.

Why this matters in interviews

"How do you keep local dev, CI, and staging from drifting apart when they all use Docker?" tests whether a candidate has actually maintained a multi-environment Compose setup or only ever run docker compose up against a single, static file — naming profiles and layered override files as the actual mechanism (not just "we're careful") is the concrete, checkable answer.