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.

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, andrestartfrom the later file win outright. - Multi-value settings are merged.
ports,expose,environment,volumes,labels, anddepends_oncombine. For mappings likeenvironment, 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 secretin Swarm mode) or your orchestrator’s secret mechanism. - Mount credentials as files and reference them with
env_fileorsecretsin 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.