Extend your Compose file

Docker Compose's extends attribute lets you share common configurations among different files, or even different projects entirely.

Extending services is useful if you have several services that reuse a common set of configuration options. With extends you can define a common set of service options in one place and refer to it from anywhere. You can refer to another Compose file and select a service you want to also use in your own application, with the ability to override some attributes for your own needs.

Important

When you use multiple Compose files, you must make sure all paths in the files are relative to the base Compose file. This is required because extend files need not be valid Compose files. Extend files can contain small fragments of configuration. Tracking which fragment of a service is relative to which path is difficult and confusing, so to keep paths easier to understand, all paths must be defined relative to the base file.

How it works

When defining any service in your compose.yaml file, you can declare that you are extending another service:

services:
  web:
    extends:
      file: common-services.yml
      service: webapp

This instructs Compose to re-use the configuration for the webapp service defined in the common-services.yaml file. Suppose that common-services.yaml looks like this:

services:
  webapp:
    build: .
    ports:
      - "8000:8000"
    volumes:
      - "/data"

In this case, you get exactly the same result as if you wrote docker-compose.yml with the same build, ports and volumes configuration values defined directly under web.

You can go further and define, or re-define, configuration locally in compose.yaml:

services:
  web:
    extends:
      file: common-services.yml
      service: webapp
    environment:
      - DEBUG=1
    cpu_shares: 5

  important_web:
    extends: web
    cpu_shares: 10

You can also write other services and link your web service to them:

services:
  web:
    extends:
      file: common-services.yml
      service: webapp
    environment:
      - DEBUG=1
    cpu_shares: 5
    depends_on:
      - db
  db:
    image: postgres

Further examples

Example one

Extending an individual service is useful when you have multiple services that have a common configuration. The example below is a Compose app with two services, a web application and a queue worker. Both services use the same codebase and share many configuration options.

The common.yaml file defines the common configuration:

services:
  app:
    build: .
    environment:
      CONFIG_FILE_PATH: /code/config
      API_KEY: xxxyyy
    cpu_shares: 5

The docker-compose.yaml defines the concrete services which use the common configuration:

services:
  webapp:
    extends:
      file: common.yaml
      service: app
    command: /code/run_web_app
    ports:
      - 8080:8080
    depends_on:
      - queue
      - db

  queue_worker:
    extends:
      file: common.yaml
      service: app
    command: /code/run_worker
    depends_on:
      - queue

Example two

Another common use case for extends is running one off or administrative tasks against one or more services in a Compose app. This example demonstrates running a database backup.

The docker-compose.yml defines the base configuration.

services:
  web:
    image: example/my_web_app:latest
    depends_on:
       db

  db:
    image: postgres:latest

docker-compose.admin.yml adds a new service to run the database export or backup.

services:
  dbadmin:
     build: database_admin/
     depends_on:
        - db

To start a normal environment, run docker compose up -d. To run a database backup, include the docker-compose.admin.yml as well.

$ docker compose -f docker-compose.yml -f docker-compose.admin.yml \
  run dbadmin db-backup

Compose extends files in the order they're specified on the command line.

Exceptions and limitations

volumes_from and depends_on are never shared between services using extends. These exceptions exist to avoid implicit dependencies; you always define volumes_from locally. This ensures dependencies between services are clearly visible when reading the current file. Defining these locally also ensures that changes to the referenced file don't break anything.

extends is useful if you only need a single service to be shared and you are familiar with the file you're extending to, so you can to tweak the configuration. But this isn’t an acceptable solution when you want to re-use someone else's unfamiliar configurations and you don’t know about its own dependencies.

Reference information

• extends