|
|
@@ -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
|
|
|
|
Daniel Nephin