Multiple Compose files (override) in Docker - Commands & Configuration

Introduction

Sometimes you want to change or add settings to your Docker setup without changing the original file. Using multiple Compose files lets you keep your base setup and add or override parts easily.

When you want to add extra services only for development without changing production setup

When you need to change environment variables for testing without editing the main file

When you want to increase resource limits temporarily without touching the base config

When you want to add debugging tools to your containers only in certain cases

When you want to keep your main Compose file clean and add optional features separately

Config File - docker-compose.override.yml

docker-compose.override.yml

version: '3.8'
services:
  web:
    environment:
      - DEBUG=true
    ports:
      - "8081:80"

This file overrides the web service from the main docker-compose.yml.

It sets an environment variable DEBUG=true and changes the port mapping to 8081:80.

Docker Compose automatically uses this override file along with the main file when you run commands.

Commands

Starts the containers using both the main and override Compose files. The override settings will apply on top of the base configuration.

Terminal

docker-compose up -d

Expected Output

Creating network "example_default" with the default driver

Creating volume "example_data" with default driver

Creating example_web_1 ... done

→

-d - Run containers in the background (detached mode)

Shows the running containers and their status to verify that the services started correctly.

Terminal

docker-compose ps

Expected Output

    Name                  Command               State           Ports         

----------------------------------------------------------------------------

example_web_1   nginx -g 'daemon off;'        Up      0.0.0.0:8081->80/tcp

Displays the combined configuration from the main and override files so you can see the final settings Docker Compose will use.

Terminal

docker-compose config

Expected Output

services:

  web:

    environment:

      - DEBUG=true

    image: nginx:latest

    ports:

      - 8081:80

version: '3.8'

Key Concept

If you remember nothing else from this pattern, remember: Docker Compose automatically merges multiple files, letting you override or add settings without changing the original file.

Common Mistakes

Editing the main docker-compose.yml file directly for temporary changes

This makes it hard to keep track of changes and can cause conflicts when switching environments.

Use a separate override file to add or change settings temporarily or for specific environments.

Not using the -f flag when you want to use custom override files

Docker Compose only automatically uses docker-compose.override.yml by default; other files need to be specified explicitly.

Use 'docker-compose -f docker-compose.yml -f custom-override.yml up' to apply multiple custom files.

Summary

Use multiple Compose files to keep your base Docker setup clean and add or override settings easily.

Docker Compose automatically merges docker-compose.override.yml with the main file when you run commands.

Use 'docker-compose config' to see the final combined configuration before starting containers.

Practice

1. What is the main purpose of using multiple Docker Compose files with the -f option?

easy

A. To override or extend settings without changing the original compose file

B. To run multiple containers simultaneously

C. To create multiple Docker images at once

D. To speed up Docker container startup time

Solution

1. Step 1: Understand the role of multiple Compose files

   Multiple Compose files allow you to customize or override configurations without editing the original file.

2. Step 2: Recognize the use of the -f option

   The -f option lets you specify multiple files, where later files override earlier ones.

3. Final Answer:

   To override or extend settings without changing the original compose file -> Option A

4. Quick Check:

   Multiple Compose files = override settings [OK]

Hint: Multiple files with -f override earlier settings [OK]

Common Mistakes:

• Thinking multiple files run containers simultaneously
• Confusing Compose files with Docker images
• Assuming it speeds up container startup

2. Which of the following is the correct syntax to use two Docker Compose files named docker-compose.yml and docker-compose.override.yml together?

easy

A. docker-compose up -f docker-compose.yml -f docker-compose.override.yml

B. docker-compose -f docker-compose.yml -f docker-compose.override.yml up

C. docker-compose up docker-compose.yml docker-compose.override.yml

D. docker-compose -f up docker-compose.yml docker-compose.override.yml

Solution

1. Step 1: Recall the correct order of options

   The -f option must come before the command and can be repeated for multiple files.

2. Step 2: Verify the syntax correctness

   docker-compose -f docker-compose.yml -f docker-compose.override.yml up correctly places -f flags before the up command and lists both files.

3. Final Answer:

   docker-compose -f docker-compose.yml -f docker-compose.override.yml up -> Option B

4. Quick Check:

   Correct order: docker-compose -f file1 -f file2 up [OK]

Hint: Place all -f options before the command [OK]

Common Mistakes:

• Putting -f after the command
• Listing files without -f
• Mixing command and file order

3. Given these two Compose files:

docker-compose.yml:
services:
  web:
    image: nginx:1.19
    ports:
      - "80:80"

docker-compose.override.yml:
services:
  web:
    image: nginx:1.21
    environment:
      - DEBUG=true

What image version will the web service use when running docker-compose -f docker-compose.yml -f docker-compose.override.yml up?

medium

A. nginx:1.19

B. nginx:latest

C. It will cause an error due to conflicting images

D. nginx:1.21

Solution

1. Step 1: Understand override behavior

   The second file overrides matching keys from the first file, including the image version.

2. Step 2: Identify the image in the override file

   The override file sets image: nginx:1.21, which replaces nginx:1.19.

3. Final Answer:

   nginx:1.21 -> Option D

4. Quick Check:

   Override file image replaces base image [OK]

Hint: Later files override earlier image settings [OK]

Common Mistakes:

• Assuming base file image stays unchanged
• Thinking it defaults to latest
• Expecting an error from override

4. You run docker-compose -f base.yml -f override.yml up but get an error: ERROR: Service 'app' has both 'build' and 'image' specified. What is the likely cause?

medium

A. Both files define 'app' service with conflicting 'build' and 'image' keys

B. You forgot to specify the -d flag

C. The override file is missing the 'app' service definition

D. Docker Compose does not support multiple files

Solution

1. Step 1: Understand the error message

   The error says the 'app' service has both 'build' and 'image' keys, which Docker Compose disallows.

2. Step 2: Identify conflict from multiple files

   When combining files, if one file sets 'build' and another sets 'image' for the same service, this conflict occurs.

3. Final Answer:

   Both files define 'app' service with conflicting 'build' and 'image' keys -> Option A

4. Quick Check:

   Conflicting keys in combined files cause this error [OK]

Hint: Check for conflicting keys in combined service definitions [OK]

Common Mistakes:

• Thinking -d flag fixes this error
• Assuming missing service causes error
• Believing multiple files are unsupported

5. You have a base Compose file docker-compose.yml and an override docker-compose.prod.yml that changes the web service's environment variables and ports. You want to run the production setup but keep the base file unchanged. Which command correctly applies the override and ensures the web service uses the production settings?

hard

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

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

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

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

Solution

1. Step 1: Recall override order

   The last file listed with -f overrides earlier files.

2. Step 2: Check command syntax and order

   docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d correctly lists base file first, then production override, followed by the up -d command.

3. Final Answer:

   docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d -> Option C

4. Quick Check:

   Last -f file overrides earlier ones [OK]

Hint: List base file first, override file second with -f [OK]

Common Mistakes:

• Reversing file order so base overrides override
• Placing -f after the command
• Omitting -d for detached mode