Skip to content
Tutorials Center
My learning

Topics

Lesson 64 of 111 ยท Docker Compose

Multiple Files, Profiles and Extends

Split a Compose project across files: compose.override.yaml, -f merging rules, !reset and !override, include, extends, YAML anchors, and when to choose each technique.

A Compose file starts small and grows. Then you need the same stack in different shapes: development with bind mounts and debug flags, production with restart policies and no source mounts, CI with extra test services. Copy-pasting the file three times is a trap, because the copies drift apart.

Compose has four built-in ways to share and layer configuration: override files (merge several files into one), include (pull in another project's file), extends (inherit from one service), and YAML anchors (plain YAML reuse). This lesson shows what each does, the exact merge rules, and which one to reach for. Profiles, the fifth tool, were introduced in Environment, Variables and Secrets and we will see where they fit. All output is from Docker 29 and Compose v5.

compose.override.yaml: the automatic second file

When you run docker compose with no -f option, Compose looks for compose.yaml and compose.override.yaml in the project folder and merges them. The convention is simple: the base file holds what is true everywhere; the override file holds your local development tweaks.

Base file, compose.yaml:

YAML
name: tcd-b9-mf
services:
  web:
    image: nginx:alpine
    ports:
      - "127.0.0.1:18093:80"
    environment:
      MODE: base
      KEEP: "1"
    command: ["nginx", "-g", "daemon off;"]

Override file, compose.override.yaml:

YAML
services:
  web:
    ports:
      - "127.0.0.1:18094:80"
    environment:
      MODE: dev
      EXTRA: "1"
    command: ["nginx-debug", "-g", "daemon off;"]
    volumes:
      - ./html:/usr/share/nginx/html:ro

Run docker compose config to see the merged result (shortened here):

CONSOLE
$ docker compose config
name: tcd-b9-mf
services:
  web:
    command:
      - nginx-debug
      - -g
      - daemon off;
    environment:
      EXTRA: "1"
      KEEP: "1"
      MODE: dev
    image: nginx:alpine
    ports:
      - mode: ingress
        host_ip: 127.0.0.1
        target: 80
        published: "18093"
        protocol: tcp
      - mode: ingress
        host_ip: 127.0.0.1
        target: 80
        published: "18094"
        protocol: tcp
    volumes:
      - type: bind
        source: /path/to/project/html
        target: /usr/share/nginx/html
        read_only: true
        bind: {}

Study this result, because it shows all the merge rules in one go.

The merge rules

Kind of value What happens Example above
Single value (image, restart) The later file replaces it command became nginx-debug
Map (environment, labels) Keys are merged; later wins on a clash KEEP stayed, EXTRA added, MODE became dev
ports, volumes, expose, dns Entries are appended (de-duplicated) Both published ports survive
command, entrypoint The later file replaces the whole list

Two things catch people out. First, ports are appended, not replaced: the dev override above exposed a second port instead of switching to a new one, so the container now answers on 18093 and 18094. Second, the replaced command is a complete swap: Compose does not merge list items.

Taking control: !override and !reset

Sometimes you really do want to replace a list or remove a key. Compose has two YAML tags for that:

YAML
services:
  web:
    ports: !override
      - "127.0.0.1:18095:80"
    environment:
      KEEP: !reset null

!override discards the earlier value and uses this one instead of merging. !reset null deletes the key. Merged with the base file:

CONSOLE
$ docker compose -f compose.yaml -f reset.yaml config
...
    environment:
      MODE: base
...
    ports:
      - mode: ingress
        host_ip: 127.0.0.1
        target: 80
        published: "18095"
        protocol: tcp

Only port 18095 remains, and KEEP is gone while MODE is untouched.

Selecting files with -f

-f (or --file) names the files explicitly. They are merged in order, and later files win:

CONSOLE
$ docker compose -f compose.yaml -f compose.prod.yaml config
...
    command:
      - nginx
      - -g
      - daemon off;
    environment:
      KEEP: "1"
      MODE: prod
...
    restart: unless-stopped

with compose.prod.yaml being:

YAML
services:
  web:
    restart: unless-stopped
    environment:
      MODE: prod

Notice what is missing: EXTRA, the dev ports and the html volume. As soon as you pass -f, Compose stops reading compose.override.yaml automatically, which is exactly what makes this a safe pattern for production: the base file plus a production file, without the developer's bind mounts.

A typical layout looks like this:

TEXT
compose.yaml            # shared: images, networks, volumes
compose.override.yaml   # dev defaults, loaded automatically
compose.prod.yaml       # production: docker compose -f compose.yaml -f compose.prod.yaml up -d
compose.ci.yaml         # tests: docker compose -f compose.yaml -f compose.ci.yaml run --rm tests

Typing -f every time gets old, so set the COMPOSE_FILE environment variable (often in .env). Separate files with : on Linux and macOS, or ; on Windows; COMPOSE_PATH_SEPARATOR changes the separator:

CONSOLE
$ COMPOSE_FILE="compose.yaml;compose.prod.yaml" docker compose config | grep -E 'restart|MODE'
      MODE: prod
    restart: unless-stopped

Use docker compose config -o merged.yaml to write the fully merged file to disk, which is handy for a code review or a debugging session.

Relative paths in every file are resolved against the first file's folder (the project directory), not each file's own location. Keep all override files next to the base file, or pass --project-directory.

include: reuse another project

include pulls whole Compose files into yours. Each included file is its own self-contained project, so its relative paths and .env resolve against its folder, not yours. This suits a platform team that publishes a shared infra/compose.yaml (database, queue) and app teams that include it:

YAML
name: tcd-b9-inc
include:
  - infra/compose.yaml
services:
  app:
    image: alpine:3
    command: ["sleep", "300"]
    depends_on:
      - db

Where infra/compose.yaml defines the db service and a data volume. The including file can use the included services, here with depends_on:

CONSOLE
$ docker compose config --services
db
app
$ docker compose up -d
$ docker compose ps --format 'table {{.Service}}\t{{.Status}}'
SERVICE   STATUS
app       Up 1 second
db        Up 3 seconds
$ docker volume ls --filter name=tcd-b9-inc --format '{{.Name}}'
tcd-b9-inc_data

Compare with -f merging: include is meant for adding services, not for modifying them. When we gave the including file its own db service with image: alpine:3, Compose did not complain: it quietly produced one db service with the including file's image and the included file's environment and volume. Do not rely on that blend. Pick distinct service names, and use -f when you want to modify a service.

extends: inherit from one service

extends lets one service start from another service's definition, in the same file or a different one. It is for repeating a service shape inside a project: several workers that share restart policy, init and a base environment.

common.yaml:

YAML
services:
  base-service:
    image: alpine:3
    restart: unless-stopped
    environment:
      TZ: UTC
    init: true

compose.yaml:

YAML
name: tcd-b9-ex
services:
  one:
    extends:
      file: common.yaml
      service: base-service
    command: ["sh", "-c", "echo one $$TZ; sleep 60"]
    environment:
      TZ: Europe/Berlin
  two:
    extends:
      file: common.yaml
      service: base-service
    command: ["sh", "-c", "echo two $$TZ; sleep 60"]

Each service takes the base and then applies its own keys using the same merge rules as before:

CONSOLE
$ docker compose up -d
$ docker compose logs
two-1  | two UTC
one-1  | one Europe/Berlin

two kept the inherited TZ: UTC; one overrode it. Both inherited restart: unless-stopped and init: true. Note that extends does not copy depends_on, volumes_from or links, because those refer to other services that might not exist in the extending file.

YAML anchors and extension fields

Compose files are plain YAML, so you can use anchors (&name), aliases (*name) and merge keys (<<) to reuse any fragment. Compose adds a convention: top-level keys starting with x- are ignored by Compose, which makes them a safe place to define fragments.

YAML
name: tcd-b9-ex
x-logging: &default-logging
  driver: json-file
  options:
    max-size: "5m"
    max-file: "2"
x-env: &shared-env
  APP_ENV: staging
  TZ: Europe/Berlin
services:
  one:
    image: alpine:3
    logging: *default-logging
    environment:
      <<: *shared-env
      NAME: one
  two:
    image: alpine:3
    logging: *default-logging
    environment:
      NAME: two

&default-logging names a block, and *default-logging pastes it. <<: *shared-env merges a map into another map and lets you add keys next to it. The result is verified at the engine level:

CONSOLE
$ docker inspect tcd-b9-ex-one-1 --format '{{.HostConfig.LogConfig.Type}} {{.HostConfig.LogConfig.Config}} {{.HostConfig.RestartPolicy.Name}}'
json-file map[max-file:2 max-size:5m] unless-stopped

Log rotation limits like these are important in production; Logging and Monitoring explains why.

Anchors are resolved by the YAML parser within one file. They cannot reach across files, and docker compose config expands them (and keeps the x- blocks in the output). Use anchors for small repeated fragments, and extends when the shared part is a whole service or lives in another file.

Choosing the right tool

You want to... Use
Add dev-only settings on top of a base file compose.override.yaml
Switch between dev, CI and production shapes -f with several files, or COMPOSE_FILE
Make some services optional in the same file profiles
Bring in services that another team maintains include
Give several services a shared base definition extends
Repeat a block (logging, healthcheck, env) YAML anchors with x- fields

A common healthy setup combines them: a base compose.yaml with profiles for optional tools, an automatic override for local development, and a production file selected with -f. Keep the number of layers small. When you cannot predict the final result by reading the files, run docker compose config and read that instead.

An automatically loaded compose.override.yaml is easy to forget in production. If a server directory contains that file, plain docker compose up -d will merge developer settings (bind mounts, debug commands) into a production deploy. Either do not copy it to servers, or always pass -f explicitly. See Deploying on a Single Host.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. You run docker compose up in a folder with compose.yaml and compose.override.yaml. What happens?

    Without -f, Compose loads compose.yaml and then merges compose.override.yaml on top.
  2. 2. The base file publishes port 8080 and the override publishes 9090 for the same service. What does the merged service publish?

    ports entries are appended. To replace them, use the !override tag in the later file.
  3. 3. You run docker compose -f compose.yaml -f compose.prod.yaml up -d. Is compose.override.yaml also loaded?

    The override file is only picked up automatically when no -f is given.
  4. 4. What is the main difference between include and -f merging?

    Included files resolve relative paths and .env against their own folder, so they work as reusable building blocks. -f is for layering changes on top of the same services.
  5. 5. What is the purpose of top-level keys that start with x-, such as x-logging?

    Compose ignores x- keys (extension fields), so you can attach anchors to them and reference the fragments elsewhere in the file.

Summary

  • compose.override.yaml is merged automatically over compose.yaml; with -f you choose the files and the order, and later files win.
  • Merge rules: scalars are replaced, maps are merged, ports and volumes are appended, and command is replaced as a whole.
  • Use !override to replace a list and !reset null to remove a key.
  • COMPOSE_FILE saves typing -f; the separator is : (or ; on Windows).
  • include brings in another Compose file as a self-contained piece, extends inherits from one service, and anchors with x- fields repeat YAML fragments.
  • Check the final result with docker compose config, and beware of an override file left on a production server.

Next: Compose Commands