LATEST 🚀 Welcome to Upgradix by Shrash Studio – Your destination for free technology learning and career growth.
🕘 Updated:
Docker

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.

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.

What you will learn
  • How Docker Compose merges multiple configuration files together.
  • How to structure your base docker-compose.yml for production safety.
  • How to use docker-compose.override.yml for 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.
Important: You do not need to rewrite the entire service in the override file. You only write the specific keys you want to add or change. Docker handles the merging intelligently.

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-compose.yml Base Definitions docker-compose.override.yml Local Additions Final Engine State Memory Merged Configuration

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.

Step 1: Dictionaries are merged. If both files define 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.
Step 2: Lists are concatenated. If both files define 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.
Step 3: Execution flags. If you want to deploy to production, you bypass the default override file entirely by explicitly chaining the files you want to use: docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d.
Watch out: Never commit 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.

Beginner Exercise 1: Check your configuration

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.

Intermediate Exercise 2: Create a production override

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.

Advanced Exercise 3: Overriding a command

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.

Q1. If I run `docker compose up` without any flags, which files does Docker use?

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.

Q2. What happens if you define a port mapping in the base compose file, and a completely different port mapping in the override file?

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.

Comments & Ratings (0)

Log in or create a student account to comment and rate this article.

Be the first to comment on this article.