Docker Compose'sextends attributelets you share common configurations among different files, or even differentprojects entirely.

Extending services is useful if you have several services that reuse a commonset of configuration options. Withextends you can define a common set ofservice options in one place and refer to it from anywhere. You can refer toanother Compose file and select a service you want to also use in your ownapplication, 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 filesare relative to the base Compose file (i.e. the Compose file in your main-project folder). This is required because extend filesneed not be valid Compose files. Extend files can contain small fragments ofconfiguration. Tracking which fragment of a service is relative to which path isdifficult and confusing, so to keep paths easier to understand, all paths mustbe defined relative to the base file.

How theextends attribute works

Extending services from another file

Take the following example:

services:web:extends:file:common-services.ymlservice:webapp

This instructs Compose to re-use only the properties of thewebapp servicedefined in thecommon-services.yml file. Thewebapp service itself is not part of the final project.

Ifcommon-services.ymllooks like this:

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

You get exactly the same result as if you wrotecompose.yaml with the samebuild,ports, andvolumes configurationvalues defined directly underweb.

To include the servicewebapp in the final project when extending services from another file, you need to explicitly include both services in your current Compose file. For example (this is for illustrative purposes only):

services:web:build:alpinecommand:echoextends:file:common-services.ymlservice:webappwebapp:extends:file:common-services.ymlservice:webapp

Alternatively, you can useinclude.

Extending services within the same file

If you define services in the same Compose file and extend one service from another, both the original service and the extended service will be part of your final configuration. For example:

services:web:build:alpineextends:webappwebapp:environment:-DEBUG=1

Extending services within the same file and from another file

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

services:web:extends:file:common-services.ymlservice:webappenvironment:-DEBUG=1cpu_shares:5important_web:extends:webcpu_shares:10

Additional example

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

Thecommon.yaml file defines the common configuration:

services:app:build:.environment:CONFIG_FILE_PATH:/code/configAPI_KEY:xxxyyycpu_shares:5

Thecompose.yaml defines the concrete services which use the commonconfiguration:

services:webapp:extends:file:common.yamlservice:appcommand:/code/run_web_appports:-8080:8080depends_on:-queue-dbqueue_worker:extends:file:common.yamlservice:appcommand:/code/run_workerdepends_on:-queue

Relative paths

When usingextends with afile attribute which points to another folder, relative pathsdeclared by the service being extended are converted so they still point to thesame file when used by the extending service. This is illustrated in the following example:

Base Compose file:

services:webapp:image:exampleextends:file:../commons/compose.yamlservice:base

Thecommons/compose.yaml file:

services:base:env_file:./container.env

The resulting service refers to the originalcontainer.env filewithin thecommons directory. This can be confirmed withdocker compose configwhich inspects the actual model:

services:webapp:image:exampleenv_file:-../commons/container.env

Reference information

• extends