From 53a0de7cf2231da88c7501bb367eb4e7f1c4d425 Mon Sep 17 00:00:00 2001 From: Daniel Nephin Date: Tue, 27 Oct 2015 16:29:36 -0400 Subject: [PATCH 1/7] Add missing title to compose file reference. Signed-off-by: Daniel Nephin --- docs/compose-file.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/compose-file.md b/docs/compose-file.md index d45916081d..7723a78476 100644 --- a/docs/compose-file.md +++ b/docs/compose-file.md @@ -24,6 +24,11 @@ As with `docker run`, options specified in the Dockerfile (e.g., `CMD`, `EXPOSE`, `VOLUME`, `ENV`) are respected by default - you don't need to specify them again in `docker-compose.yml`. +## Service configuration reference + +This section contains a list of all configuration options supported by a service +definition. + ### build Path to a directory containing a Dockerfile. When the value supplied is a From 186d43c59f82e4210b379885368eb73a4162003d Mon Sep 17 00:00:00 2001 From: Daniel Nephin Date: Fri, 9 Oct 2015 10:49:41 -0400 Subject: [PATCH 2/7] Extract the getting started guide from the index page. Signed-off-by: Daniel Nephin --- docs/completion.md | 2 +- docs/django.md | 1 + docs/extends.md | 1 + docs/gettingstarted.md | 163 +++++++++++++++++++++++++++++++++++++++++ docs/index.md | 139 +---------------------------------- docs/install.md | 1 + docs/production.md | 3 - docs/rails.md | 2 +- docs/wordpress.md | 2 +- 9 files changed, 170 insertions(+), 144 deletions(-) create mode 100644 docs/gettingstarted.md diff --git a/docs/completion.md b/docs/completion.md index bc8bedc96c..3c2022d827 100644 --- a/docs/completion.md +++ b/docs/completion.md @@ -5,7 +5,7 @@ description = "Compose CLI reference" keywords = ["fig, composition, compose, docker, orchestration, cli, reference"] [menu.main] parent="smn_workw_compose" -weight=3 +weight=10 +++ diff --git a/docs/django.md b/docs/django.md index 2bb67399c5..d4d2bd1ecf 100644 --- a/docs/django.md +++ b/docs/django.md @@ -173,6 +173,7 @@ In this section, you set up the database connection for Django. - [User guide](../index.md) - [Installing Compose](install.md) +- [Getting Started](gettingstarted.md) - [Get started with Rails](rails.md) - [Get started with WordPress](wordpress.md) - [Command line reference](./reference/index.md) diff --git a/docs/extends.md b/docs/extends.md index f0b9e9ea2d..e63cf4662e 100644 --- a/docs/extends.md +++ b/docs/extends.md @@ -360,6 +360,7 @@ locally-defined bindings taking precedence: - [User guide](/) - [Installing Compose](install.md) +- [Getting Started](gettingstarted.md) - [Get started with Django](django.md) - [Get started with Rails](rails.md) - [Get started with WordPress](wordpress.md) diff --git a/docs/gettingstarted.md b/docs/gettingstarted.md new file mode 100644 index 0000000000..f2024b39ba --- /dev/null +++ b/docs/gettingstarted.md @@ -0,0 +1,163 @@ + + + +## 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. + +### Installation and set-up + +First, [install Docker and Compose](install.md). + +Next, you'll want to make a directory for the project: + + $ mkdir composetest + $ cd composetest + +Inside this directory, create `app.py`, a simple Python web app that uses the Flask +framework and increments a value in Redis. Don't worry if you don't have Redis installed, docker is going to take care of that for you when we [define services](#define-services): + + from flask import Flask + from redis import Redis + + app = Flask(__name__) + redis = Redis(host='redis', 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) + +Next, define the Python dependencies in a file called `requirements.txt`: + + flask + redis + +### Create a Docker image + +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/): + + FROM python:2.7 + ADD . /code + WORKDIR /code + RUN pip install -r requirements.txt + CMD python app.py + +This tells Docker to: + +* 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/). + +You can build the image by running `docker build -t web .`. + +### Define services + +Next, define a set of services using `docker-compose.yml`: + + web: + build: . + ports: + - "5000:5000" + volumes: + - .:/code + links: + - redis + redis: + image: redis + +This template 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. +* Mounts the current directory on the host to `/code` inside the container allowing you to modify the code without having to rebuild the image. +* Links the web container to the Redis 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 + +Now, when you run `docker-compose up`, Compose will pull a Redis image, build an image for your code, and start everything up: + + $ 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. + +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`. + +You should get a message in your browser saying: + +`Hello World! I have been seen 1 times.` + +Refreshing the page will increment the number. + +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 + +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 + +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 + +At this point, you have seen the basics of how Compose works. + +- 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) diff --git a/docs/index.md b/docs/index.md index 62c78d6893..19a6c801c2 100644 --- a/docs/index.md +++ b/docs/index.md @@ -50,150 +50,13 @@ Compose has commands for managing the whole lifecycle of your application: ## Compose documentation - [Installing Compose](install.md) +- [Getting Started](gettingstarted.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) -## Quick start - -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. - -### Installation and set-up - -First, [install Docker and Compose](install.md). - -Next, you'll want to make a directory for the project: - - $ mkdir composetest - $ cd composetest - -Inside this directory, create `app.py`, a simple Python web app that uses the Flask -framework and increments a value in Redis. Don't worry if you don't have Redis installed, docker is going to take care of that for you when we [define services](#define-services): - - from flask import Flask - from redis import Redis - - app = Flask(__name__) - redis = Redis(host='redis', 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) - -Next, define the Python dependencies in a file called `requirements.txt`: - - flask - redis - -### Create a Docker image - -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/): - - FROM python:2.7 - ADD . /code - WORKDIR /code - RUN pip install -r requirements.txt - CMD python app.py - -This tells Docker to: - -* 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/). - -You can build the image by running `docker build -t web .`. - -### Define services - -Next, define a set of services using `docker-compose.yml`: - - web: - build: . - ports: - - "5000:5000" - volumes: - - .:/code - redis: - image: redis - -This template 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. -* Mounts the current directory on the host to `/code` inside the container allowing you to modify the code without having to rebuild the image. - -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 - -Now, when you run `docker-compose up`, Compose will pull a Redis image, build an image for your code, and start everything up: - - $ 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. - -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`. - -You should get a message in your browser saying: - -`Hello World! I have been seen 1 times.` - -Refreshing the page will increment the number. - -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 - -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 - -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 - -At this point, you have seen the basics of how Compose works. - -- 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). ## Release Notes diff --git a/docs/install.md b/docs/install.md index 944ce349d0..e19bda0f3b 100644 --- a/docs/install.md +++ b/docs/install.md @@ -127,6 +127,7 @@ To uninstall Docker Compose if you installed using `pip`: ## Where to go next - [User guide](/) +- [Getting Started](gettingstarted.md) - [Get started with Django](django.md) - [Get started with Rails](rails.md) - [Get started with WordPress](wordpress.md) diff --git a/docs/production.md b/docs/production.md index 8793f9277e..0b0e46c3f0 100644 --- a/docs/production.md +++ b/docs/production.md @@ -86,8 +86,5 @@ guide. ## Compose documentation - [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) diff --git a/docs/rails.md b/docs/rails.md index e81675c537..8e16af6423 100644 --- a/docs/rails.md +++ b/docs/rails.md @@ -135,8 +135,8 @@ That's it. Your app should now be running on port 3000 on your Docker daemon. If - [User guide](/) - [Installing Compose](install.md) +- [Getting Started](gettingstarted.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) diff --git a/docs/wordpress.md b/docs/wordpress.md index 8c1f5b0acb..373ef4d0d5 100644 --- a/docs/wordpress.md +++ b/docs/wordpress.md @@ -95,8 +95,8 @@ database containers. If you're using [Docker Machine](https://docs.docker.com/ma - [User guide](/) - [Installing Compose](install.md) +- [Getting Started](gettingstarted.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) From 86d845fde3ec63d762a2dbd0dbcfc21eb8011f52 Mon Sep 17 00:00:00 2001 From: Daniel Nephin Date: Fri, 9 Oct 2015 11:08:23 -0400 Subject: [PATCH 3/7] Flush out features and use cases. Signed-off-by: Daniel Nephin --- README.md | 17 ++++++---- docs/index.md | 94 ++++++++++++++++++++++++++++++++++++++++++++++----- 2 files changed, 97 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index ed176550db..55346f24cc 100644 --- a/README.md +++ b/README.md @@ -4,13 +4,15 @@ Docker Compose *(Previously known as Fig)* -Compose is a tool for defining and running multi-container applications with -Docker. With Compose, you define a multi-container application in a single -file, then spin your application up in a single command which does everything -that needs to be done to get it running. +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 +from your configuration. To learn more about all the features of Compose +see [the list of features](#features) -Compose is great for development environments, staging servers, and CI. We don't -recommend that you use it in production yet. +Compose is great for development, testing, and staging environments, as well as +CI workflows. You can learn more about each case in +[Common Use Cases](#common-use-cases). Using Compose is basically a three-step process. @@ -33,6 +35,9 @@ A `docker-compose.yml` looks like this: redis: image: redis +For more information about the Compose file, see the +[Compose file reference](docs/yml.md) + Compose has commands for managing the whole lifecycle of your application: * Start, stop and rebuild services diff --git a/docs/index.md b/docs/index.md index 19a6c801c2..ac7e07f9ba 100644 --- a/docs/index.md +++ b/docs/index.md @@ -11,20 +11,22 @@ parent="smn_workw_compose" # Overview of Docker Compose -Compose is a tool for defining and running multi-container applications with -Docker. With Compose, you define a multi-container application in a single -file, then spin your application up in a single command which does everything -that needs to be done to get it running. +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 +from your configuration. To learn more about all the features of Compose +see [the list of features](#features) -Compose is great for development environments, staging servers, and CI. We don't -recommend that you use it in production yet. +Compose is great for development, testing, and staging environments, as well as +CI workflows. You can learn more about each case in +[Common Use Cases](#common-use-cases). Using Compose is basically a three-step process. 1. Define your app's environment with a `Dockerfile` so it can be reproduced anywhere. 2. Define the services that make up your app in `docker-compose.yml` so -they can be run together in an isolated environment: +they can be run together in an isolated environment. 3. Lastly, run `docker-compose up` and Compose will start and run your entire app. A `docker-compose.yml` looks like this: @@ -40,6 +42,9 @@ A `docker-compose.yml` looks like this: redis: image: redis +For more information about the Compose file, see the +[Compose file reference](yml.md) + Compose has commands for managing the whole lifecycle of your application: * Start, stop and rebuild services @@ -57,11 +62,84 @@ Compose has commands for managing the whole lifecycle of your application: - [Command line reference](./reference/index.md) - [Compose file reference](compose-file.md) +## Features + +#### Preserve volume data + +Compose preserves all volumes used by your services. When `docker-compose up` +runs, if it finds any containers from previous runs, it copies the volumes from +the old container to the new container. This process ensures that any data +you've created in volumes isn't lost. + + +#### Only recreate containers that have changed + +Compose caches the configuration used to create a container. When you +restart a service that has not changed, Compose re-uses the existing +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 + +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. + + +## Common Use Cases + +Compose can be used in many different ways. Some common use cases are outlined +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`. + +### Automated testing environments + +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 +environments in just a few commands: + + $ docker-compose up -d + $ ./run_tests + $ docker-compose stop + $ docker-compose rm -f + +### Single host deployments + +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. + +See [compose in production](production.md) for more details. + ## Release Notes To see a detailed list of changes for past and current releases of Docker -Compose, please refer to the [CHANGELOG](https://github.com/docker/compose/blob/master/CHANGELOG.md). +Compose, please refer to the +[CHANGELOG](https://github.com/docker/compose/blob/master/CHANGELOG.md). ## Getting help From db3b90b84efa1ddd39b282e67f775f75609d14a3 Mon Sep 17 00:00:00 2001 From: Daniel Nephin Date: Wed, 21 Oct 2015 16:28:47 -0400 Subject: [PATCH 4/7] Updates to gettingstarted guide from PR feedback. Signed-off-by: Daniel Nephin --- docs/gettingstarted.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/gettingstarted.md b/docs/gettingstarted.md index f2024b39ba..9cc478d7e5 100644 --- a/docs/gettingstarted.md +++ b/docs/gettingstarted.md @@ -21,13 +21,13 @@ Python. First, [install Docker and Compose](install.md). -Next, you'll want to make a directory for the project: +Create a directory for the project: $ mkdir composetest $ cd composetest Inside this directory, create `app.py`, a simple Python web app that uses the Flask -framework and increments a value in Redis. Don't worry if you don't have Redis installed, docker is going to take care of that for you when we [define services](#define-services): +framework and increments a value in Redis. from flask import Flask from redis import Redis @@ -74,7 +74,7 @@ You can build the image by running `docker build -t web .`. ### Define services -Next, define a set of services using `docker-compose.yml`: +Define a set of services using `docker-compose.yml`: web: build: . @@ -91,8 +91,8 @@ This template 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. -* Mounts the current directory on the host to `/code` inside the container allowing you to modify the code without having to rebuild the image. -* Links the web container to the Redis service. +* Mounts the project directory on the host to `/code` inside the container allowing you to modify the code without having to rebuild the image. +* Links the web service to the Redis service. The `redis` service uses the latest public [Redis](https://registry.hub.docker.com/_/redis/) image pulled from the Docker Hub registry. @@ -113,7 +113,7 @@ If you're using [Docker Machine](https://docs.docker.com/machine), then `docker- 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`. -You should get a message in your browser saying: +You will see a message in your browser saying: `Hello World! I have been seen 1 times.` From d9bc91b7cc0a8cc867caaac1bf36c1eab2b6cb4b Mon Sep 17 00:00:00 2001 From: Daniel Nephin Date: Fri, 23 Oct 2015 16:51:03 -0400 Subject: [PATCH 5/7] Update intro docs based on feedback. Signed-off-by: Daniel Nephin --- README.md | 4 +- docs/gettingstarted.md | 207 +++++++++++++++++++++++------------------ docs/index.md | 50 ++++++---- 3 files changed, 147 insertions(+), 114 deletions(-) diff --git a/README.md b/README.md index 55346f24cc..bd11030724 100644 --- a/README.md +++ b/README.md @@ -2,8 +2,6 @@ Docker Compose ============== ![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. 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: diff --git a/docs/gettingstarted.md b/docs/gettingstarted.md index 9cc478d7e5..f685bf3820 100644 --- a/docs/gettingstarted.md +++ b/docs/gettingstarted.md @@ -10,84 +10,103 @@ weight=3 -## 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) diff --git a/docs/index.md b/docs/index.md index ac7e07f9ba..6ea0e99ab5 100644 --- a/docs/index.md +++ b/docs/index.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 From a3fb13e14195835d08006f23a9f26f6907f77262 Mon Sep 17 00:00:00 2001 From: Daniel Nephin Date: Tue, 27 Oct 2015 16:51:49 -0400 Subject: [PATCH 6/7] Add another feature to the docs - multiple environments per host. Signed-off-by: Daniel Nephin --- docs/index.md | 22 ++++++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) diff --git a/docs/index.md b/docs/index.md index 6ea0e99ab5..ebc1320eae 100644 --- a/docs/index.md +++ b/docs/index.md @@ -66,11 +66,29 @@ Compose has commands for managing the whole lifecycle of your application: The features of Compose that make it effective are: -* [Preserve volume data](#preserve-volume-data) +* [Multiple isolated environments on a single host](#Multiple-isolated-environments-on-a-single-host) +* [Preserve volume data when containers are created](#preserve-volume-data-when-containers-are-created) * [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 +#### Multiple isolated environments on a single host + +Compose uses a project name to isolate environments from each other. You can use +this project name to: + +* on a dev host, to create multiple copies of a single environment (ex: you want + to run a stable copy for each feature branch of a project) +* on a CI server, to keep builds from interfering with each other, you can set + the project name to a unique build number +* on a shared host or dev host, to prevent different projects which may use the + same service names, from interfering with each other + +The default project name is the basename of the project directory. You can set +a custom project name by using the +[`-p` command line option](./reference/docker-compose.md) or the +[`COMPOSE_PROJECT_NAME` environment variable](./reference/overview.md#compose-project-name). + +#### Preserve volume data when containers are created Compose preserves all volumes used by your services. When `docker-compose up` runs, if it finds any containers from previous runs, it copies the volumes from From c58cf036e34b34a7c435f0c4c80b13f058788d70 Mon Sep 17 00:00:00 2001 From: Daniel Nephin Date: Fri, 30 Oct 2015 13:27:06 -0400 Subject: [PATCH 7/7] Touch up intro paragraph with feedback from @moxiegirl. Signed-off-by: Daniel Nephin --- README.md | 6 +++--- docs/index.md | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index bd11030724..5052db39d5 100644 --- a/README.md +++ b/README.md @@ -3,10 +3,10 @@ Docker Compose ![Docker Compose](logo.png?raw=true "Docker Compose Logo") 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 +With Compose, you use a Compose file to configure your application's services. +Then, using a single command, you create and start all the services from your configuration. To learn more about all the features of Compose -see [the list of features](#features) +see [the list of features](docs/index.md#features). Compose is great for development, testing, and staging environments, as well as CI workflows. You can learn more about each case in diff --git a/docs/index.md b/docs/index.md index ebc1320eae..279154eef9 100644 --- a/docs/index.md +++ b/docs/index.md @@ -12,10 +12,10 @@ parent="smn_workw_compose" # Overview of Docker Compose 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 +With Compose, you use a Compose file to configure your application's services. +Then, using a single command, you create and start all the services from your configuration. To learn more about all the features of Compose -see [the list of features](#features) +see [the list of features](#features). Compose is great for development, testing, and staging environments, as well as CI workflows. You can learn more about each case in