Add tutorial and reference for extends

[aanand]

Closes#1111 and #1127.

[bfirsh]

Nice. LGTM

cc @moxiegirl

[moxiegirl]

So, there are some awkward constructions in here. Generally, readers use technical documents to perform tasks or gather information. For readers, these activities take place in the present. Therefore, the present tense is appropriate in most cases.

Also the first person plural "We" is awkward and generally avoided. You should instead use "you" to bring the action closer to the reader.

Finally, your walkthrough benefits from steps to make it easier to follow:

https://gist.github.com/moxiegirl/190be92c1aac21835b01

--->
page_title: Extending services in Compose
page_description: How to use Docker Compose's "extends" keyword to share configuration between files and projects
page_keywords: fig, composition, compose, docker, orchestration, documentation, docs

Extending services in Compose

Docker Compose's extends keyword enables sharing of common configurations
among different files, or even different projects entirely. Extending services
is useful if you have several applications that reuse commonly-defined services.
Using extends you can define a service in one place and refer to it from
anywhere.

Alternatively, you can deploy the same application to multiple environments with
a slightly different set of services in each case (or with changes to the
configuration of some services). Moreover, you can do so without copy-pasting
the configuration around.

Understand the extends configuration

When defining any service in docker-compose.yml, you can declare that you are
extending another service like this:

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

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

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

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

You can go further and define (or re-define) configuration locally in
docker-compose.yml:

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

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

web:
extends:
file: common-services.ymlservice: webappenvironment:
- DEBUG=1cpu_shares: 5links:
- dbdb:
image: postgres

For full details on how to use extends, refer to the reference.

Example use case

In this example, you repurpose the example app from the quick start
guide. (If you're not familiar with Compose, it's recommended that
you go through the quick start first.) This example assumes you want to use
Compose both to develop an application locally and then deploy it to a
production environment.

The local and production environments are similar, but there are some
differences. In development, you mount the application code as a volume so that
it can pick up changes; in production, the code should be immutable from the
outside. This ensures it’s not accidentally changed. The development environment
uses a local Redis container, but in production another team manages the Redis
service which is listening at redis-production.example.com.

To configure with extends for this sample, you must:

1. Define the web application as a Docker image and Compose service.

2. Define the development environment in another Compose file.

   • Use the extends to pull in the web service
   • Configure a volume to enable code reloading.
   • Create an additional Redis service for the application to use locally.

3. Define the production environment in a third Compose file.

   In this file, you also use extends to pull in the web service and configure
   it to talk to the external, production Redis service.

Define the web app

Defining the web application requires the following:

1. Create an app.py file.

   This files contains a simple Python application that uses Flask to serve HTTP
   and increments a counter in Redis:

   ```python
   from flask import Flask
   from redis import Redis
   import os
   app = Flask(__name__)
   redis = Redis(host=os.environ['REDIS_HOST'], port=6379)
   @app.route('/')
   def hello():
   redis.incr('hits')
   return 'Hello World! I have been seen %s times.' % redis.get('hits')
   if __name__ == "__main__":
   app.run(host="0.0.0.0", debug=True)
   ```
   

   This code uses a REDIS_HOST environment variable to determine where to find
   Redis.

2. Define the Python dependencies a requirements.txt file.

   flask
   redis
   

3. Create a Dockerfile to build an image containing the app:

   FROM python:2.7 ADD . /code WORKDIR /code RUN pip install -r
   requirements.txt CMD python app.py
   

4. Create a Compose configuration file called common.yml file.

   This configuration defines how to run the app.

   web:
   build: .
   ports:
   - "5000:5000"
   

   Typically, you would have dropped this configuration into a
   docker-compose.yml file, but to use with extends it needs to be in its own
   file.

5. Save a close all the new files.

Define the development environment

Your define your development environment in a docker-compose.yml file:

1. Edit the file and add an extends section.

   This section pulls in the web service from the common.yml file you created
   in the previous section.

   web:
   extends:
   file: common.yml
   service: web
   volumes:
   - .:/code
   links:
   - redis
   environment:
   - REDIS_HOST=redis
   redis:
   image: redis
   

   The new addition defines a web service that:

   • Fetches the base configuration for web out of common.yml
   • Adds volumes and links configuration to the base (common.yml)
     configuration.
   • Sets the REDIS_HOST environment variable to point to the linked redis
     container. This environment uses a stock redis image from the Docker Hub.

2. Run docker-compose up.

   Compose creates, links, and starts a web and redis container linked together.
   It mounts your application code inside the web container.

3. Verify that the code is mounted by changing the message in
   app.py—say, from Hello world! to Hello from Compose!.

   Don't forget to refresh your browser to see your change!

Define the production environment

You are almost done. Now, define your production environment:

1. Create a production.yml file.

   web:
   extends:
   file: common.yml
   service: web
   environment:
   - REDIS_HOST=redis-production.example.com
   

2. Run docker-compose -f production.yml up.

   Compose creates just a web container and configures the Redis connection via
   the REDIS_HOST environment variable. This variable points to the production
   Redis instance.

   Note: If you try to load up the webapp in your browser you'll get an
   error—redis-production.example.com isn't actually a Redis server.

You've now done a basic extends configuration. As your application develops,
you can make any necessary changes to the web service in common.yml. Compose
picks up both the development and production environments when you next run
docker-compose. You don't have to do any copy-and-paste, and you don't have to
manually keep both environments in sync.

Reference

You can use extends on any service together with other configuration keys. It
always expects a dictionary that should always contain two keys: file and
service.

The file key specifies which file to look in. It can be an absolute path or a
relative one—if relative, it's treated as relative to the current file.

The service key specifies the name of the service to extend, for example web or database.

You can extend a service that itself extends another. You can extend indefinitely. Compose does not support circular references and docker-compose returns an error if it encounters them.

Adding and overriding configuration

Compose copies configurations from the original service over to the local one,
except for links and volumes_from. These exceptions exist to avoid
implicit dependencies—you always define links and volumes_from
locally. This ensures dependencies between services are clearly visible when
reading the current file. Defining these locally also ensures changes to the
referenced file don't result in breakage.

If a configuration option is defined in both the original service and the local
service, the local value either _override_s or _extend_s the definition of the
original service. This works differently for other configuration options.

For single-value options like image, command or mem_limit, the new value
replaces the old value. This is the default behaviour - all exceptions are
listed below. In the case of build and image, using one causes Compose to
discard the other.

# original servicebuild: .# local serviceimage: redis# resultimage: redis

# original serviceimage: redis# local servicebuild: .# resultbuild: .

For the multi-value optionsports, expose, external_links, dns and
dns_search, Compose concatenates both sets of values:

# original serviceexpose:
- "3000"# local serviceexpose:
- "4000"
- "5000"# resultexpose:
- "3000"
- "4000"
- "5000"

In the case of environment, Compose "merges" entries together with
locally-defined values taking precedence:

# original serviceenvironment:
- FOO=original
- BAR=original# local serviceenvironment:
- BAR=local
- BAZ=local# resultenvironment:
- FOO=original
- BAR=local
- BAZ=local

Finally, for volumes, Compose "merges" entries together with locally-defined
bindings taking precedence:

# original servicevolumes:
- /original-dir/foo:/foo
- /original-dir/bar:/bar# local servicevolumes:
- /local-dir/bar:/bar
- /local-dir/baz/:baz# resultvolumes:
- /original-dir/foo:/foo
- /local-dir/bar:/bar
- /local-dir/baz/:baz

[aanand]

@moxiegirl Thanks! I've incorporated your changes.

[bfirsh]

LGTM

[aanand]

Closes#1111 and #1127.

[bfirsh]

Nice. LGTM

cc @moxiegirl

[moxiegirl]

So, there are some awkward constructions in here. Generally, readers use technical documents to perform tasks or gather information. For readers, these activities take place in the present. Therefore, the present tense is appropriate in most cases.

Also the first person plural "We" is awkward and generally avoided. You should instead use "you" to bring the action closer to the reader.

Finally, your walkthrough benefits from steps to make it easier to follow:

https://gist.github.com/moxiegirl/190be92c1aac21835b01

--->
page_title: Extending services in Compose
page_description: How to use Docker Compose's "extends" keyword to share configuration between files and projects
page_keywords: fig, composition, compose, docker, orchestration, documentation, docs

Extending services in Compose

Docker Compose's extends keyword enables sharing of common configurations
among different files, or even different projects entirely. Extending services
is useful if you have several applications that reuse commonly-defined services.
Using extends you can define a service in one place and refer to it from
anywhere.

Alternatively, you can deploy the same application to multiple environments with
a slightly different set of services in each case (or with changes to the
configuration of some services). Moreover, you can do so without copy-pasting
the configuration around.

Understand the extends configuration

When defining any service in docker-compose.yml, you can declare that you are
extending another service like this:

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

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

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

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

You can go further and define (or re-define) configuration locally in
docker-compose.yml:

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

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

web:
extends:
file: common-services.ymlservice: webappenvironment:
- DEBUG=1cpu_shares: 5links:
- dbdb:
image: postgres

For full details on how to use extends, refer to the reference.

Example use case

In this example, you repurpose the example app from the quick start
guide. (If you're not familiar with Compose, it's recommended that
you go through the quick start first.) This example assumes you want to use
Compose both to develop an application locally and then deploy it to a
production environment.

The local and production environments are similar, but there are some
differences. In development, you mount the application code as a volume so that
it can pick up changes; in production, the code should be immutable from the
outside. This ensures it’s not accidentally changed. The development environment
uses a local Redis container, but in production another team manages the Redis
service which is listening at redis-production.example.com.

To configure with extends for this sample, you must:

1. Define the web application as a Docker image and Compose service.

2. Define the development environment in another Compose file.

   • Use the extends to pull in the web service
   • Configure a volume to enable code reloading.
   • Create an additional Redis service for the application to use locally.

3. Define the production environment in a third Compose file.

   In this file, you also use extends to pull in the web service and configure
   it to talk to the external, production Redis service.

Define the web app

Defining the web application requires the following:

1. Create an app.py file.

   This files contains a simple Python application that uses Flask to serve HTTP
   and increments a counter in Redis:

   ```python
   from flask import Flask
   from redis import Redis
   import os
   app = Flask(__name__)
   redis = Redis(host=os.environ['REDIS_HOST'], port=6379)
   @app.route('/')
   def hello():
   redis.incr('hits')
   return 'Hello World! I have been seen %s times.' % redis.get('hits')
   if __name__ == "__main__":
   app.run(host="0.0.0.0", debug=True)
   ```
   

   This code uses a REDIS_HOST environment variable to determine where to find
   Redis.

2. Define the Python dependencies a requirements.txt file.

   flask
   redis
   

3. Create a Dockerfile to build an image containing the app:

   FROM python:2.7 ADD . /code WORKDIR /code RUN pip install -r
   requirements.txt CMD python app.py
   

4. Create a Compose configuration file called common.yml file.

   This configuration defines how to run the app.

   web:
   build: .
   ports:
   - "5000:5000"
   

   Typically, you would have dropped this configuration into a
   docker-compose.yml file, but to use with extends it needs to be in its own
   file.

5. Save a close all the new files.

Define the development environment

Your define your development environment in a docker-compose.yml file:

1. Edit the file and add an extends section.

   This section pulls in the web service from the common.yml file you created
   in the previous section.

   web:
   extends:
   file: common.yml
   service: web
   volumes:
   - .:/code
   links:
   - redis
   environment:
   - REDIS_HOST=redis
   redis:
   image: redis
   

   The new addition defines a web service that:

   • Fetches the base configuration for web out of common.yml
   • Adds volumes and links configuration to the base (common.yml)
     configuration.
   • Sets the REDIS_HOST environment variable to point to the linked redis
     container. This environment uses a stock redis image from the Docker Hub.

2. Run docker-compose up.

   Compose creates, links, and starts a web and redis container linked together.
   It mounts your application code inside the web container.

3. Verify that the code is mounted by changing the message in
   app.py—say, from Hello world! to Hello from Compose!.

   Don't forget to refresh your browser to see your change!

Define the production environment

You are almost done. Now, define your production environment:

1. Create a production.yml file.

   web:
   extends:
   file: common.yml
   service: web
   environment:
   - REDIS_HOST=redis-production.example.com
   

2. Run docker-compose -f production.yml up.

   Compose creates just a web container and configures the Redis connection via
   the REDIS_HOST environment variable. This variable points to the production
   Redis instance.

   Note: If you try to load up the webapp in your browser you'll get an
   error—redis-production.example.com isn't actually a Redis server.

You've now done a basic extends configuration. As your application develops,
you can make any necessary changes to the web service in common.yml. Compose
picks up both the development and production environments when you next run
docker-compose. You don't have to do any copy-and-paste, and you don't have to
manually keep both environments in sync.

Reference

You can use extends on any service together with other configuration keys. It
always expects a dictionary that should always contain two keys: file and
service.

The file key specifies which file to look in. It can be an absolute path or a
relative one—if relative, it's treated as relative to the current file.

The service key specifies the name of the service to extend, for example web or database.

You can extend a service that itself extends another. You can extend indefinitely. Compose does not support circular references and docker-compose returns an error if it encounters them.

Adding and overriding configuration

Compose copies configurations from the original service over to the local one,
except for links and volumes_from. These exceptions exist to avoid
implicit dependencies—you always define links and volumes_from
locally. This ensures dependencies between services are clearly visible when
reading the current file. Defining these locally also ensures changes to the
referenced file don't result in breakage.

If a configuration option is defined in both the original service and the local
service, the local value either _override_s or _extend_s the definition of the
original service. This works differently for other configuration options.

For single-value options like image, command or mem_limit, the new value
replaces the old value. This is the default behaviour - all exceptions are
listed below. In the case of build and image, using one causes Compose to
discard the other.

# original servicebuild: .# local serviceimage: redis# resultimage: redis

# original serviceimage: redis# local servicebuild: .# resultbuild: .

For the multi-value optionsports, expose, external_links, dns and
dns_search, Compose concatenates both sets of values:

# original serviceexpose:
- "3000"# local serviceexpose:
- "4000"
- "5000"# resultexpose:
- "3000"
- "4000"
- "5000"

In the case of environment, Compose "merges" entries together with
locally-defined values taking precedence:

# original serviceenvironment:
- FOO=original
- BAR=original# local serviceenvironment:
- BAR=local
- BAZ=local# resultenvironment:
- FOO=original
- BAR=local
- BAZ=local

Finally, for volumes, Compose "merges" entries together with locally-defined
bindings taking precedence:

# original servicevolumes:
- /original-dir/foo:/foo
- /original-dir/bar:/bar# local servicevolumes:
- /local-dir/bar:/bar
- /local-dir/baz/:baz# resultvolumes:
- /original-dir/foo:/foo
- /local-dir/bar:/bar
- /local-dir/baz/:baz

[aanand]

@moxiegirl Thanks! I've incorporated your changes.

[bfirsh]

LGTM

[aanand]

Closes#1111 and #1127.

[bfirsh]

Nice. LGTM

cc @moxiegirl

[moxiegirl]

So, there are some awkward constructions in here. Generally, readers use technical documents to perform tasks or gather information. For readers, these activities take place in the present. Therefore, the present tense is appropriate in most cases.

Also the first person plural "We" is awkward and generally avoided. You should instead use "you" to bring the action closer to the reader.

Finally, your walkthrough benefits from steps to make it easier to follow:

https://gist.github.com/moxiegirl/190be92c1aac21835b01

--->
page_title: Extending services in Compose
page_description: How to use Docker Compose's "extends" keyword to share configuration between files and projects
page_keywords: fig, composition, compose, docker, orchestration, documentation, docs

Extending services in Compose

Docker Compose's extends keyword enables sharing of common configurations
among different files, or even different projects entirely. Extending services
is useful if you have several applications that reuse commonly-defined services.
Using extends you can define a service in one place and refer to it from
anywhere.

Alternatively, you can deploy the same application to multiple environments with
a slightly different set of services in each case (or with changes to the
configuration of some services). Moreover, you can do so without copy-pasting
the configuration around.

Understand the extends configuration

When defining any service in docker-compose.yml, you can declare that you are
extending another service like this:

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

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

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

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

You can go further and define (or re-define) configuration locally in
docker-compose.yml:

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

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

web:
extends:
file: common-services.ymlservice: webappenvironment:
- DEBUG=1cpu_shares: 5links:
- dbdb:
image: postgres

For full details on how to use extends, refer to the reference.

Example use case

In this example, you repurpose the example app from the quick start
guide. (If you're not familiar with Compose, it's recommended that
you go through the quick start first.) This example assumes you want to use
Compose both to develop an application locally and then deploy it to a
production environment.

The local and production environments are similar, but there are some
differences. In development, you mount the application code as a volume so that
it can pick up changes; in production, the code should be immutable from the
outside. This ensures it’s not accidentally changed. The development environment
uses a local Redis container, but in production another team manages the Redis
service which is listening at redis-production.example.com.

To configure with extends for this sample, you must:

1. Define the web application as a Docker image and Compose service.

2. Define the development environment in another Compose file.

   • Use the extends to pull in the web service
   • Configure a volume to enable code reloading.
   • Create an additional Redis service for the application to use locally.

3. Define the production environment in a third Compose file.

   In this file, you also use extends to pull in the web service and configure
   it to talk to the external, production Redis service.

Define the web app

Defining the web application requires the following:

1. Create an app.py file.

   This files contains a simple Python application that uses Flask to serve HTTP
   and increments a counter in Redis:

   ```python
   from flask import Flask
   from redis import Redis
   import os
   app = Flask(__name__)
   redis = Redis(host=os.environ['REDIS_HOST'], port=6379)
   @app.route('/')
   def hello():
   redis.incr('hits')
   return 'Hello World! I have been seen %s times.' % redis.get('hits')
   if __name__ == "__main__":
   app.run(host="0.0.0.0", debug=True)
   ```
   

   This code uses a REDIS_HOST environment variable to determine where to find
   Redis.

2. Define the Python dependencies a requirements.txt file.

   flask
   redis
   

3. Create a Dockerfile to build an image containing the app:

   FROM python:2.7 ADD . /code WORKDIR /code RUN pip install -r
   requirements.txt CMD python app.py
   

4. Create a Compose configuration file called common.yml file.

   This configuration defines how to run the app.

   web:
   build: .
   ports:
   - "5000:5000"
   

   Typically, you would have dropped this configuration into a
   docker-compose.yml file, but to use with extends it needs to be in its own
   file.

5. Save a close all the new files.

Define the development environment

Your define your development environment in a docker-compose.yml file:

1. Edit the file and add an extends section.

   This section pulls in the web service from the common.yml file you created
   in the previous section.

   web:
   extends:
   file: common.yml
   service: web
   volumes:
   - .:/code
   links:
   - redis
   environment:
   - REDIS_HOST=redis
   redis:
   image: redis
   

   The new addition defines a web service that:

   • Fetches the base configuration for web out of common.yml
   • Adds volumes and links configuration to the base (common.yml)
     configuration.
   • Sets the REDIS_HOST environment variable to point to the linked redis
     container. This environment uses a stock redis image from the Docker Hub.

2. Run docker-compose up.

   Compose creates, links, and starts a web and redis container linked together.
   It mounts your application code inside the web container.

3. Verify that the code is mounted by changing the message in
   app.py—say, from Hello world! to Hello from Compose!.

   Don't forget to refresh your browser to see your change!

Define the production environment

You are almost done. Now, define your production environment:

1. Create a production.yml file.

   web:
   extends:
   file: common.yml
   service: web
   environment:
   - REDIS_HOST=redis-production.example.com
   

2. Run docker-compose -f production.yml up.

   Compose creates just a web container and configures the Redis connection via
   the REDIS_HOST environment variable. This variable points to the production
   Redis instance.

   Note: If you try to load up the webapp in your browser you'll get an
   error—redis-production.example.com isn't actually a Redis server.

You've now done a basic extends configuration. As your application develops,
you can make any necessary changes to the web service in common.yml. Compose
picks up both the development and production environments when you next run
docker-compose. You don't have to do any copy-and-paste, and you don't have to
manually keep both environments in sync.

Reference

You can use extends on any service together with other configuration keys. It
always expects a dictionary that should always contain two keys: file and
service.

The file key specifies which file to look in. It can be an absolute path or a
relative one—if relative, it's treated as relative to the current file.

The service key specifies the name of the service to extend, for example web or database.

You can extend a service that itself extends another. You can extend indefinitely. Compose does not support circular references and docker-compose returns an error if it encounters them.

Adding and overriding configuration

Compose copies configurations from the original service over to the local one,
except for links and volumes_from. These exceptions exist to avoid
implicit dependencies—you always define links and volumes_from
locally. This ensures dependencies between services are clearly visible when
reading the current file. Defining these locally also ensures changes to the
referenced file don't result in breakage.

If a configuration option is defined in both the original service and the local
service, the local value either _override_s or _extend_s the definition of the
original service. This works differently for other configuration options.

For single-value options like image, command or mem_limit, the new value
replaces the old value. This is the default behaviour - all exceptions are
listed below. In the case of build and image, using one causes Compose to
discard the other.

# original servicebuild: .# local serviceimage: redis# resultimage: redis

# original serviceimage: redis# local servicebuild: .# resultbuild: .

For the multi-value optionsports, expose, external_links, dns and
dns_search, Compose concatenates both sets of values:

# original serviceexpose:
- "3000"# local serviceexpose:
- "4000"
- "5000"# resultexpose:
- "3000"
- "4000"
- "5000"

In the case of environment, Compose "merges" entries together with
locally-defined values taking precedence:

# original serviceenvironment:
- FOO=original
- BAR=original# local serviceenvironment:
- BAR=local
- BAZ=local# resultenvironment:
- FOO=original
- BAR=local
- BAZ=local

Finally, for volumes, Compose "merges" entries together with locally-defined
bindings taking precedence:

# original servicevolumes:
- /original-dir/foo:/foo
- /original-dir/bar:/bar# local servicevolumes:
- /local-dir/bar:/bar
- /local-dir/baz/:baz# resultvolumes:
- /original-dir/foo:/foo
- /local-dir/bar:/bar
- /local-dir/baz/:baz

[aanand]

@moxiegirl Thanks! I've incorporated your changes.

[bfirsh]

LGTM

[aanand]

Closes#1111 and #1127.

[bfirsh]

Nice. LGTM

cc @moxiegirl

[moxiegirl]

So, there are some awkward constructions in here. Generally, readers use technical documents to perform tasks or gather information. For readers, these activities take place in the present. Therefore, the present tense is appropriate in most cases.

Also the first person plural "We" is awkward and generally avoided. You should instead use "you" to bring the action closer to the reader.

Finally, your walkthrough benefits from steps to make it easier to follow:

https://gist.github.com/moxiegirl/190be92c1aac21835b01

--->
page_title: Extending services in Compose
page_description: How to use Docker Compose's "extends" keyword to share configuration between files and projects
page_keywords: fig, composition, compose, docker, orchestration, documentation, docs

Extending services in Compose

Docker Compose's extends keyword enables sharing of common configurations
among different files, or even different projects entirely. Extending services
is useful if you have several applications that reuse commonly-defined services.
Using extends you can define a service in one place and refer to it from
anywhere.

Alternatively, you can deploy the same application to multiple environments with
a slightly different set of services in each case (or with changes to the
configuration of some services). Moreover, you can do so without copy-pasting
the configuration around.

Understand the extends configuration

When defining any service in docker-compose.yml, you can declare that you are
extending another service like this:

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

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

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

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

You can go further and define (or re-define) configuration locally in
docker-compose.yml:

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

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

web:
extends:
file: common-services.ymlservice: webappenvironment:
- DEBUG=1cpu_shares: 5links:
- dbdb:
image: postgres

For full details on how to use extends, refer to the reference.

Example use case

In this example, you repurpose the example app from the quick start
guide. (If you're not familiar with Compose, it's recommended that
you go through the quick start first.) This example assumes you want to use
Compose both to develop an application locally and then deploy it to a
production environment.

The local and production environments are similar, but there are some
differences. In development, you mount the application code as a volume so that
it can pick up changes; in production, the code should be immutable from the
outside. This ensures it’s not accidentally changed. The development environment
uses a local Redis container, but in production another team manages the Redis
service which is listening at redis-production.example.com.

To configure with extends for this sample, you must:

1. Define the web application as a Docker image and Compose service.

2. Define the development environment in another Compose file.

   • Use the extends to pull in the web service
   • Configure a volume to enable code reloading.
   • Create an additional Redis service for the application to use locally.

3. Define the production environment in a third Compose file.

   In this file, you also use extends to pull in the web service and configure
   it to talk to the external, production Redis service.

Define the web app

Defining the web application requires the following:

1. Create an app.py file.

   This files contains a simple Python application that uses Flask to serve HTTP
   and increments a counter in Redis:

   ```python
   from flask import Flask
   from redis import Redis
   import os
   app = Flask(__name__)
   redis = Redis(host=os.environ['REDIS_HOST'], port=6379)
   @app.route('/')
   def hello():
   redis.incr('hits')
   return 'Hello World! I have been seen %s times.' % redis.get('hits')
   if __name__ == "__main__":
   app.run(host="0.0.0.0", debug=True)
   ```
   

   This code uses a REDIS_HOST environment variable to determine where to find
   Redis.

2. Define the Python dependencies a requirements.txt file.

   flask
   redis
   

3. Create a Dockerfile to build an image containing the app:

   FROM python:2.7 ADD . /code WORKDIR /code RUN pip install -r
   requirements.txt CMD python app.py
   

4. Create a Compose configuration file called common.yml file.

   This configuration defines how to run the app.

   web:
   build: .
   ports:
   - "5000:5000"
   

   Typically, you would have dropped this configuration into a
   docker-compose.yml file, but to use with extends it needs to be in its own
   file.

5. Save a close all the new files.

Define the development environment

Your define your development environment in a docker-compose.yml file:

1. Edit the file and add an extends section.

   This section pulls in the web service from the common.yml file you created
   in the previous section.

   web:
   extends:
   file: common.yml
   service: web
   volumes:
   - .:/code
   links:
   - redis
   environment:
   - REDIS_HOST=redis
   redis:
   image: redis
   

   The new addition defines a web service that:

   • Fetches the base configuration for web out of common.yml
   • Adds volumes and links configuration to the base (common.yml)
     configuration.
   • Sets the REDIS_HOST environment variable to point to the linked redis
     container. This environment uses a stock redis image from the Docker Hub.

2. Run docker-compose up.

   Compose creates, links, and starts a web and redis container linked together.
   It mounts your application code inside the web container.

3. Verify that the code is mounted by changing the message in
   app.py—say, from Hello world! to Hello from Compose!.

   Don't forget to refresh your browser to see your change!

Define the production environment

You are almost done. Now, define your production environment:

1. Create a production.yml file.

   web:
   extends:
   file: common.yml
   service: web
   environment:
   - REDIS_HOST=redis-production.example.com
   

2. Run docker-compose -f production.yml up.

   Compose creates just a web container and configures the Redis connection via
   the REDIS_HOST environment variable. This variable points to the production
   Redis instance.

   Note: If you try to load up the webapp in your browser you'll get an
   error—redis-production.example.com isn't actually a Redis server.

You've now done a basic extends configuration. As your application develops,
you can make any necessary changes to the web service in common.yml. Compose
picks up both the development and production environments when you next run
docker-compose. You don't have to do any copy-and-paste, and you don't have to
manually keep both environments in sync.

Reference

You can use extends on any service together with other configuration keys. It
always expects a dictionary that should always contain two keys: file and
service.

The file key specifies which file to look in. It can be an absolute path or a
relative one—if relative, it's treated as relative to the current file.

The service key specifies the name of the service to extend, for example web or database.

You can extend a service that itself extends another. You can extend indefinitely. Compose does not support circular references and docker-compose returns an error if it encounters them.

Adding and overriding configuration

Compose copies configurations from the original service over to the local one,
except for links and volumes_from. These exceptions exist to avoid
implicit dependencies—you always define links and volumes_from
locally. This ensures dependencies between services are clearly visible when
reading the current file. Defining these locally also ensures changes to the
referenced file don't result in breakage.

If a configuration option is defined in both the original service and the local
service, the local value either _override_s or _extend_s the definition of the
original service. This works differently for other configuration options.

For single-value options like image, command or mem_limit, the new value
replaces the old value. This is the default behaviour - all exceptions are
listed below. In the case of build and image, using one causes Compose to
discard the other.

# original servicebuild: .# local serviceimage: redis# resultimage: redis

# original serviceimage: redis# local servicebuild: .# resultbuild: .

For the multi-value optionsports, expose, external_links, dns and
dns_search, Compose concatenates both sets of values:

# original serviceexpose:
- "3000"# local serviceexpose:
- "4000"
- "5000"# resultexpose:
- "3000"
- "4000"
- "5000"

In the case of environment, Compose "merges" entries together with
locally-defined values taking precedence:

# original serviceenvironment:
- FOO=original
- BAR=original# local serviceenvironment:
- BAR=local
- BAZ=local# resultenvironment:
- FOO=original
- BAR=local
- BAZ=local

Finally, for volumes, Compose "merges" entries together with locally-defined
bindings taking precedence:

# original servicevolumes:
- /original-dir/foo:/foo
- /original-dir/bar:/bar# local servicevolumes:
- /local-dir/bar:/bar
- /local-dir/baz/:baz# resultvolumes:
- /original-dir/foo:/foo
- /local-dir/bar:/bar
- /local-dir/baz/:baz

[aanand]

@moxiegirl Thanks! I've incorporated your changes.

[bfirsh]

LGTM

[aanand]

Closes#1111 and #1127.

[bfirsh]

Nice. LGTM

cc @moxiegirl

[moxiegirl]

So, there are some awkward constructions in here. Generally, readers use technical documents to perform tasks or gather information. For readers, these activities take place in the present. Therefore, the present tense is appropriate in most cases.

Also the first person plural "We" is awkward and generally avoided. You should instead use "you" to bring the action closer to the reader.

Finally, your walkthrough benefits from steps to make it easier to follow:

https://gist.github.com/moxiegirl/190be92c1aac21835b01

--->
page_title: Extending services in Compose
page_description: How to use Docker Compose's "extends" keyword to share configuration between files and projects
page_keywords: fig, composition, compose, docker, orchestration, documentation, docs

Extending services in Compose

Docker Compose's extends keyword enables sharing of common configurations
among different files, or even different projects entirely. Extending services
is useful if you have several applications that reuse commonly-defined services.
Using extends you can define a service in one place and refer to it from
anywhere.

Alternatively, you can deploy the same application to multiple environments with
a slightly different set of services in each case (or with changes to the
configuration of some services). Moreover, you can do so without copy-pasting
the configuration around.

Understand the extends configuration

When defining any service in docker-compose.yml, you can declare that you are
extending another service like this:

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

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

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

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

You can go further and define (or re-define) configuration locally in
docker-compose.yml:

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

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

web:
extends:
file: common-services.ymlservice: webappenvironment:
- DEBUG=1cpu_shares: 5links:
- dbdb:
image: postgres

For full details on how to use extends, refer to the reference.

Example use case

In this example, you repurpose the example app from the quick start
guide. (If you're not familiar with Compose, it's recommended that
you go through the quick start first.) This example assumes you want to use
Compose both to develop an application locally and then deploy it to a
production environment.

The local and production environments are similar, but there are some
differences. In development, you mount the application code as a volume so that
it can pick up changes; in production, the code should be immutable from the
outside. This ensures it’s not accidentally changed. The development environment
uses a local Redis container, but in production another team manages the Redis
service which is listening at redis-production.example.com.

To configure with extends for this sample, you must:

1. Define the web application as a Docker image and Compose service.

2. Define the development environment in another Compose file.

   • Use the extends to pull in the web service
   • Configure a volume to enable code reloading.
   • Create an additional Redis service for the application to use locally.

3. Define the production environment in a third Compose file.

   In this file, you also use extends to pull in the web service and configure
   it to talk to the external, production Redis service.

Define the web app

Defining the web application requires the following:

1. Create an app.py file.

   This files contains a simple Python application that uses Flask to serve HTTP
   and increments a counter in Redis:

   ```python
   from flask import Flask
   from redis import Redis
   import os
   app = Flask(__name__)
   redis = Redis(host=os.environ['REDIS_HOST'], port=6379)
   @app.route('/')
   def hello():
   redis.incr('hits')
   return 'Hello World! I have been seen %s times.' % redis.get('hits')
   if __name__ == "__main__":
   app.run(host="0.0.0.0", debug=True)
   ```
   

   This code uses a REDIS_HOST environment variable to determine where to find
   Redis.

2. Define the Python dependencies a requirements.txt file.

   flask
   redis
   

3. Create a Dockerfile to build an image containing the app:

   FROM python:2.7 ADD . /code WORKDIR /code RUN pip install -r
   requirements.txt CMD python app.py
   

4. Create a Compose configuration file called common.yml file.

   This configuration defines how to run the app.

   web:
   build: .
   ports:
   - "5000:5000"
   

   Typically, you would have dropped this configuration into a
   docker-compose.yml file, but to use with extends it needs to be in its own
   file.

5. Save a close all the new files.

Define the development environment

Your define your development environment in a docker-compose.yml file:

1. Edit the file and add an extends section.

   This section pulls in the web service from the common.yml file you created
   in the previous section.

   web:
   extends:
   file: common.yml
   service: web
   volumes:
   - .:/code
   links:
   - redis
   environment:
   - REDIS_HOST=redis
   redis:
   image: redis
   

   The new addition defines a web service that:

   • Fetches the base configuration for web out of common.yml
   • Adds volumes and links configuration to the base (common.yml)
     configuration.
   • Sets the REDIS_HOST environment variable to point to the linked redis
     container. This environment uses a stock redis image from the Docker Hub.

2. Run docker-compose up.

   Compose creates, links, and starts a web and redis container linked together.
   It mounts your application code inside the web container.

3. Verify that the code is mounted by changing the message in
   app.py—say, from Hello world! to Hello from Compose!.

   Don't forget to refresh your browser to see your change!

Define the production environment

You are almost done. Now, define your production environment:

1. Create a production.yml file.

   web:
   extends:
   file: common.yml
   service: web
   environment:
   - REDIS_HOST=redis-production.example.com
   

2. Run docker-compose -f production.yml up.

   Compose creates just a web container and configures the Redis connection via
   the REDIS_HOST environment variable. This variable points to the production
   Redis instance.

   Note: If you try to load up the webapp in your browser you'll get an
   error—redis-production.example.com isn't actually a Redis server.

You've now done a basic extends configuration. As your application develops,
you can make any necessary changes to the web service in common.yml. Compose
picks up both the development and production environments when you next run
docker-compose. You don't have to do any copy-and-paste, and you don't have to
manually keep both environments in sync.

Reference

You can use extends on any service together with other configuration keys. It
always expects a dictionary that should always contain two keys: file and
service.

The file key specifies which file to look in. It can be an absolute path or a
relative one—if relative, it's treated as relative to the current file.

The service key specifies the name of the service to extend, for example web or database.

You can extend a service that itself extends another. You can extend indefinitely. Compose does not support circular references and docker-compose returns an error if it encounters them.

Adding and overriding configuration

Compose copies configurations from the original service over to the local one,
except for links and volumes_from. These exceptions exist to avoid
implicit dependencies—you always define links and volumes_from
locally. This ensures dependencies between services are clearly visible when
reading the current file. Defining these locally also ensures changes to the
referenced file don't result in breakage.

If a configuration option is defined in both the original service and the local
service, the local value either _override_s or _extend_s the definition of the
original service. This works differently for other configuration options.

For single-value options like image, command or mem_limit, the new value
replaces the old value. This is the default behaviour - all exceptions are
listed below. In the case of build and image, using one causes Compose to
discard the other.

# original servicebuild: .# local serviceimage: redis# resultimage: redis

# original serviceimage: redis# local servicebuild: .# resultbuild: .

For the multi-value optionsports, expose, external_links, dns and
dns_search, Compose concatenates both sets of values:

# original serviceexpose:
- "3000"# local serviceexpose:
- "4000"
- "5000"# resultexpose:
- "3000"
- "4000"
- "5000"

In the case of environment, Compose "merges" entries together with
locally-defined values taking precedence:

# original serviceenvironment:
- FOO=original
- BAR=original# local serviceenvironment:
- BAR=local
- BAZ=local# resultenvironment:
- FOO=original
- BAR=local
- BAZ=local

Finally, for volumes, Compose "merges" entries together with locally-defined
bindings taking precedence:

# original servicevolumes:
- /original-dir/foo:/foo
- /original-dir/bar:/bar# local servicevolumes:
- /local-dir/bar:/bar
- /local-dir/baz/:baz# resultvolumes:
- /original-dir/foo:/foo
- /local-dir/bar:/bar
- /local-dir/baz/:baz

[aanand]

@moxiegirl Thanks! I've incorporated your changes.

[bfirsh]

LGTM

[aanand]

Closes#1111 and #1127.

[bfirsh]

Nice. LGTM

cc @moxiegirl

[moxiegirl]

So, there are some awkward constructions in here. Generally, readers use technical documents to perform tasks or gather information. For readers, these activities take place in the present. Therefore, the present tense is appropriate in most cases.

Also the first person plural "We" is awkward and generally avoided. You should instead use "you" to bring the action closer to the reader.

Finally, your walkthrough benefits from steps to make it easier to follow:

https://gist.github.com/moxiegirl/190be92c1aac21835b01

--->
page_title: Extending services in Compose
page_description: How to use Docker Compose's "extends" keyword to share configuration between files and projects
page_keywords: fig, composition, compose, docker, orchestration, documentation, docs

Extending services in Compose

Docker Compose's extends keyword enables sharing of common configurations
among different files, or even different projects entirely. Extending services
is useful if you have several applications that reuse commonly-defined services.
Using extends you can define a service in one place and refer to it from
anywhere.

Alternatively, you can deploy the same application to multiple environments with
a slightly different set of services in each case (or with changes to the
configuration of some services). Moreover, you can do so without copy-pasting
the configuration around.

Understand the extends configuration

When defining any service in docker-compose.yml, you can declare that you are
extending another service like this:

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

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

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

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

You can go further and define (or re-define) configuration locally in
docker-compose.yml:

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

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

web:
extends:
file: common-services.ymlservice: webappenvironment:
- DEBUG=1cpu_shares: 5links:
- dbdb:
image: postgres

For full details on how to use extends, refer to the reference.

Example use case

In this example, you repurpose the example app from the quick start
guide. (If you're not familiar with Compose, it's recommended that
you go through the quick start first.) This example assumes you want to use
Compose both to develop an application locally and then deploy it to a
production environment.

The local and production environments are similar, but there are some
differences. In development, you mount the application code as a volume so that
it can pick up changes; in production, the code should be immutable from the
outside. This ensures it’s not accidentally changed. The development environment
uses a local Redis container, but in production another team manages the Redis
service which is listening at redis-production.example.com.

To configure with extends for this sample, you must:

1. Define the web application as a Docker image and Compose service.

2. Define the development environment in another Compose file.

   • Use the extends to pull in the web service
   • Configure a volume to enable code reloading.
   • Create an additional Redis service for the application to use locally.

3. Define the production environment in a third Compose file.

   In this file, you also use extends to pull in the web service and configure
   it to talk to the external, production Redis service.

Define the web app

Defining the web application requires the following:

1. Create an app.py file.

   This files contains a simple Python application that uses Flask to serve HTTP
   and increments a counter in Redis:

   ```python
   from flask import Flask
   from redis import Redis
   import os
   app = Flask(__name__)
   redis = Redis(host=os.environ['REDIS_HOST'], port=6379)
   @app.route('/')
   def hello():
   redis.incr('hits')
   return 'Hello World! I have been seen %s times.' % redis.get('hits')
   if __name__ == "__main__":
   app.run(host="0.0.0.0", debug=True)
   ```
   

   This code uses a REDIS_HOST environment variable to determine where to find
   Redis.

2. Define the Python dependencies a requirements.txt file.

   flask
   redis
   

3. Create a Dockerfile to build an image containing the app:

   FROM python:2.7 ADD . /code WORKDIR /code RUN pip install -r
   requirements.txt CMD python app.py
   

4. Create a Compose configuration file called common.yml file.

   This configuration defines how to run the app.

   web:
   build: .
   ports:
   - "5000:5000"
   

   Typically, you would have dropped this configuration into a
   docker-compose.yml file, but to use with extends it needs to be in its own
   file.

5. Save a close all the new files.

Define the development environment

Your define your development environment in a docker-compose.yml file:

1. Edit the file and add an extends section.

   This section pulls in the web service from the common.yml file you created
   in the previous section.

   web:
   extends:
   file: common.yml
   service: web
   volumes:
   - .:/code
   links:
   - redis
   environment:
   - REDIS_HOST=redis
   redis:
   image: redis
   

   The new addition defines a web service that:

   • Fetches the base configuration for web out of common.yml
   • Adds volumes and links configuration to the base (common.yml)
     configuration.
   • Sets the REDIS_HOST environment variable to point to the linked redis
     container. This environment uses a stock redis image from the Docker Hub.

2. Run docker-compose up.

   Compose creates, links, and starts a web and redis container linked together.
   It mounts your application code inside the web container.

3. Verify that the code is mounted by changing the message in
   app.py—say, from Hello world! to Hello from Compose!.

   Don't forget to refresh your browser to see your change!

Define the production environment

You are almost done. Now, define your production environment:

1. Create a production.yml file.

   web:
   extends:
   file: common.yml
   service: web
   environment:
   - REDIS_HOST=redis-production.example.com
   

2. Run docker-compose -f production.yml up.

   Compose creates just a web container and configures the Redis connection via
   the REDIS_HOST environment variable. This variable points to the production
   Redis instance.

   Note: If you try to load up the webapp in your browser you'll get an
   error—redis-production.example.com isn't actually a Redis server.

You've now done a basic extends configuration. As your application develops,
you can make any necessary changes to the web service in common.yml. Compose
picks up both the development and production environments when you next run
docker-compose. You don't have to do any copy-and-paste, and you don't have to
manually keep both environments in sync.

Reference

You can use extends on any service together with other configuration keys. It
always expects a dictionary that should always contain two keys: file and
service.

The file key specifies which file to look in. It can be an absolute path or a
relative one—if relative, it's treated as relative to the current file.

The service key specifies the name of the service to extend, for example web or database.

You can extend a service that itself extends another. You can extend indefinitely. Compose does not support circular references and docker-compose returns an error if it encounters them.

Adding and overriding configuration

Compose copies configurations from the original service over to the local one,
except for links and volumes_from. These exceptions exist to avoid
implicit dependencies—you always define links and volumes_from
locally. This ensures dependencies between services are clearly visible when
reading the current file. Defining these locally also ensures changes to the
referenced file don't result in breakage.

If a configuration option is defined in both the original service and the local
service, the local value either _override_s or _extend_s the definition of the
original service. This works differently for other configuration options.

For single-value options like image, command or mem_limit, the new value
replaces the old value. This is the default behaviour - all exceptions are
listed below. In the case of build and image, using one causes Compose to
discard the other.

# original servicebuild: .# local serviceimage: redis# resultimage: redis

# original serviceimage: redis# local servicebuild: .# resultbuild: .

For the multi-value optionsports, expose, external_links, dns and
dns_search, Compose concatenates both sets of values:

# original serviceexpose:
- "3000"# local serviceexpose:
- "4000"
- "5000"# resultexpose:
- "3000"
- "4000"
- "5000"

In the case of environment, Compose "merges" entries together with
locally-defined values taking precedence:

# original serviceenvironment:
- FOO=original
- BAR=original# local serviceenvironment:
- BAR=local
- BAZ=local# resultenvironment:
- FOO=original
- BAR=local
- BAZ=local

Finally, for volumes, Compose "merges" entries together with locally-defined
bindings taking precedence:

# original servicevolumes:
- /original-dir/foo:/foo
- /original-dir/bar:/bar# local servicevolumes:
- /local-dir/bar:/bar
- /local-dir/baz/:baz# resultvolumes:
- /original-dir/foo:/foo
- /local-dir/bar:/bar
- /local-dir/baz/:baz

[aanand]

@moxiegirl Thanks! I've incorporated your changes.

[bfirsh]

LGTM

[aanand]

Closes#1111 and #1127.

[bfirsh]

Nice. LGTM

cc @moxiegirl

[moxiegirl]

So, there are some awkward constructions in here. Generally, readers use technical documents to perform tasks or gather information. For readers, these activities take place in the present. Therefore, the present tense is appropriate in most cases.

Also the first person plural "We" is awkward and generally avoided. You should instead use "you" to bring the action closer to the reader.

Finally, your walkthrough benefits from steps to make it easier to follow:

https://gist.github.com/moxiegirl/190be92c1aac21835b01

--->
page_title: Extending services in Compose
page_description: How to use Docker Compose's "extends" keyword to share configuration between files and projects
page_keywords: fig, composition, compose, docker, orchestration, documentation, docs

Extending services in Compose

Docker Compose's extends keyword enables sharing of common configurations
among different files, or even different projects entirely. Extending services
is useful if you have several applications that reuse commonly-defined services.
Using extends you can define a service in one place and refer to it from
anywhere.

Alternatively, you can deploy the same application to multiple environments with
a slightly different set of services in each case (or with changes to the
configuration of some services). Moreover, you can do so without copy-pasting
the configuration around.

Understand the extends configuration

When defining any service in docker-compose.yml, you can declare that you are
extending another service like this:

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

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

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

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

You can go further and define (or re-define) configuration locally in
docker-compose.yml:

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

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

web:
extends:
file: common-services.ymlservice: webappenvironment:
- DEBUG=1cpu_shares: 5links:
- dbdb:
image: postgres

For full details on how to use extends, refer to the reference.

Example use case

In this example, you repurpose the example app from the quick start
guide. (If you're not familiar with Compose, it's recommended that
you go through the quick start first.) This example assumes you want to use
Compose both to develop an application locally and then deploy it to a
production environment.

The local and production environments are similar, but there are some
differences. In development, you mount the application code as a volume so that
it can pick up changes; in production, the code should be immutable from the
outside. This ensures it’s not accidentally changed. The development environment
uses a local Redis container, but in production another team manages the Redis
service which is listening at redis-production.example.com.

To configure with extends for this sample, you must:

1. Define the web application as a Docker image and Compose service.

2. Define the development environment in another Compose file.

   • Use the extends to pull in the web service
   • Configure a volume to enable code reloading.
   • Create an additional Redis service for the application to use locally.

3. Define the production environment in a third Compose file.

   In this file, you also use extends to pull in the web service and configure
   it to talk to the external, production Redis service.

Define the web app

Defining the web application requires the following:

1. Create an app.py file.

   This files contains a simple Python application that uses Flask to serve HTTP
   and increments a counter in Redis:

   ```python
   from flask import Flask
   from redis import Redis
   import os
   app = Flask(__name__)
   redis = Redis(host=os.environ['REDIS_HOST'], port=6379)
   @app.route('/')
   def hello():
   redis.incr('hits')
   return 'Hello World! I have been seen %s times.' % redis.get('hits')
   if __name__ == "__main__":
   app.run(host="0.0.0.0", debug=True)
   ```
   

   This code uses a REDIS_HOST environment variable to determine where to find
   Redis.

2. Define the Python dependencies a requirements.txt file.

   flask
   redis
   

3. Create a Dockerfile to build an image containing the app:

   FROM python:2.7 ADD . /code WORKDIR /code RUN pip install -r
   requirements.txt CMD python app.py
   

4. Create a Compose configuration file called common.yml file.

   This configuration defines how to run the app.

   web:
   build: .
   ports:
   - "5000:5000"
   

   Typically, you would have dropped this configuration into a
   docker-compose.yml file, but to use with extends it needs to be in its own
   file.

5. Save a close all the new files.

Define the development environment

Your define your development environment in a docker-compose.yml file:

1. Edit the file and add an extends section.

   This section pulls in the web service from the common.yml file you created
   in the previous section.

   web:
   extends:
   file: common.yml
   service: web
   volumes:
   - .:/code
   links:
   - redis
   environment:
   - REDIS_HOST=redis
   redis:
   image: redis
   

   The new addition defines a web service that:

   • Fetches the base configuration for web out of common.yml
   • Adds volumes and links configuration to the base (common.yml)
     configuration.
   • Sets the REDIS_HOST environment variable to point to the linked redis
     container. This environment uses a stock redis image from the Docker Hub.

2. Run docker-compose up.

   Compose creates, links, and starts a web and redis container linked together.
   It mounts your application code inside the web container.

3. Verify that the code is mounted by changing the message in
   app.py—say, from Hello world! to Hello from Compose!.

   Don't forget to refresh your browser to see your change!

Define the production environment

You are almost done. Now, define your production environment:

1. Create a production.yml file.

   web:
   extends:
   file: common.yml
   service: web
   environment:
   - REDIS_HOST=redis-production.example.com
   

2. Run docker-compose -f production.yml up.

   Compose creates just a web container and configures the Redis connection via
   the REDIS_HOST environment variable. This variable points to the production
   Redis instance.

   Note: If you try to load up the webapp in your browser you'll get an
   error—redis-production.example.com isn't actually a Redis server.

You've now done a basic extends configuration. As your application develops,
you can make any necessary changes to the web service in common.yml. Compose
picks up both the development and production environments when you next run
docker-compose. You don't have to do any copy-and-paste, and you don't have to
manually keep both environments in sync.

Reference

You can use extends on any service together with other configuration keys. It
always expects a dictionary that should always contain two keys: file and
service.

The file key specifies which file to look in. It can be an absolute path or a
relative one—if relative, it's treated as relative to the current file.

The service key specifies the name of the service to extend, for example web or database.

You can extend a service that itself extends another. You can extend indefinitely. Compose does not support circular references and docker-compose returns an error if it encounters them.

Adding and overriding configuration

Compose copies configurations from the original service over to the local one,
except for links and volumes_from. These exceptions exist to avoid
implicit dependencies—you always define links and volumes_from
locally. This ensures dependencies between services are clearly visible when
reading the current file. Defining these locally also ensures changes to the
referenced file don't result in breakage.

If a configuration option is defined in both the original service and the local
service, the local value either _override_s or _extend_s the definition of the
original service. This works differently for other configuration options.

For single-value options like image, command or mem_limit, the new value
replaces the old value. This is the default behaviour - all exceptions are
listed below. In the case of build and image, using one causes Compose to
discard the other.

# original servicebuild: .# local serviceimage: redis# resultimage: redis

# original serviceimage: redis# local servicebuild: .# resultbuild: .

For the multi-value optionsports, expose, external_links, dns and
dns_search, Compose concatenates both sets of values:

# original serviceexpose:
- "3000"# local serviceexpose:
- "4000"
- "5000"# resultexpose:
- "3000"
- "4000"
- "5000"

In the case of environment, Compose "merges" entries together with
locally-defined values taking precedence:

# original serviceenvironment:
- FOO=original
- BAR=original# local serviceenvironment:
- BAR=local
- BAZ=local# resultenvironment:
- FOO=original
- BAR=local
- BAZ=local

Finally, for volumes, Compose "merges" entries together with locally-defined
bindings taking precedence:

# original servicevolumes:
- /original-dir/foo:/foo
- /original-dir/bar:/bar# local servicevolumes:
- /local-dir/bar:/bar
- /local-dir/baz/:baz# resultvolumes:
- /original-dir/foo:/foo
- /local-dir/bar:/bar
- /local-dir/baz/:baz

[aanand]

@moxiegirl Thanks! I've incorporated your changes.

[bfirsh]

LGTM

[aanand]

Closes#1111 and #1127.

[bfirsh]

Nice. LGTM

cc @moxiegirl

[moxiegirl]

So, there are some awkward constructions in here. Generally, readers use technical documents to perform tasks or gather information. For readers, these activities take place in the present. Therefore, the present tense is appropriate in most cases.

Also the first person plural "We" is awkward and generally avoided. You should instead use "you" to bring the action closer to the reader.

Finally, your walkthrough benefits from steps to make it easier to follow:

https://gist.github.com/moxiegirl/190be92c1aac21835b01

--->
page_title: Extending services in Compose
page_description: How to use Docker Compose's "extends" keyword to share configuration between files and projects
page_keywords: fig, composition, compose, docker, orchestration, documentation, docs

Extending services in Compose

Docker Compose's extends keyword enables sharing of common configurations
among different files, or even different projects entirely. Extending services
is useful if you have several applications that reuse commonly-defined services.
Using extends you can define a service in one place and refer to it from
anywhere.

Alternatively, you can deploy the same application to multiple environments with
a slightly different set of services in each case (or with changes to the
configuration of some services). Moreover, you can do so without copy-pasting
the configuration around.

Understand the extends configuration

When defining any service in docker-compose.yml, you can declare that you are
extending another service like this:

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

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

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

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

You can go further and define (or re-define) configuration locally in
docker-compose.yml:

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

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

web:
extends:
file: common-services.ymlservice: webappenvironment:
- DEBUG=1cpu_shares: 5links:
- dbdb:
image: postgres

For full details on how to use extends, refer to the reference.

Example use case

In this example, you repurpose the example app from the quick start
guide. (If you're not familiar with Compose, it's recommended that
you go through the quick start first.) This example assumes you want to use
Compose both to develop an application locally and then deploy it to a
production environment.

The local and production environments are similar, but there are some
differences. In development, you mount the application code as a volume so that
it can pick up changes; in production, the code should be immutable from the
outside. This ensures it’s not accidentally changed. The development environment
uses a local Redis container, but in production another team manages the Redis
service which is listening at redis-production.example.com.

To configure with extends for this sample, you must:

1. Define the web application as a Docker image and Compose service.

2. Define the development environment in another Compose file.

   • Use the extends to pull in the web service
   • Configure a volume to enable code reloading.
   • Create an additional Redis service for the application to use locally.

3. Define the production environment in a third Compose file.

   In this file, you also use extends to pull in the web service and configure
   it to talk to the external, production Redis service.

Define the web app

Defining the web application requires the following:

1. Create an app.py file.

   This files contains a simple Python application that uses Flask to serve HTTP
   and increments a counter in Redis:

   ```python
   from flask import Flask
   from redis import Redis
   import os
   app = Flask(__name__)
   redis = Redis(host=os.environ['REDIS_HOST'], port=6379)
   @app.route('/')
   def hello():
   redis.incr('hits')
   return 'Hello World! I have been seen %s times.' % redis.get('hits')
   if __name__ == "__main__":
   app.run(host="0.0.0.0", debug=True)
   ```
   

   This code uses a REDIS_HOST environment variable to determine where to find
   Redis.

2. Define the Python dependencies a requirements.txt file.

   flask
   redis
   

3. Create a Dockerfile to build an image containing the app:

   FROM python:2.7 ADD . /code WORKDIR /code RUN pip install -r
   requirements.txt CMD python app.py
   

4. Create a Compose configuration file called common.yml file.

   This configuration defines how to run the app.

   web:
   build: .
   ports:
   - "5000:5000"
   

   Typically, you would have dropped this configuration into a
   docker-compose.yml file, but to use with extends it needs to be in its own
   file.

5. Save a close all the new files.

Define the development environment

Your define your development environment in a docker-compose.yml file:

1. Edit the file and add an extends section.

   This section pulls in the web service from the common.yml file you created
   in the previous section.

   web:
   extends:
   file: common.yml
   service: web
   volumes:
   - .:/code
   links:
   - redis
   environment:
   - REDIS_HOST=redis
   redis:
   image: redis
   

   The new addition defines a web service that:

   • Fetches the base configuration for web out of common.yml
   • Adds volumes and links configuration to the base (common.yml)
     configuration.
   • Sets the REDIS_HOST environment variable to point to the linked redis
     container. This environment uses a stock redis image from the Docker Hub.

2. Run docker-compose up.

   Compose creates, links, and starts a web and redis container linked together.
   It mounts your application code inside the web container.

3. Verify that the code is mounted by changing the message in
   app.py—say, from Hello world! to Hello from Compose!.

   Don't forget to refresh your browser to see your change!

Define the production environment

You are almost done. Now, define your production environment:

1. Create a production.yml file.

   web:
   extends:
   file: common.yml
   service: web
   environment:
   - REDIS_HOST=redis-production.example.com
   

2. Run docker-compose -f production.yml up.

   Compose creates just a web container and configures the Redis connection via
   the REDIS_HOST environment variable. This variable points to the production
   Redis instance.

   Note: If you try to load up the webapp in your browser you'll get an
   error—redis-production.example.com isn't actually a Redis server.

You've now done a basic extends configuration. As your application develops,
you can make any necessary changes to the web service in common.yml. Compose
picks up both the development and production environments when you next run
docker-compose. You don't have to do any copy-and-paste, and you don't have to
manually keep both environments in sync.

Reference

You can use extends on any service together with other configuration keys. It
always expects a dictionary that should always contain two keys: file and
service.

The file key specifies which file to look in. It can be an absolute path or a
relative one—if relative, it's treated as relative to the current file.

The service key specifies the name of the service to extend, for example web or database.

You can extend a service that itself extends another. You can extend indefinitely. Compose does not support circular references and docker-compose returns an error if it encounters them.

Adding and overriding configuration

Compose copies configurations from the original service over to the local one,
except for links and volumes_from. These exceptions exist to avoid
implicit dependencies—you always define links and volumes_from
locally. This ensures dependencies between services are clearly visible when
reading the current file. Defining these locally also ensures changes to the
referenced file don't result in breakage.

If a configuration option is defined in both the original service and the local
service, the local value either _override_s or _extend_s the definition of the
original service. This works differently for other configuration options.

For single-value options like image, command or mem_limit, the new value
replaces the old value. This is the default behaviour - all exceptions are
listed below. In the case of build and image, using one causes Compose to
discard the other.

# original servicebuild: .# local serviceimage: redis# resultimage: redis

# original serviceimage: redis# local servicebuild: .# resultbuild: .

For the multi-value optionsports, expose, external_links, dns and
dns_search, Compose concatenates both sets of values:

# original serviceexpose:
- "3000"# local serviceexpose:
- "4000"
- "5000"# resultexpose:
- "3000"
- "4000"
- "5000"

In the case of environment, Compose "merges" entries together with
locally-defined values taking precedence:

# original serviceenvironment:
- FOO=original
- BAR=original# local serviceenvironment:
- BAR=local
- BAZ=local# resultenvironment:
- FOO=original
- BAR=local
- BAZ=local

Finally, for volumes, Compose "merges" entries together with locally-defined
bindings taking precedence:

# original servicevolumes:
- /original-dir/foo:/foo
- /original-dir/bar:/bar# local servicevolumes:
- /local-dir/bar:/bar
- /local-dir/baz/:baz# resultvolumes:
- /original-dir/foo:/foo
- /local-dir/bar:/bar
- /local-dir/baz/:baz

[aanand]

@moxiegirl Thanks! I've incorporated your changes.

[bfirsh]

LGTM