Home DockerDocker Compose Override Files: Dev, Staging and Production

Docker Compose Override Files: Dev, Staging and Production

by Knowledge Base Linux
Clean technical illustration of docker compose override files layering environment settings over a base compose file, no text

Maintaining separate Compose files for every environment is a recipe for drift: the development stack slowly diverges from staging, and staging diverges from production, until nobody trusts any of them. A docker compose override workflow fixes this by keeping one shared base file and layering small, environment-specific files on top of it. You change a service once in the base file, and every environment inherits the change.

Technical diagram of a docker compose override workflow for dev, staging, and production environments, no text

In this guide, you will learn how Compose merges files, how the automatic override file works, how to select explicit files for staging and production, and how to verify the merged result before you deploy. The examples use Docker Compose v2 (docker compose, with a space), which is the current standard.

Prerequisites

  • Docker Engine and Docker Compose v2 installed. Check with docker compose version.
  • A small project with at least one service, or willingness to create the example used below.
  • Basic familiarity with YAML and with running docker compose up.
  • A terminal on Linux, macOS, or Windows with access to the Docker daemon.

All examples in this guide run without any external images beyond the public nginx and postgres images, so you can follow along on a laptop.

The Base File: One Source of Truth

Start with a docker-compose.yml that describes the application as it runs everywhere: the services, their images, the networks, and the settings that do not change between environments.

services:
  web:
    image: nginx:1.27
    ports:
      - "8080:80"
    environment:
      - APP_ENV=base
    depends_on:
      - db
  db:
    image: postgres:16
    environment:
      - POSTGRES_USER=app
      - POSTGRES_PASSWORD=changeme
      - POSTGRES_DB=appdb
    volumes:
      - db-data:/var/lib/postgresql/data

volumes:
  db-data:

This file alone should produce a working stack. Run docker compose up -d and you get the base configuration. Everything environment-specific lives in override files, never in edits to this file.

How a Docker Compose Override File Merges

Compose does not replace the base file with the override file. It merges them, field by field, following rules that are worth learning before you rely on them:

  • Single-value settings are replaced. image, command, entrypoint, container_name, and restart from the later file win outright.
  • Multi-value settings are merged. ports, expose, environment, volumes, labels, and depends_on combine. For mappings like environment, a key set in the later file overrides the same key from the earlier file, while other keys are kept.
  • Ports merge by target port. If both files publish the same container port, the later file’s host mapping wins; different container ports are both kept.
  • Volumes merge by target path. Two mounts to the same container path conflict, and the later file wins; mounts to different paths coexist.
  • New services and networks are added. An override file can introduce services (such as a mail catcher for development) that do not exist in the base file at all.

One common misunderstanding: an override file cannot remove a port, volume, or environment variable set in the base file. It can only replace its value or add new entries. If you truly need a setting gone in one environment, restructure the base file so that setting lives in the environment files instead.

The authoritative reference for every merge rule is the Docker Compose documentation on multiple Compose files. When a merge behaves unexpectedly, check the docs before assuming a bug.

The Automatic Override: docker-compose.override.yml

When you run docker compose up in a directory containing both docker-compose.yml and docker-compose.override.yml, Compose loads and merges the override file automatically. No flags are needed. This is the conventional place for development settings, because development is the environment developers run by default.

Create docker-compose.override.yml for local development:

services:
  web:
    ports:
      - "8080:80"
    volumes:
      - ./site:/usr/share/nginx/html:ro
    environment:
      - APP_ENV=development
      - DEBUG=true
  db:
    ports:
      - "5432:5432"
    environment:
      - POSTGRES_PASSWORD=devpassword

With both files present, docker compose up -d now starts the web service with your local site directory mounted in, exposes the database on the host for inspection tools, and sets development environment variables. Nothing in the base file changed.

Two practical rules keep this pattern safe. First, never commit secrets or production credentials into an override file; development values are fine, production values belong in a secrets manager or environment file outside version control. Second, make sure docker-compose.override.yml is not accidentally deployed to production, where its development conveniences (open database ports, debug flags, local volume mounts) become security problems.

Explicit Files for Staging and Production

For environments beyond development, skip the automatic override and select files explicitly with repeated -f flags. Files are merged left to right, so later files take precedence over earlier ones. The base file always comes first.

Create docker-compose.staging.yml:

services:
  web:
    ports:
      - "80:80"
    environment:
      - APP_ENV=staging
    deploy:
      replicas: 2
  db:
    environment:
      - POSTGRES_PASSWORD=${STAGING_DB_PASSWORD}

And docker-compose.prod.yml:

services:
  web:
    ports:
      - "80:80"
    environment:
      - APP_ENV=production
    restart: always
    deploy:
      replicas: 3
  db:
    environment:
      - POSTGRES_PASSWORD=${PROD_DB_PASSWORD}
    volumes:
      - db-data:/var/lib/postgresql/data

Note on the deploy.replicas entries above: plain docker compose up ignores the deploy section; those replica counts are honored when the same files are deployed to a Docker Swarm (docker stack deploy). With plain Compose, scale a service with docker compose up -d --scale web=2, and only when the service does not bind a fixed host port.

Start staging with:

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

And production with:

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

Note an important subtlety: when you pass -f flags explicitly, Compose does not also load docker-compose.override.yml automatically. Only the files you list are merged. That is exactly what you want for staging and production, since it guarantees development settings never leak into those environments.

You can chain more than two files. A common pattern is a shared production base plus a per-host file for machine-specific settings, for example -f docker-compose.yml -f docker-compose.prod.yml -f docker-compose.host-a.yml. Keep the chain short and documented, or the merge order becomes hard to reason about.

Environment Variables and Secrets

Override files pair naturally with environment variable interpolation. Values like ${STAGING_DB_PASSWORD} are read from the shell environment or from a .env file in the project directory at the time Compose parses the files. This keeps credentials out of the YAML while letting each environment supply its own values.

For production, prefer one of these approaches over a checked-in .env file:

  • Export variables from your deployment pipeline’s secret store before running Compose.
  • Use Docker secrets (docker secret in Swarm mode) or your orchestrator’s secret mechanism.
  • Mount credentials as files and reference them with env_file or secrets in the production override.

Never bake a real production password into an example, a screenshot, or a repository. The values in this guide are placeholders.

Verify the Merged Docker Compose Override with docker compose config

Never deploy a merged configuration you have not inspected. The docker compose config command prints the fully merged, interpolated configuration without starting anything, and it validates the YAML at the same time. This is the single most useful check in a docker compose override workflow.

docker compose -f docker-compose.yml -f docker-compose.staging.yml config

Review the output for the values you expect: the staging port mapping, APP_ENV=staging, and the staging database password variable. If a value is wrong, the problem is in the merge order or in a file you did not intend to include. The merged output itself is the reliable check: a value that appears only in the staging file proves that file was loaded.

Add docker compose config -q to your CI pipeline as a validation step. The -q flag runs quietly and exits non-zero on invalid configuration, so a broken merge fails the build before it reaches any server. Pair this with Docker Compose profiles for optional stacks if some services should only run in certain environments, and with Docker Compose healthchecks for self-healing services to make the merged stack restart unhealthy containers automatically.

Troubleshooting

The override file seems to be ignored

First, confirm the filename: the automatic file must be exactly docker-compose.override.yml (or compose.override.yml) in the same directory as the base file. A typo like docker-compose.overide.yml is silently ignored. Second, if you passed any -f flag, the automatic override is disabled; list every file you want, including the override, explicitly.

A setting from the base file will not go away

This is by design. Overrides merge, they do not delete. Move the setting out of the base file and into the environment files that need it, or accept the base value in all environments. The !override and !reset YAML tags exist in newer Compose versions for sequence replacement, but they are rarely needed and reduce readability; prefer restructuring the files first.

Ports conflict when starting the stack

If two services, or the host, already use a port, Compose fails with a bind error. Run docker compose config to see the merged port list, then check what holds the port with ss -tlnp | grep 8080 (adjust the port number). In development, changing the host side of the mapping in the override file is usually the right fix.

Environment variables are empty in the merged output

Interpolation happens from the shell environment and the project .env file, not from the override file itself. If ${STAGING_DB_PASSWORD} renders empty, the variable was not exported and no .env entry exists. Export it or add it to .env, then re-run docker compose config to confirm.

Different behavior between local runs and CI

CI usually checks out only tracked files, so an untracked local override file is missing there and the merged result differs. Commit the base file and every environment file the pipeline uses, and keep purely personal tweaks in a git-ignored local override that CI never sees.

Conclusion

A docker compose override strategy turns environment management from copy-paste maintenance into a clean layering problem. Keep the base file universal, put development conveniences in the automatic docker-compose.override.yml, select staging and production files explicitly with -f, and verify every combination with docker compose config before deploying.

Start small: extract one environment’s differences from a duplicated Compose file into an override, verify the merged output matches what you run today, and delete the duplicate. Repeat for the next environment, and your stacks will stay in sync as your application grows.

You may also like

KbLinux

Typically replies within a day

Hello, Welcome to the site. Please click below button for chatting me through Telegram.