Overriding Compose Files for Dev and Prod
When you build a modern application, the environment you use to write code on your laptop is fundamentally different from the environment that runs in production. Locally, you want hot-reloading, exposed debugging ports, and verbose logs. In production, you want strict security, minimal exposed ports, and automated restart policies.
Instead of maintaining two entirely separate Compose files (which leads to configuration drift and bugs), Docker Compose allows you to create a foundational "base" file and use overrides to apply environment-specific tweaks.
- How Docker Compose merges multiple configuration files together.
- How to structure your base
docker-compose.ymlfor production safety. - How to use
docker-compose.override.ymlfor seamless local development. - The critical difference between how Docker merges dictionaries vs. lists.
1. The Core Concept: Layering Configurations
Docker Compose is designed to merge multiple YAML files into a single, final configuration in memory before starting your containers. By default, if you run docker compose up, Docker automatically looks for two files in your directory: docker-compose.yml and docker-compose.override.yml. It reads the first one, and then applies the second one on top of it.
| File Name | Primary Purpose | Execution Behavior |
|---|---|---|
| docker-compose.yml | The base configuration. It defines the core services, networks, and volumes required to run the app anywhere. | Read first. Should be as close to production-ready as possible. |
| docker-compose.override.yml | The local development layer. It adds helpful developer tools like bind mounts and exposed database ports. | Read second automatically if you don't specify flags. Merges over the base. |
| docker-compose.prod.yml | The strict production layer. It adds restart policies, logging drivers, and specific deployment replicas. | Read manually using the -f flag during deployment. |
2. Creating Your Base and Override Files
Let's look at a practical example of a web application and a Postgres database. We will build the base file first, and then apply developer conveniences through the override file.
The Base Configuration
Example 1: docker-compose.yml (The Foundation)
services:
web:
image: my-app:latest
environment:
- DB_HOST=db
- NODE_ENV=production
ports:
- "80:80"
db:
image: postgres:15-alpine
environment:
- POSTGRES_USER=admin
- POSTGRES_PASSWORD=secret
volumes:
- db-data:/var/lib/postgresql/data
# Notice: We intentionally do NOT expose the database port to the host machine.
# The web service can still reach it internally on port 5432.
volumes:
db-data:
The Local Development Override
If a developer pulls this repository, they need to attach their local database client (like DBeaver or pgAdmin) to inspect the data. They also want the application to hot-reload when they edit files, rather than using the baked-in production image.
Example 2: docker-compose.override.yml (The Local Tweaks)
services:
web:
# 1. Override the build context to compile locally
build: .
# 2. Add a bind mount to sync local code changes instantly
volumes:
- ./:/app
# 3. Change the environment variable to development mode
environment:
- NODE_ENV=development
db:
# 4. Expose the port to the host machine for local debugging tools
ports:
- "5432:5432"
Expected output when running: docker compose up
[+] Running 2/2 ✔ Container demo-db-1 Started ✔ Container demo-web-1 Started # Docker automatically combined both files. # The web container is running with a volume mount, and the DB is exposed on 5432.
3. The File Merge Workflow Visualized
Understanding exactly how Docker processes these files is critical to preventing configuration bugs when deploying to a live server.
How Docker Compose Merges Configurations
Docker reads the base file, applies the override file on top, and deploys the resulting combined configuration.
4. Step-by-Step Execution Breakdown
When you use overrides, Docker follows very specific rules for merging lists (arrays) versus dictionaries (key-value maps). Knowing this prevents painful deployment issues.
environment variables, Docker merges the two lists of variables. If they define the same variable (like NODE_ENV), the value in the override file wins.ports or volumes, Docker adds them together. The override file does not delete the ports defined in the base file; it just adds its own ports to the final container.docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d.docker-compose.override.yml to your source control (Git) if it contains secrets or local-only absolute file paths. Add it to your .gitignore file. Keep your production secrets securely managed in environment files (.env) or a vault.5. Hands-On Practice
Solidify your understanding by manipulating compose files.
How do you verify exactly what Docker will deploy without actually spinning up the containers?
Hint: Run docker compose config. This command parses the base and override files, merges them, and prints out the final YAML structure it is about to use.
Create a file named docker-compose.prod.yml. Add a restart: always policy to the web service. Then, start the stack using both the base file and your new production file.
Expected result: You should use the command docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d.
If your base file specifies command: npm start, how can you change it to run a test suite in your override file?
Hint: Just redefine command: npm test under the service in the override file. Single-value fields completely replace the base value.
6. Interview Questions
If you are applying for a DevOps or Senior Backend Engineering role, you will be tested on your container architecture knowledge.
Answer: By default, Docker Compose looks for `docker-compose.yml` and `docker-compose.override.yml`. If both are present, it automatically merges the override file on top of the base file before deploying.
Answer: Lists in Docker Compose, such as ports and volumes, are concatenated (added together). The container will end up with both port mappings exposed, not just the one from the override file.
Conclusion
Separating your configurations using docker-compose.override.yml keeps your primary architecture clean and production-ready, while offering developers the flexibility they need on their local machines. By mastering this layering system, you ensure that test databases, verbose debuggers, and exposed development ports never accidentally make their way into your live production environments.
Official Documentation
Upgradix by Shrash Studio – Learn Technology. Build Your Future.