Opscraft
Docker Compose · Lesson 7 of 10 · 3 min read

Multiple environments: overrides, profiles, extends

Override files

Later files override and merge into earlier ones:

docker compose -f compose.yaml -f compose.prod.yaml up -d

Merge rules: single values (image, command) are replaced; lists like ports and volumes are merged; maps like environment are merged key by key. compose.override.yaml is loaded automatically when you don't pass -f, which makes it the natural home for dev-only settings (bind mounts, debug ports).

A typical split:

  • compose.yaml — the base: images, networks, volumes.
  • compose.override.yaml — dev: build:, source bind mounts, debugger ports.
  • compose.ci.yaml — CI: no bind mounts, test-specific env.
  • compose.prod.yaml — single-host prod: pinned tags, restart policies, resource limits, log rotation.
Enlarge diagramcompose.yamlthe base: images,networks, volumescompose.override.yamldev: build, bind mounts, debug ports (auto-loaded)compose.ci.yamlCI: no bind mounts, test settingscompose.prod.yamlsingle-host prod: pinned tags, limits, restart
Figure 1. One base file plus a small file per environment. Later files override earlier ones: single values are replaced, lists and maps are merged.
Swipe sideways to see all of it, or tap to open it full screen.

Profiles

services:
  mailhog: { image: mailhog/mailhog, profiles: [debug] }
  worker:  { build: ./worker, profiles: [workers] }

Services with profiles start only when asked: docker compose --profile debug up or COMPOSE_PROFILES=debug,workers. Services without profiles always start.

Reuse: anchors, extends, include

  • YAML anchors + x- fields (shown earlier) reuse blocks within one file.
  • extends inherits a service definition from another service or file: extends: { file: common.yaml, service: base-node }.
  • include (Compose 2.20+) imports whole compose files — e.g. each team owns its service's compose file, and a top-level file includes them all, with relative paths resolved per file.