How to use different/multiple Docker Compose files on different servers

Introduction

Official docs

There are two common options for using multiple compose files.

Option 1 — Default override file

By default, Compose reads docker-compose.yml and an optional docker-compose.override.yml. Example setups:

• Local machine: only docker-compose.yml
• Dev/prod servers: docker-compose.yml + docker-compose.override.yml

This is simple but not very flexible. Keeping a correct docker-compose.override.yml in your repository can be hard when servers differ.

Option 2 — Explicit override files

Use explicit override files per environment, for example:

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

You can keep multiple override files like docker-compose.prod.yml, docker-compose.dev.yml, etc. This is more versatile than the default override.

Problems with the above approaches

• Files are combined at runtime, so you don't get a resulting merged docker-compose.yml file to inspect and verify.
• The -f ... -f ... override syntax works with docker-compose but does not directly translate to Docker Swarm's docker stack deploy.

Recommended solution — generate the merged file

Use docker-compose config to produce a merged/flattened compose file you can review and then use with docker-compose or docker stack deploy:

docker-compose -f docker-compose.yml -f docker-compose.prod.yml \
  config > docker-compose.stack.yml

This command merges the files the same way Compose would at runtime, but writes the final composed YAML to docker-compose.stack.yml so you can:

• review/validate the resulting configuration
• store or audit the merged output
• use it with Docker Swarm

Now you can start with the merged file:

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

Or deploy it to a Swarm:

docker stack deploy -c docker-compose.stack.yml mystack

Benefits:

• You can verify the merged configuration before applying it.
• The same merged file works for Compose and Swarm deployments.