9.3.5.5 Environment Specific Compose

Environment-specific Compose refers to adapting a Compose file's configuration for different deployment contexts — development, staging, production — typically achieved through Compose's file-merging capability rather than maintaining entirely separate, duplicated Compose files for each environment.

The Base File and Override Pattern

A base Compose file defines the application's common structure, with environment-specific override files layering additional or modified configuration on top.

services:
  api:
    build: .
    environment:
      - LOG_LEVEL=info

services:
  api:
    environment:
      - LOG_LEVEL=debug
    volumes:
      - .:/app

docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d

This combines the base configuration with the development-specific override, resulting in a merged configuration appropriate for that specific context.

Why This Approach Avoids Duplication

Rather than maintaining several largely similar, fully separate Compose files (with all the duplication and risk of drift that implies), this pattern keeps shared configuration in one place, with override files containing only what genuinely differs between environments.

services:
  api:
    deploy:
      resources:
        limits:
          memory: 1G

A production-specific override like this adds configuration genuinely unique to that environment, without needing to repeat everything already defined in the base file.

Using a Default Override File Automatically

Compose automatically merges in a file named docker-compose.override.yml, if present, without needing to specify it explicitly — useful for a default local development override that doesn't require remembering an extra flag.

docker compose up -d

This automatically incorporates docker-compose.override.yml if it exists alongside the base file.

Why Environment-Specific Compose Matters

This layered, override-based approach provides a maintainable way to adapt a single, well-organized base configuration for different deployment contexts, avoiding the duplication and inconsistency risk that fully separate, independently maintained Compose files for each environment would introduce.