From 461f1ad5d5a4dd02e259d6fb4699dc0f5dcf76d1 Mon Sep 17 00:00:00 2001 From: Fred Lifton Date: Thu, 29 Jan 2015 18:21:49 -0800 Subject: [PATCH] Edit and revision of overview & quick start doc Signed-off-by: Fred Lifton --- docs/index.md | 98 ++++++++++++++++++++++++++++----------------------- 1 file changed, 54 insertions(+), 44 deletions(-) diff --git a/docs/index.md b/docs/index.md index 7f20624e2e..cdde1da7c4 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,22 +1,24 @@ ---- -layout: default -title: Compose: Multi-container orchestration for Docker page_title: Compose: Multi-container orchestration for Docker -page_description: Compose: Multi-container orchestration for Docker -page_keywords: fig, composition, compose, docker ---- +page_description: Introduction and Overview of Compose +page_keywords: documentation, docs, docker, compose, orchestration, containers -# Fast, isolated development environments using Docker. -Define your app's environment with a `Dockerfile` so it can be reproduced anywhere: +## Overview + +Compose is a tool that allows you to orchestrate multiple Docker containers. With Compose, you can build clusters of containers which provide the resources (services, volumes, etc.) needed to build and run a complete distributed application. + +You can use Compose to build your app with containers hosted locally, or on a remote server, including cloud-based instances. Compose can also be used to deploy code to production. + +Using Compose is basically a three-step process. + +First, you define your app's environment with a `Dockerfile` so it can be reproduced anywhere: FROM python:2.7 ADD . /code WORKDIR /code RUN pip install -r requirements.txt -Define the services that make up your app in `docker-compose.yml` so they can be -run together in an isolated environment: +Next, you define the services that make up your app in `docker-compose.yml` so they can be run together in an isolated environment: ```yaml web: @@ -32,24 +34,25 @@ db: (No more installing Postgres on your laptop!) -Then type `docker-compose up`, and Compose will start and run your entire app. +Lastly, run `docker-compose up` and Compose will start and run your entire app. -There are commands to: +Compose includes commands to: - - start, stop and rebuild services - - view the status of running services - - tail running services' log output - - run a one-off command on a service + * Start, stop and rebuild services + * View the status of running services + * tail the log output of running services + * run a one-off command on a service ## Quick start -Let's get a basic Python web app running on Compose. It assumes a little knowledge -of Python, but the concepts should be clear if you're not familiar with it. +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.html). -You'll want to make a directory for the project: +Next, you'll want to make a directory for the project: $ mkdir composetest $ cd composetest @@ -73,25 +76,29 @@ if __name__ == "__main__": app.run(host="0.0.0.0", debug=True) ``` -We define our Python dependencies in a file called `requirements.txt`: +Next, define the Python dependencies in a file called `requirements.txt`: flask redis -Next, we want to create a Docker image containing all of our app's dependencies. -We specify how to build one using a file called `Dockerfile`: +### 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 -This tells Docker to install Python, our code and our Python dependencies inside +This tells Docker to include Python, your code, and your Python dependencies in a Docker image. 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/). +[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/). -We then define a set of services using `docker-compose.yml`: +### Define services + +Next, define a set of services using `docker-compose.yml`: web: build: . @@ -107,14 +114,18 @@ We then define a set of services using `docker-compose.yml`: This defines two services: - - `web`, which is built from `Dockerfile` in the current directory. It also says - to run the command `python app.py` inside the image, forward the exposed port - 5000 on the container to port 5000 on the host machine, connect up the Redis - service, and mount the current directory inside the container so we can work - on code without having to rebuild the image. - - `redis`, which uses the public image [redis](https://registry.hub.docker.com/_/redis/). + - `web`, which is built from the `Dockerfile` in the current directory. It also + says to run the command `python app.py` inside the image, forward the exposed +port 5000 on the container to port 5000 on the host machine, connect up the +Redis service, and mount the current directory inside the container so we can +work on code without having to rebuild the image. + - `redis`, which uses the public image [redis](https://registry.hub.docker.com/_/redis/), which gets pulled from the + Docker Hub registry. -Now if we run `docker-compose up`, it'll pull a Redis image, build an image for our own code, and start everything up: +### 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... @@ -124,11 +135,12 @@ Now if we run `docker-compose up`, it'll pull a Redis image, build an image for 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/ -The web app should now be listening on port 5000 on your docker daemon (if you're -using boot2docker, `boot2docker ip` will tell you its address). +The web app should now be listening on port 5000 on your docker daemon (if +you're using boot2docker, `boot2docker ip` will tell you its address). -If you want to run your services in the background, you can pass the `-d` flag to -`docker-compose up` and use `docker-compose ps` to see what is currently running: +If you want to run your services in the background, you can pass the `-d` flag +(for daemon mode) to `docker-compose up` and use `docker-compose ps` to see what +is currently running: $ docker-compose up -d Starting composetest_redis_1... @@ -139,19 +151,17 @@ If you want to run your services in the background, you can pass the `-d` flag t composetest_redis_1 /usr/local/bin/run Up composetest_web_1 /bin/sh -c python app.py Up 5000->5000/tcp -`docker-compose run` allows you to run one-off commands for your services. For -example, to see what environment variables are available to the `web` service: +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` other commands that are available. +See `docker-compose --help` to see other 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 -That's more-or-less how Compose works. See the reference section below for full -details on the commands, configuration file and environment variables. If you -have any thoughts or suggestions, [open an issue on GitHub](https://github.com/docker/docker-compose). +At this point, you have seen the basics of how Compose works. See the reference section for complete details on the commands, configuration file and environment variables.