5.6 KiB

Raw Blame History

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 from your configuration. To learn more about all the features of Compose see the list of features

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.

Using Compose is basically a three-step process.

Define your app's environment with a Dockerfile so it can be reproduced anywhere.
Define the services that make up your app in docker-compose.yml so they can be run together in an isolated environment.
Lastly, run docker-compose up and Compose will start and run your entire app.

A docker-compose.yml looks like this:

web:
  build: .
  ports:
   - "5000:5000"
  volumes:
   - .:/code
  links:
   - redis
redis:
  image: redis

For more information about the Compose file, see the Compose file reference

Compose has commands for managing the whole lifecycle of your application:

Start, stop and rebuild services
View the status of running services
Stream the log output of running services
Run a one-off command on a service

Compose documentation

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 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 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) 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 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 or a Docker Swarm cluster.

See compose in production 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.

Getting help

Docker Compose is under active development. If you need help, would like to contribute, or simply want to talk about the project with like-minded individuals, we have a number of open channels for communication.

To report bugs or file feature requests: please use the issue tracker on Github.
To talk about the project with people in real time: please join the #docker-compose channel on freenode IRC.
To contribute code or documentation changes: please submit a pull request on Github.

For more information and resources, please visit the Getting Help project page.

5.6 KiB Raw Blame History