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

Update intro docs based on feedback. 

Signed-off-by: Daniel Nephin <dnephin@docker.com>
This commit is contained in:
Daniel Nephin 2015-10-23 16:51:03 -04:00
parent bfb46b37d3
commit 7ee36829ac
3 changed files with 147 additions and 114 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
README.md
View File

@ -2,8 +2,6 @@ Docker Compose
============== ==============
![Docker Compose](logo.png?raw=true "Docker Compose Logo") ![Docker Compose](logo.png?raw=true "Docker Compose Logo")
*(Previously known as Fig)*
Compose is a tool for defining and running multi-container Docker applications. Compose is a tool for defining and running multi-container Docker applications.
With Compose, you define a multi-container application in a compose With Compose, you define a multi-container application in a compose
file then, using a single command, you create and start all the containers file then, using a single command, you create and start all the containers
@ -36,7 +34,7 @@ A `docker-compose.yml` looks like this:
image: redis image: redis
For more information about the Compose file, see the For more information about the Compose file, see the
[Compose file reference](docs/yml.md) [Compose file reference](docs/compose-file.md)
Compose has commands for managing the whole lifecycle of your application: Compose has commands for managing the whole lifecycle of your application:

207
docs/gettingstarted.md
View File

@ -10,84 +10,103 @@ weight=3
<![end-metadata]--> <![end-metadata]-->
## Getting Started # Getting Started
Let's get started with a walkthrough of getting a simple Python web app running On this page you build a simple Python web application running on Compose. The
on Compose. It assumes a little knowledge of Python, but the concepts application uses the Flask framework and increments a value in Redis. While the
demonstrated here should be understandable even if you're not familiar with sample uses Python, the concepts demonstrated here should be understandable even
Python. if you're not familiar with it.
### Installation and set-up ## Prerequisites
First, [install Docker and Compose](install.md). Make sure you have already
[installed both Docker Engine and Docker Compose](install.md). You
don't need to install Python, it is provided by a Docker image.
Create a directory for the project: ## Step 1: Setup
$ mkdir composetest 1. Create a directory for the project:
$ cd composetest
Inside this directory, create `app.py`, a simple Python web app that uses the Flask $ mkdir composetest
framework and increments a value in Redis. $ cd composetest
from flask import Flask 2. With your favorite text editor create a file called `app.py` in your project
from redis import Redis directory.
app = Flask(__name__) from flask import Flask
redis = Redis(host='redis', port=6379) from redis import Redis
@app.route('/') app = Flask(__name__)
def hello(): redis = Redis(host='redis', port=6379)
redis.incr('hits')
return 'Hello World! I have been seen %s times.' % redis.get('hits')
if __name__ == "__main__": @app.route('/')
app.run(host="0.0.0.0", debug=True) def hello():
redis.incr('hits')
return 'Hello World! I have been seen %s times.' % redis.get('hits')
Next, define the Python dependencies in a file called `requirements.txt`: if __name__ == "__main__":
app.run(host="0.0.0.0", debug=True)
flask 3. Create another file called `requirements.txt` in your project directory and
redis add the following:
### Create a Docker image flask
redis
Now, create a Docker image containing all of your app's dependencies. You These define the applications dependencies.
specify how to build the image using a file called
[`Dockerfile`](http://docs.docker.com/reference/builder/):
FROM python:2.7 ## Step 2: Create a Docker image
ADD . /code
WORKDIR /code
RUN pip install -r requirements.txt
CMD python app.py
This tells Docker to: In this step, you build a new Docker image. The image contains all the
dependencies the Python application requires, including Python itself.
* Build an image starting with the Python 2.7 image. 1. In your project directory create a file named `Dockerfile` and add the
* Add the current directory `.` into the path `/code` in the image. following:
* Set the working directory to `/code`.
* Install the Python dependencies.
* Set the default command for the container to `python app.py`
For more information on how to write Dockerfiles, see the [Docker user guide](https://docs.docker.com/userguide/dockerimages/#building-an-image-from-a-dockerfile) and the [Dockerfile reference](http://docs.docker.com/reference/builder/). FROM python:2.7
ADD . /code
WORKDIR /code
RUN pip install -r requirements.txt
CMD python app.py
You can build the image by running `docker build -t web .`. This tells Docker to:
### Define services * Build an image starting with the Python 2.7 image.
* Add the current directory `.` into the path `/code` in the image.
* Set the working directory to `/code`.
* Install the Python dependencies.
* Set the default command for the container to `python app.py`
For more information on how to write Dockerfiles, see the [Docker user guide](https://docs.docker.com/userguide/dockerimages/#building-an-image-from-a-dockerfile) and the [Dockerfile reference](http://docs.docker.com/reference/builder/).
2. Build the image.
$ docker build -t web .
This command builds an image named `web` from the contents of the current
directory. The command automatically locates the `Dockerfile`, `app.py`, and
`requirements.txt` files.
## Step 3: Define services
Define a set of services using `docker-compose.yml`: Define a set of services using `docker-compose.yml`:
web: 1. Create a file called docker-compose.yml in your project directory and add
build: . the following:
ports:
- "5000:5000"
volumes:
- .:/code
links:
- redis
redis:
image: redis
This template defines two services, `web` and `redis`. The `web` service: web:
build: .
ports:
- "5000:5000"
volumes:
- .:/code
links:
- redis
redis:
image: redis
This Compose file defines two services, `web` and `redis`. The web service:
* Builds from the `Dockerfile` in the current directory. * Builds from the `Dockerfile` in the current directory.
* Forwards the exposed port 5000 on the container to port 5000 on the host machine. * Forwards the exposed port 5000 on the container to port 5000 on the host machine.
@ -96,68 +115,74 @@ This template defines two services, `web` and `redis`. The `web` service:
The `redis` service uses the latest public [Redis](https://registry.hub.docker.com/_/redis/) image pulled from the Docker Hub registry. The `redis` service uses the latest public [Redis](https://registry.hub.docker.com/_/redis/) image pulled from the Docker Hub registry.
### Build and run your app with Compose ## Step 4: Build and run your app with Compose
Now, when you run `docker-compose up`, Compose will pull a Redis image, build an image for your code, and start everything up: 1. From your project directory, start up your application.
$ docker-compose up $ docker-compose up
Pulling image redis... Pulling image redis...
Building web... Building web...
Starting composetest_redis_1... Starting composetest_redis_1...
Starting composetest_web_1... Starting composetest_web_1...
redis_1 | [8] 02 Jan 18:43:35.576 # Server started, Redis version 2.8.3 redis_1 | [8] 02 Jan 18:43:35.576 # Server started, Redis version 2.8.3
web_1 | * Running on http://0.0.0.0:5000/ web_1 | * Running on http://0.0.0.0:5000/
web_1 | * Restarting with stat web_1 | * Restarting with stat
If you're using [Docker Machine](https://docs.docker.com/machine), then `docker-machine ip MACHINE_VM` will tell you its address and you can open `http://MACHINE_VM_IP:5000` in a browser. Compose pulls a Redis image, builds an image for your code, and start the
services you defined.
If you're using Docker on Linux natively, then the web app should now be listening on port 5000 on your Docker daemon host. If `http://0.0.0.0:5000` doesn't resolve, you can also try `http://localhost:5000`. 2. Enter `http://0.0.0.0:5000/` in a browser to see the application running.
You will see a message in your browser saying: If you're using Docker on Linux natively, then the web app should now be
listening on port 5000 on your Docker daemon host. If http://0.0.0.0:5000
doesn't resolve, you can also try http://localhost:5000.
`Hello World! I have been seen 1 times.` If you're using Docker Machine on a Mac, use `docker-machine ip MACHINE_VM` to get
the IP address of your Docker host. Then, `open http://MACHINE_VM_IP:5000` in a
browser.
Refreshing the page will increment the number. You should see a message in your browser saying:
`Hello World! I have been seen 1 times.`
3. Refresh the page.
The number should increment.
## Step 5: Experiment with some other commands
If you want to run your services in the background, you can pass the `-d` flag If you want to run your services in the background, you can pass the `-d` flag
(for "detached" mode) to `docker-compose up` and use `docker-compose ps` to (for "detached" mode) to `docker-compose up` and use `docker-compose ps` to
see what is currently running: see what is currently running:
$ docker-compose up -d $ docker-compose up -d
Starting composetest_redis_1... Starting composetest_redis_1...
Starting composetest_web_1... Starting composetest_web_1...
$ docker-compose ps $ docker-compose ps
Name Command State Ports Name Command State Ports
------------------------------------------------------------------- -------------------------------------------------------------------
composetest_redis_1 /usr/local/bin/run Up composetest_redis_1 /usr/local/bin/run Up
composetest_web_1 /bin/sh -c python app.py Up 5000->5000/tcp composetest_web_1 /bin/sh -c python app.py Up 5000->5000/tcp
The `docker-compose run` command allows you to run one-off commands for your The `docker-compose run` command allows you to run one-off commands for your
services. For example, to see what environment variables are available to the services. For example, to see what environment variables are available to the
`web` service: `web` service:
$ docker-compose run web env $ docker-compose run web env
See `docker-compose --help` to see other available commands. You can also install [command completion](completion.md) for the bash and zsh shell, which will also show you available commands. See `docker-compose --help` to see other available commands. You can also install [command completion](completion.md) for the bash and zsh shell, which will also show you available commands.
If you started Compose with `docker-compose up -d`, you'll probably want to stop If you started Compose with `docker-compose up -d`, you'll probably want to stop
your services once you've finished with them: your services once you've finished with them:
$ docker-compose stop $ docker-compose stop
At this point, you have seen the basics of how Compose works. At this point, you have seen the basics of how Compose works.
## Where to go next
- Next, try the quick start guide for [Django](django.md), - Next, try the quick start guide for [Django](django.md),
[Rails](rails.md), or [WordPress](wordpress.md). [Rails](rails.md), or [WordPress](wordpress.md).
- See the reference guides for complete details on the [commands](./reference/index.md), the - [Explore the full list of Compose commands](./reference/index.md)
[configuration file](compose-file.md) and [environment variables](env.md). - [Compose configuration file reference](compose-file.md)
## More Compose documentation
- [User guide](/)
- [Installing Compose](install.md)
- [Get started with Django](django.md)
- [Get started with Rails](rails.md)
- [Get started with WordPress](wordpress.md)
- [Command line reference](./reference/index.md)
- [Compose file reference](compose-file.md)

50
docs/index.md
View File

@ -43,7 +43,7 @@ A `docker-compose.yml` looks like this:
image: redis image: redis
For more information about the Compose file, see the For more information about the Compose file, see the
[Compose file reference](yml.md) [Compose file reference](compose-file.md)
Compose has commands for managing the whole lifecycle of your application: Compose has commands for managing the whole lifecycle of your application:
@ -64,6 +64,12 @@ Compose has commands for managing the whole lifecycle of your application:
## Features ## Features
The features of Compose that make it effective are:
* [Preserve volume data](#preserve-volume-data)
* [Only recreate containers that have changed](#only-recreate-containers-that-have-changed)
* [Variables and moving a composition between environments](#variables-and-moving-a-composition-between-environments)
#### Preserve volume data #### Preserve volume data
Compose preserves all volumes used by your services. When `docker-compose up` Compose preserves all volumes used by your services. When `docker-compose up`
@ -80,18 +86,15 @@ containers. Re-using containers means that you can make changes to your
environment very quickly. environment very quickly.
#### Variables and moving a composition to different environments #### Variables and moving a composition between environments
> New in `docker-compose` 1.5
Compose supports variables in the Compose file. You can use these variables Compose supports variables in the Compose file. You can use these variables
to customize your composition for different environments, or different users. to customize your composition for different environments, or different users.
See [Variable substitution](compose-file.md#variable-substitution) for more See [Variable substitution](compose-file.md#variable-substitution) for more
details. details.
Compose files can also be extended from other files using the `extends` You can extend a Compose file using the `extends` field or by creating multiple
field in a compose file, or by using multiple files. See [extends](extends.md) Compose files. See [extends](extends.md) for more details.
for more details.
## Common Use Cases ## Common Use Cases
@ -101,14 +104,19 @@ below.
### Development environments ### Development environments
When you're developing software it is often helpful to be able to run the When you're developing software, the ability to run an application in an
application and interact with it. If the application has any service dependencies isolated environment and interact with it is crucial. The Compose command
(databases, queues, caches, web services, etc) you need a way to document the line tool can be used to create the environment and interact with it.
dependencies, configuration and operation of each. Compose provides a convenient
format for definition these dependencies (the [Compose file](yml.md)) and a CLI The [Compose file](compose-file.md) provides a way to document and configure
tool for starting an isolated environment. Compose can replace a multi-page all of the application's service dependencies (databases, queues, caches,
"developer getting started guide" with a single machine readable configuration web service APIs, etc). Using the Compose command line tool you can create
file and a single command `docker-compose up`. and start one or more containers for each dependency with a single command
(`docker-compose up`).
Together, these features provide a convenient way for developers to get
started on a project. Compose can reduce a multi-page "developer getting
started guide" to a single machine readable Compose file and a few commands.
### Automated testing environments ### Automated testing environments
@ -116,7 +124,7 @@ An important part of any Continuous Deployment or Continuous Integration process
is the automated test suite. Automated end-to-end testing requires an is the automated test suite. Automated end-to-end testing requires an
environment in which to run tests. Compose provides a convenient way to create environment in which to run tests. Compose provides a convenient way to create
and destroy isolated testing environments for your test suite. By defining the full and destroy isolated testing environments for your test suite. By defining the full
environment in a [Compose file](yml.md) you can create and destroy these environment in a [Compose file](compose-file.md) you can create and destroy these
environments in just a few commands: environments in just a few commands:
$ docker-compose up -d $ docker-compose up -d
@ -128,11 +136,13 @@ environments in just a few commands:
Compose has traditionally been focused on development and testing workflows, Compose has traditionally been focused on development and testing workflows,
but with each release we're making progress on more production-oriented features. but with each release we're making progress on more production-oriented features.
Compose can be used to deploy to a remote docker engine, for example a cloud You can use Compose to deploy to a remote Docker Engine. The Docker Engine may
instance provisioned with [Docker Machine](https://docs.docker.com/machine/) or be a single instance provisioned with
a [Docker Swarm](https://docs.docker.com/swarm/) cluster. [Docker Machine](https://docs.docker.com/machine/) or an entire
[Docker Swarm](https://docs.docker.com/swarm/) cluster.
See [compose in production](production.md) for more details. For details on using production-oriented features, see
[compose in production](production.md) in this documentation.
## Release Notes ## Release Notes