Remove duplication from extends docs.

Start restructuring extends docs in preparation for adding documentation about using multiple compose files.

Signed-off-by: Daniel Nephin <[email protected]>

docs/compose-file.md

@@ -168,44 +168,29 @@ accessible to linked services. Only the internal port can be specified.
 Extend another service, in the current file or another, optionally overriding
 configuration.
 
-Here's a simple example. Suppose we have 2 files - **common.yml** and
-**development.yml**. We can use `extends` to define a service in
-**development.yml** which uses configuration defined in **common.yml**:
+You can use `extends` on any service together with other configuration keys.
+The value must be a dictionary with the key: `service` and may optionally have
+the `file` key.
 
-**common.yml**
+    extends:
+      file: common.yml
+      service: webapp
 
-    webapp:
-      build: ./webapp
-      environment:
-        - DEBUG=false
-        - SEND_EMAILS=false
+The `file` key specifies the location of a Compose configuration file defining
+the service which is being extended. The `file` value can be an absolute or
+relative path. If you specify a relative path, Docker Compose treats it as
+relative to the location of the current file. If you don't specify a `file`,
+Compose looks in the current configuration file.
 
-**development.yml**
+The `service` key specifies the name of the service to extend, for example `web`
+or `database`.
 
-    web:
-      extends:
-        file: common.yml
-        service: webapp
-      ports:
-        - "8000:8000"
-      links:
-        - db
-      environment:
-        - DEBUG=true
-    db:
-      image: postgres
-
-Here, the `web` service in **development.yml** inherits the configuration of
-the `webapp` service in **common.yml** - the `build` and `environment` keys -
-and adds `ports` and `links` configuration. It overrides one of the defined
-environment variables (DEBUG) with a new value, and the other one
-(SEND_EMAILS) is left untouched.
-
-The `file` key is optional, if it is not set then Compose will look for the
-service within the current file.
+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 one.
 
-For more on `extends`, see the [tutorial](extends.md#example) and
-[reference](extends.md#reference).
+For more on `extends`, see the
+[the extends documentation](extends.md#extending-services).
 
 ### external_links
 

docs/extends.md

@@ -10,20 +10,29 @@ weight=2
 <![end-metadata]-->
 
 
-## Extending services in Compose
+## Extending services and Compose files
+
+Compose supports two ways to sharing common configuration and
+extend a service with that shared configuration.
+
+1. Extending individual services with [the `extends` field](#extending-services)
+2. Extending entire compositions by
+   [exnteding compose files](#extending-compose-files)
+
+### Extending services
 
 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.
+is useful if you have several services that reuse a common set of configuration
+options. Using `extends` you can define a common set of service options 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.
+> **Note:** `links` and `volumes_from` are never shared between services using
+> `extends`. See
+> [Adding and overriding configuration](#adding-and-overriding-configuration)
+> for more information.
 
-### Understand the extends configuration
+#### Understand the extends configuration
 
 When defining any service in `docker-compose.yml`, you can declare that you are
 extending another service like this:
@@ -77,183 +86,46 @@ You can also write other services and link your `web` service to them:
     db:
       image: postgres
 
-For full details on how to use `extends`, refer to the [reference](#reference).
-
-### Example use case
-
-In this example, you’ll 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 in `Dockerfile` and a Compose
-    service in `common.yml`.
-
-2.  Define the development environment in the standard Compose file,
-    `docker-compose.yml`.
-
-    - Use `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, `production.yml`.
-
-    - Use `extends` to pull in the web service.
-    - Configure the web service 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 file contains a simple Python application that uses Flask to serve HTTP
-    and increments a counter in Redis:
-
-        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.\n' % 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 in 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`:
-
-    This configuration defines how to run the app.
-
-        web:
-          build: .
-          ports:
-            - "5000:5000"
-
-    Typically, you would have dropped this configuration into
-    `docker-compose.yml` file, but in order to pull it into multiple files with
-    `extends`, it needs to be in a separate file.
-
-#### Define the development environment
-
-1.  Create a `docker-compose.yml` file.
-
-    The `extends` option pulls in the `web` service from the `common.yml` file
-    you created in the previous section.
+#### Example use case
 
-        web:
-          extends:
-            file: common.yml
-            service: web
-          volumes:
-            - .:/code
-          links:
-            - redis
-          environment:
-            - REDIS_HOST=redis
-        redis:
-          image: redis
+Extending an individual service is useful when you have multiple services that
+have a common configuration.  In this example we have a composition that with
+a web application and a queue worker. Both services use the same codebase and
+share many configuration options.
 
-    The new addition defines a `web` service that:
+In a **common.yml** we'll define the common configuration:
 
-    - 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`&mdash;say, from `Hello world!` to `Hello from Compose!`.
-
-    Don't forget to refresh your browser to see the change!
-
-#### Define the production environment
-
-You are almost done. Now, define your production environment:
-
-1.  Create a `production.yml` file.
-
-    As with `docker-compose.yml`, the `extends` option pulls in the `web` service
-    from `common.yml`.
-
-        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&mdash;`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
+    app:
+      build: .
+      environment:
+        CONFIG_FILE_PATH: /code/config
+        API_KEY: xxxyyy
+      cpu_shares: 5
 
-You can use `extends` on any service together with other configuration keys. It
-expects a dictionary that contains a `service` key and optionally a `file` key.
-The `extends` key can also take a string, whose value is the name of a `service` defined in the same file.
+In a **docker-compose.yml** we'll define the concrete services which use the
+common configuration:
 
-The `file` key specifies the location of a Compose configuration file defining
-the extension. The `file` value can be an absolute or relative path. If you
-specify a relative path, Docker Compose treats it as relative to the location
-of the current file. If you don't specify a `file`, Compose looks in the
-current configuration file.
 
-The `service` key specifies the name of the service to extend, for example `web`
-or `database`.
+    webapp:
+      extends:
+        file: common.yml
+        service: app
+      command: /code/run_web_app
+      ports:
+        - 8080:8080
+      links:
+        - queue
+        - db
 
-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.
+    queue_worker:
+      extends:
+        file: common.yml
+        service: app
+    command: /code/run_worker
+    links:
+      - queue
 
-#### Adding and overriding configuration
+#### 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
@@ -282,6 +154,8 @@ listed below.**
 In the case of `build` and `image`, using one in the local service causes
 Compose to discard the other, if it was defined in the original service.
 
+Example of image replacing build:
+
     # original service
     build: .
 
@@ -291,6 +165,9 @@ Compose to discard the other, if it was defined in the original service.
     # result
     image: redis
 
+
+Example of build replacing image:
+
     # original service
     image: redis
 
@@ -356,6 +233,13 @@ locally-defined bindings taking precedence:
       - /local-dir/bar:/bar
       - /local-dir/baz/:baz
 
+
+### Extending Compose files
+
+> **Note:** This feature is new in `docker-compose` 1.5
+
+
+
 ## Compose documentation
 
 - [User guide](/)