docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Remove duplication from extends docs. 

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

Signed-off-by: Daniel Nephin <dnephin@docker.com>
This commit is contained in:
Daniel Nephin 2015-10-09 12:34:55 -04:00
parent 767a13f771
commit 7014cabb04
2 changed files with 80 additions and 211 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

51
docs/compose-file.md
View File

@ -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 Extend another service, in the current file or another, optionally overriding
configuration. configuration.
Here's a simple example. Suppose we have 2 files - **common.yml** and You can use `extends` on any service together with other configuration keys.
**development.yml**. We can use `extends` to define a service in The value must be a dictionary with the key: `service` and may optionally have
**development.yml** which uses configuration defined in **common.yml**: the `file` key.
**common.yml** extends:
file: common.yml
service: webapp
webapp: The `file` key specifies the location of a Compose configuration file defining
build: ./webapp the service which is being extended. The `file` value can be an absolute or
environment: relative path. If you specify a relative path, Docker Compose treats it as
- DEBUG=false relative to the location of the current file. If you don't specify a `file`,
- SEND_EMAILS=false 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: You can extend a service that itself extends another. You can extend
extends: indefinitely. Compose does not support circular references and `docker-compose`
file: common.yml returns an error if it encounters one.
service: webapp
ports:
- "8000:8000"
links:
- db
environment:
- DEBUG=true
db:
image: postgres
Here, the `web` service in **development.yml** inherits the configuration of For more on `extends`, see the
the `webapp` service in **common.yml** - the `build` and `environment` keys - [the extends documentation](extends.md#extending-services).
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.
For more on `extends`, see the [tutorial](extends.md#example) and
[reference](extends.md#reference).
### external_links ### external_links

240
docs/extends.md
View File

@ -10,20 +10,29 @@ weight=2
<![end-metadata]--> <![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 Docker Compose's `extends` keyword enables sharing of common configurations
among different files, or even different projects entirely. Extending services among different files, or even different projects entirely. Extending services
is useful if you have several applications that reuse commonly-defined services. is useful if you have several services that reuse a common set of configuration
Using `extends` you can define a service in one place and refer to it from options. Using `extends` you can define a common set of service options in one
anywhere. place and refer to it from anywhere.
Alternatively, you can deploy the same application to multiple environments with > **Note:** `links` and `volumes_from` are never shared between services using
a slightly different set of services in each case (or with changes to the > `extends`. See
configuration of some services). Moreover, you can do so without copy-pasting > [Adding and overriding configuration](#adding-and-overriding-configuration)
the configuration around. > 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 When defining any service in `docker-compose.yml`, you can declare that you are
extending another service like this: extending another service like this:
@ -77,183 +86,46 @@ You can also write other services and link your `web` service to them:
db: db:
image: postgres image: postgres
For full details on how to use `extends`, refer to the [reference](#reference). #### Example use case
### Example use case 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.
In this example, you’ll repurpose the example app from the [quick start In a **common.yml** we'll define the common configuration:
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 app:
differences. In development, you mount the application code as a volume so that build: .
it can pick up changes; in production, the code should be immutable from the environment:
outside. This ensures it’s not accidentally changed. The development environment CONFIG_FILE_PATH: /code/config
uses a local Redis container, but in production another team manages the Redis API_KEY: xxxyyy
service, which is listening at `redis-production.example.com`. cpu_shares: 5
To configure with `extends` for this sample, you must: In a **docker-compose.yml** we'll define the concrete services which use the
common configuration:
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.
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`&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 webapp:
extends:
file: common.yml
service: app
command: /code/run_web_app
ports:
- 8080:8080
links:
- queue
- db
You can use `extends` on any service together with other configuration keys. It queue_worker:
expects a dictionary that contains a `service` key and optionally a `file` key. extends:
The `extends` key can also take a string, whose value is the name of a `service` defined in the same file. file: common.yml
service: app
command: /code/run_worker
links:
- queue
The `file` key specifies the location of a Compose configuration file defining #### Adding and overriding configuration
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`.
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, Compose copies configurations from the original service over to the local one,
**except** for `links` and `volumes_from`. These exceptions exist to avoid **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 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. Compose to discard the other, if it was defined in the original service.
Example of image replacing build:
# original service # original service
build: . build: .
@ -291,6 +165,9 @@ Compose to discard the other, if it was defined in the original service.
# result # result
image: redis image: redis
Example of build replacing image:
# original service # original service
image: redis image: redis
@ -356,6 +233,13 @@ locally-defined bindings taking precedence:
- /local-dir/bar:/bar - /local-dir/bar:/bar
- /local-dir/baz/:baz - /local-dir/baz/:baz
### Extending Compose files
> **Note:** This feature is new in `docker-compose` 1.5
## Compose documentation ## Compose documentation
- [User guide](/) - [User guide](/)