Merge pull request #2165 from dnephin/more_user_docs

Restructure intro docs

README.md

@@ -2,15 +2,15 @@ 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 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](docs/index.md#features).
 
-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 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 +33,9 @@ A `docker-compose.yml` looks like this:
     redis:
       image: redis
 
+For more information about the Compose file, see the
+[Compose file reference](docs/compose-file.md)
+
 Compose has commands for managing the whole lifecycle of your application:
 
  * Start, stop and rebuild services

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
 +++
 <![end-metadata]-->
 

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

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)

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)

docs/gettingstarted.md

@@ -0,0 +1,188 @@
+<!--[metadata]>
++++
+title = "Getting Started"
+description = "Getting started with Docker Compose"
+keywords = ["documentation, docs,  docker, compose, orchestration, containers"]
+[menu.main]
+parent="smn_workw_compose"
+weight=3
++++
+<![end-metadata]-->
+
+
+# Getting Started
+
+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.
+
+## Prerequisites
+
+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.
+
+## Step 1: Setup
+
+1. Create a directory for the project:
+
+        $ mkdir composetest
+        $ cd composetest
+
+2. With your favorite text editor create a file called `app.py` in your project
+   directory.
+
+        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)
+
+3. Create another file called `requirements.txt` in your project directory and
+   add the following:
+
+        flask
+        redis
+
+   These define the applications dependencies.
+
+## Step 2: Create a Docker image
+
+In this step, you build a new Docker image. The image contains all the
+dependencies the Python application requires, including Python itself.
+
+1. In your project directory create a file named `Dockerfile` and add the
+   following:
+
+        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/).
+
+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`:
+
+1. Create a file called docker-compose.yml in your project directory and add
+   the following:
+
+        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.
+* 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.
+
+## Step 4: Build and run your app with Compose
+
+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
+
+   Compose pulls a Redis image, builds an image for your code, and start the
+   services you defined.
+
+2. Enter `http://0.0.0.0:5000/` in a browser to see the application running.
+
+   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.
+
+   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.
+
+   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
+
+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.
+
+
+## Where to go next
+
+- Next, try the quick start guide for [Django](django.md),
+  [Rails](rails.md), or [WordPress](wordpress.md).
+- [Explore the full list of Compose commands](./reference/index.md)
+- [Compose configuration file reference](compose-file.md)

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 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).
 
-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](compose-file.md)
+
 Compose has commands for managing the whole lifecycle of your application:
 
  * Start, stop and rebuild services
@@ -50,155 +55,119 @@ 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
+## Features
 
-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):
+The features of Compose that make it effective are:
 
-    from flask import Flask
-    from redis import Redis
+* [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)
 
-    app = Flask(__name__)
-    redis = Redis(host='redis', port=6379)
+#### Multiple isolated environments on a single host
 
-    @app.route('/')
-    def hello():
-        redis.incr('hits')
-        return 'Hello World! I have been seen %s times.' % redis.get('hits')
+Compose uses a project name to isolate environments from each other. You can use
+this project name to:
 
-    if __name__ == "__main__":
-        app.run(host="0.0.0.0", debug=True)
+* 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
 
-Next, define the Python dependencies in a file called `requirements.txt`:
+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).
 
-    flask
-    redis
+#### Preserve volume data when containers are created
 
-### Create a Docker image
+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.
 
-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
+#### Only recreate containers that have changed
 
-This tells Docker to:
+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.
 
-* 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:
+#### Variables and moving a composition between environments
 
-* 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.
+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.
 
-The `redis` service uses the latest public [Redis](https://registry.hub.docker.com/_/redis/) image pulled from the Docker Hub registry.
+You can extend a Compose file using the `extends` field or by creating multiple
+Compose files. See [extends](extends.md) for more details.
 
-### 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:
+## Common Use Cases
 
-    $ 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
+Compose can be used in many different ways. Some common use cases are outlined
+below.
 
-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.
+### Development environments
 
-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`.
+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.
 
-You should get a message in your browser saying:
+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`).
 
-`Hello World! I have been seen 1 times.`
+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.
 
-Refreshing the page will increment the number.
+### Automated testing environments
 
-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:
+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](compose-file.md) you can create and destroy these
+environments in just a few commands:
 
     $ 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.
+    $ ./run_tests
+    $ docker-compose stop
+    $ docker-compose rm -f
 
-If you started Compose with `docker-compose up -d`, you'll probably want to stop
-your services once you've finished with them:
+### Single host deployments
 
-    $ docker-compose stop
+Compose has traditionally been focused on development and testing workflows,
+but with each release we're making progress on more production-oriented features.
+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.
 
-At this point, you have seen the basics of how Compose works.
+For details on using production-oriented features, see
+[compose in production](production.md) in this documentation.
 
-- 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
 
 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
 

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)

docs/production.md

@@ -86,8 +86,5 @@ guide</a>.
 ## 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)

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)

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)