mirror of https://github.com/docker/compose.git
Update intro docs based on feedback.
Signed-off-by: Daniel Nephin <dnephin@docker.com>
This commit is contained in:
Daniel Nephin
parent
bfb46b37d3
commit
7ee36829ac
|
|
@ -2,8 +2,6 @@ Docker Compose
|
|||
==============
|
||||
|
||||
|
||||
*(Previously known as Fig)*
|
||||
|
||||
Compose is a tool for defining and running multi-container Docker applications.
|
||||
With Compose, you define a multi-container application in a compose
|
||||
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
|
||||
|
||||
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:
|
||||
|
||||
|
|
|
|||
|
|
@ -10,84 +10,103 @@ weight=3
|
|||
<![end-metadata]-->
|
||||
|
||||
|
||||
## Getting Started
|
||||
# Getting Started
|
||||
|
||||
Let's get started with a walkthrough of getting a simple Python web app running
|
||||
on Compose. It assumes a little knowledge of Python, but the concepts
|
||||
demonstrated here should be understandable even if you're not familiar with
|
||||
Python.
|
||||
On this page you build a simple Python web application running on Compose. The
|
||||
application uses the Flask framework and increments a value in Redis. While the
|
||||
sample uses Python, the concepts demonstrated here should be understandable even
|
||||
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
|
||||
$ cd composetest
|
||||
1. Create a directory for the project:
|
||||
|
||||
Inside this directory, create `app.py`, a simple Python web app that uses the Flask
|
||||
framework and increments a value in Redis.
|
||||
$ mkdir composetest
|
||||
$ cd composetest
|
||||
|
||||
from flask import Flask
|
||||
from redis import Redis
|
||||
2. With your favorite text editor create a file called `app.py` in your project
|
||||
directory.
|
||||
|
||||
app = Flask(__name__)
|
||||
redis = Redis(host='redis', port=6379)
|
||||
from flask import Flask
|
||||
from redis import Redis
|
||||
|
||||
@app.route('/')
|
||||
def hello():
|
||||
redis.incr('hits')
|
||||
return 'Hello World! I have been seen %s times.' % redis.get('hits')
|
||||
app = Flask(__name__)
|
||||
redis = Redis(host='redis', port=6379)
|
||||
|
||||
if __name__ == "__main__":
|
||||
app.run(host="0.0.0.0", debug=True)
|
||||
@app.route('/')
|
||||
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
|
||||
redis
|
||||
3. Create another file called `requirements.txt` in your project directory and
|
||||
add the following:
|
||||
|
||||
### Create a Docker image
|
||||
flask
|
||||
redis
|
||||
|
||||
Now, create a Docker image containing all of your app's dependencies. You
|
||||
specify how to build the image using a file called
|
||||
[`Dockerfile`](http://docs.docker.com/reference/builder/):
|
||||
These define the applications dependencies.
|
||||
|
||||
FROM python:2.7
|
||||
ADD . /code
|
||||
WORKDIR /code
|
||||
RUN pip install -r requirements.txt
|
||||
CMD python app.py
|
||||
## Step 2: Create a Docker image
|
||||
|
||||
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.
|
||||
* 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`
|
||||
1. In your project directory create a file named `Dockerfile` and add the
|
||||
following:
|
||||
|
||||
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`:
|
||||
|
||||
web:
|
||||
build: .
|
||||
ports:
|
||||
- "5000:5000"
|
||||
volumes:
|
||||
- .:/code
|
||||
links:
|
||||
- redis
|
||||
redis:
|
||||
image: redis
|
||||
1. Create a file called docker-compose.yml in your project directory and add
|
||||
the following:
|
||||
|
||||
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.
|
||||
* 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.
|
||||
|
||||
### 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
|
||||
Pulling image redis...
|
||||
Building web...
|
||||
Starting composetest_redis_1...
|
||||
Starting composetest_web_1...
|
||||
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 | * Restarting with stat
|
||||
$ docker-compose up
|
||||
Pulling image redis...
|
||||
Building web...
|
||||
Starting composetest_redis_1...
|
||||
Starting composetest_web_1...
|
||||
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 | * 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
|
||||
(for "detached" mode) to `docker-compose up` and use `docker-compose ps` to
|
||||
see what is currently running:
|
||||
|
||||
$ docker-compose up -d
|
||||
Starting composetest_redis_1...
|
||||
Starting composetest_web_1...
|
||||
$ docker-compose ps
|
||||
Name Command State Ports
|
||||
-------------------------------------------------------------------
|
||||
composetest_redis_1 /usr/local/bin/run Up
|
||||
composetest_web_1 /bin/sh -c python app.py Up 5000->5000/tcp
|
||||
$ docker-compose up -d
|
||||
Starting composetest_redis_1...
|
||||
Starting composetest_web_1...
|
||||
$ docker-compose ps
|
||||
Name Command State Ports
|
||||
-------------------------------------------------------------------
|
||||
composetest_redis_1 /usr/local/bin/run Up
|
||||
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
|
||||
services. For example, to see what environment variables are available to the
|
||||
`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.
|
||||
|
||||
If you started Compose with `docker-compose up -d`, you'll probably want to stop
|
||||
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.
|
||||
|
||||
|
||||
## Where to go next
|
||||
|
||||
- Next, try the quick start guide for [Django](django.md),
|
||||
[Rails](rails.md), or [WordPress](wordpress.md).
|
||||
- See the reference guides for complete details on the [commands](./reference/index.md), the
|
||||
[configuration file](compose-file.md) and [environment variables](env.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)
|
||||
- [Explore the full list of Compose commands](./reference/index.md)
|
||||
- [Compose configuration file reference](compose-file.md)
|
||||
|
|
|
|||
|
|
@ -43,7 +43,7 @@ A `docker-compose.yml` looks like this:
|
|||
image: redis
|
||||
|
||||
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:
|
||||
|
||||
|
|
@ -64,6 +64,12 @@ Compose has commands for managing the whole lifecycle of your application:
|
|||
|
||||
## 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
|
||||
|
||||
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.
|
||||
|
||||
|
||||
#### Variables and moving a composition to different environments
|
||||
|
||||
> New in `docker-compose` 1.5
|
||||
#### Variables and moving a composition between environments
|
||||
|
||||
Compose supports variables in the Compose file. You can use these variables
|
||||
to customize your composition for different environments, or different users.
|
||||
See [Variable substitution](compose-file.md#variable-substitution) for more
|
||||
details.
|
||||
|
||||
Compose files can also be extended from other files using the `extends`
|
||||
field in a compose file, or by using multiple files. See [extends](extends.md)
|
||||
for more details.
|
||||
You can extend a Compose file using the `extends` field or by creating multiple
|
||||
Compose files. See [extends](extends.md) for more details.
|
||||
|
||||
|
||||
## Common Use Cases
|
||||
|
|
@ -101,14 +104,19 @@ below.
|
|||
|
||||
### Development environments
|
||||
|
||||
When you're developing software it is often helpful to be able to run the
|
||||
application and interact with it. If the application has any service dependencies
|
||||
(databases, queues, caches, web services, etc) you need a way to document the
|
||||
dependencies, configuration and operation of each. Compose provides a convenient
|
||||
format for definition these dependencies (the [Compose file](yml.md)) and a CLI
|
||||
tool for starting an isolated environment. Compose can replace a multi-page
|
||||
"developer getting started guide" with a single machine readable configuration
|
||||
file and a single command `docker-compose up`.
|
||||
When you're developing software, the ability to run an application in an
|
||||
isolated environment and interact with it is crucial. The Compose command
|
||||
line tool can be used to create the environment and interact with it.
|
||||
|
||||
The [Compose file](compose-file.md) provides a way to document and configure
|
||||
all of the application's service dependencies (databases, queues, caches,
|
||||
web service APIs, etc). Using the Compose command line tool you can create
|
||||
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
|
||||
|
||||
|
|
@ -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
|
||||
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
|
||||
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:
|
||||
|
||||
$ docker-compose up -d
|
||||
|
|
@ -128,11 +136,13 @@ environments in just a few commands:
|
|||
|
||||
Compose has traditionally been focused on development and testing workflows,
|
||||
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
|
||||
instance provisioned with [Docker Machine](https://docs.docker.com/machine/) or
|
||||
a [Docker Swarm](https://docs.docker.com/swarm/) cluster.
|
||||
You can use Compose to deploy to a remote Docker Engine. The Docker Engine may
|
||||
be a single instance provisioned with
|
||||
[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
|
||||
|
|
|
|||
Loading…
Reference in New Issue