mirror of https://github.com/docker/docs.git
Engdocs 1019 1021 (#15826)
* updated getting started guide * toc update * rearranging * fix broken link * fix broken links * naming tweaks * links fix * add icon links
This commit is contained in:
parent
ad614f1d2c
commit
fb95c6bc75
|
|
@ -1553,6 +1553,8 @@ manuals:
|
||||||
section:
|
section:
|
||||||
- path: /compose/
|
- path: /compose/
|
||||||
title: Overview
|
title: Overview
|
||||||
|
- path: /compose/features-uses/
|
||||||
|
title: Key features and use cases
|
||||||
- sectiontitle: Install Docker Compose
|
- sectiontitle: Install Docker Compose
|
||||||
section:
|
section:
|
||||||
- path: /compose/install/
|
- path: /compose/install/
|
||||||
|
|
@ -1564,7 +1566,13 @@ manuals:
|
||||||
- path: /compose/install/uninstall/
|
- path: /compose/install/uninstall/
|
||||||
title: Uninstall Docker Compose
|
title: Uninstall Docker Compose
|
||||||
- path: /compose/gettingstarted/
|
- path: /compose/gettingstarted/
|
||||||
title: Getting started
|
title: Try Docker Compose
|
||||||
|
- sectiontitle: Compose V2
|
||||||
|
section:
|
||||||
|
- path: /compose/compose-v2/
|
||||||
|
title: Overview
|
||||||
|
- path: /compose/cli-command-compatibility/
|
||||||
|
title: Compose v2 compatibility
|
||||||
- sectiontitle: Environment variables
|
- sectiontitle: Environment variables
|
||||||
section:
|
section:
|
||||||
- path: /compose/environment-variables/
|
- path: /compose/environment-variables/
|
||||||
|
|
@ -1587,8 +1595,6 @@ manuals:
|
||||||
title: Control startup order
|
title: Control startup order
|
||||||
- path: /compose/samples-for-compose/
|
- path: /compose/samples-for-compose/
|
||||||
title: Sample apps with Compose
|
title: Sample apps with Compose
|
||||||
- path: /compose/cli-command-compatibility/
|
|
||||||
title: Compose v2 compatibility
|
|
||||||
- path: /compose/release-notes/
|
- path: /compose/release-notes/
|
||||||
title: Release notes
|
title: Release notes
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -0,0 +1,45 @@
|
||||||
|
---
|
||||||
|
description: Key features and use cases of Docker Compose
|
||||||
|
keywords: documentation, docs, docker, compose, orchestration, containers, uses, features
|
||||||
|
title: Compose V2 Overview
|
||||||
|
---
|
||||||
|
|
||||||
|
## Compose V2 and the new `docker compose` command
|
||||||
|
|
||||||
|
> Important
|
||||||
|
>
|
||||||
|
> The new Compose V2, which supports the `compose` command as part of the Docker
|
||||||
|
> CLI, is now available.
|
||||||
|
>
|
||||||
|
> Compose V2 integrates compose functions into the Docker platform, continuing
|
||||||
|
> to support most of the previous `docker-compose` features and flags. You can
|
||||||
|
> run Compose V2 by replacing the hyphen (`-`) with a space, using `docker compose`,
|
||||||
|
> instead of `docker-compose`.
|
||||||
|
{: .important}
|
||||||
|
|
||||||
|
If you rely on using Docker Compose as `docker-compose` (with a hyphen), you can
|
||||||
|
set up Compose V2 to act as a drop-in replacement of the previous `docker-compose`.
|
||||||
|
Refer to the [Installing Compose](../install/index.md) section for detailed instructions.
|
||||||
|
|
||||||
|
## Context of Docker Compose evolution
|
||||||
|
|
||||||
|
Introduction of the [Compose specification](https://github.com/compose-spec/compose-spec){:target="_blank" rel="noopener" class="_"}
|
||||||
|
makes a clean distinction between the Compose YAML file model and the `docker-compose`
|
||||||
|
implementation. Making this change has enabled a number of enhancements, including
|
||||||
|
adding the `compose` command directly into the Docker CLI, being able to "up" a
|
||||||
|
Compose application on cloud platforms by simply switching the Docker context,
|
||||||
|
and launching of [Amazon ECS](../../cloud/ecs-integration.md) and [Microsoft ACI](../../cloud/aci-integration.md).
|
||||||
|
As the Compose specification evolves, new features land faster in the Docker CLI.
|
||||||
|
|
||||||
|
Compose V2 relies directly on the compose-go bindings which are maintained as part
|
||||||
|
of the specification. This allows us to include community proposals, experimental
|
||||||
|
implementations by the Docker CLI and/or Engine, and deliver features faster to
|
||||||
|
users. Compose V2 also supports some of the newer additions to the specification,
|
||||||
|
such as [profiles](../profiles.md) and [GPU](../gpu-support.md) devices.
|
||||||
|
|
||||||
|
Compose V2 has been re-written in [Go](https://go.dev), which improves integration
|
||||||
|
with other Docker command-line features, and allows it to run natively on
|
||||||
|
[macOS on Apple silicon](../../desktop/mac/apple-silicon.md), Windows, and Linux,
|
||||||
|
without dependencies such as Python.
|
||||||
|
|
||||||
|
For more information about compatibility with the compose v1 command-line, see the [docker-compose compatibility list](../cli-command-compatibility.md).
|
||||||
|
|
@ -112,6 +112,19 @@ the directory contents of the image.
|
||||||
There are [many examples of Compose files on
|
There are [many examples of Compose files on
|
||||||
GitHub](https://github.com/search?q=in%3Apath+docker-compose.yml+extension%3Ayml&type=Code).
|
GitHub](https://github.com/search?q=in%3Apath+docker-compose.yml+extension%3Ayml&type=Code).
|
||||||
|
|
||||||
|
## 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: use the [issue tracker on Github](https://github.com/docker/compose/issues).
|
||||||
|
|
||||||
|
* To talk about the project with people in real time: join the
|
||||||
|
`#docker-compose` channel on the Docker Community Slack.
|
||||||
|
|
||||||
|
* To contribute code or documentation changes: submit a [pull request on Github](https://github.com/docker/compose/pulls).
|
||||||
|
|
||||||
|
|
||||||
## Compose documentation
|
## Compose documentation
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -0,0 +1,131 @@
|
||||||
|
---
|
||||||
|
description: Key features and use cases of Docker Compose
|
||||||
|
keywords: documentation, docs, docker, compose, orchestration, containers, uses, features
|
||||||
|
title: Key features and use cases
|
||||||
|
---
|
||||||
|
|
||||||
|
Using Compose is essentially 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.
|
||||||
|
|
||||||
|
3. Run `docker compose up` and the [Docker compose command](compose-v2/index.md#compose-v2-and-the-new-docker-compose-command) starts and runs your entire app. You can alternatively run `docker-compose up` using Compose standalone(`docker-compose` binary).
|
||||||
|
|
||||||
|
A `docker-compose.yml` looks like this:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
version: "{{ site.compose_file_v3 }}" # optional since v1.27.0
|
||||||
|
services:
|
||||||
|
web:
|
||||||
|
build: .
|
||||||
|
ports:
|
||||||
|
- "8000:5000"
|
||||||
|
volumes:
|
||||||
|
- .:/code
|
||||||
|
- logvolume01:/var/log
|
||||||
|
depends_on:
|
||||||
|
- redis
|
||||||
|
redis:
|
||||||
|
image: redis
|
||||||
|
volumes:
|
||||||
|
logvolume01: {}
|
||||||
|
```
|
||||||
|
|
||||||
|
For more information about the Compose file, see the
|
||||||
|
[Compose file reference](compose-file/index.md).
|
||||||
|
|
||||||
|
## Key features of Docker Compose
|
||||||
|
|
||||||
|
### Have multiple isolated environments on a single host
|
||||||
|
|
||||||
|
Compose uses a project name to isolate environments from each other. You can make use of this project name in several different contexts:
|
||||||
|
|
||||||
|
* on a dev host, to create multiple copies of a single environment, such as when 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/index.md) or the
|
||||||
|
[`COMPOSE_PROJECT_NAME` environment variable](reference/envvars.md#compose_project_name).
|
||||||
|
|
||||||
|
The default project directory is the base directory of the Compose file. A custom value
|
||||||
|
for it can be defined with the `--project-directory` command line option.
|
||||||
|
|
||||||
|
|
||||||
|
### Preserves 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
|
||||||
|
the old container to the new container. This process ensures that any data
|
||||||
|
you've created in volumes isn't lost.
|
||||||
|
|
||||||
|
If you use `docker-compose` on a Windows machine, see
|
||||||
|
[Environment variables](reference/envvars.md) and adjust the necessary environment
|
||||||
|
variables for your specific needs.
|
||||||
|
|
||||||
|
|
||||||
|
### 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.
|
||||||
|
|
||||||
|
|
||||||
|
### Supports 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/compose-file-v3.md#variable-substitution) 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 of Docker Compose
|
||||||
|
|
||||||
|
Compose can be used in many different ways. Some common use cases are outlined
|
||||||
|
below.
|
||||||
|
|
||||||
|
### Development environments
|
||||||
|
|
||||||
|
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/index.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
|
||||||
|
|
||||||
|
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/index.md), you can create and destroy these environments in just a few commands:
|
||||||
|
|
||||||
|
```console
|
||||||
|
$ docker compose up -d
|
||||||
|
$ ./run_tests
|
||||||
|
$ docker compose down
|
||||||
|
```
|
||||||
|
|
||||||
|
### 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.
|
||||||
|
|
||||||
|
For details on using production-oriented features, see
|
||||||
|
[compose in production](production.md) in this documentation.
|
||||||
|
|
@ -1,23 +1,23 @@
|
||||||
---
|
---
|
||||||
description: Get started with Docker Compose
|
description: Get started with Docker Compose
|
||||||
keywords: documentation, docs, docker, compose, orchestration, containers
|
keywords: documentation, docs, docker, compose, orchestration, containers
|
||||||
title: Get started with Docker Compose
|
title: Try Docker Compose
|
||||||
---
|
---
|
||||||
|
|
||||||
On this page you build a simple Python web application running on Docker
|
This tutorial is designed to introduce the key concepts of Docker Compose whilst building a simple Python web application. The application uses the Flask framework and maintains a hit counter in
|
||||||
Compose. The application uses the Flask framework and maintains a hit counter in
|
Redis.
|
||||||
Redis. While the sample uses Python, the concepts demonstrated here should be
|
|
||||||
understandable even if you're not familiar with it.
|
The concepts demonstrated here should be understandable even if you're not familiar Python.
|
||||||
|
|
||||||
## Prerequisites
|
## Prerequisites
|
||||||
|
|
||||||
Make sure you have already installed both [Docker Engine](../get-docker.md)
|
You need to have Docker Engine and Docker Compose on your machine. You can either:
|
||||||
and [Docker Compose](install/index.md). You don't need to install Python or Redis, as
|
- Install [Docker Engine](../get-docker.md) and [Docker Compose](install/index.md) as standalone binaries
|
||||||
both are provided by Docker images.
|
- Install [Docker Desktop](../desktop/index.md) which includes both Docker Engine and Docker Compose
|
||||||
|
|
||||||
## Step 1: Setup
|
You don't need to install Python or Redis, as both are provided by Docker images.
|
||||||
|
|
||||||
Define the application dependencies.
|
## Step 1: Define the application dependencies
|
||||||
|
|
||||||
1. Create a directory for the project:
|
1. Create a directory for the project:
|
||||||
|
|
||||||
|
|
@ -26,7 +26,7 @@ Define the application dependencies.
|
||||||
$ cd composetest
|
$ cd composetest
|
||||||
```
|
```
|
||||||
|
|
||||||
2. Create a file called `app.py` in your project directory and paste this in:
|
2. Create a file called `app.py` in your project directory and paste the following code in:
|
||||||
|
|
||||||
```python
|
```python
|
||||||
import time
|
import time
|
||||||
|
|
@ -62,13 +62,13 @@ Define the application dependencies.
|
||||||
> Note the way the `get_hit_count` function is written. This basic retry
|
> Note the way the `get_hit_count` function is written. This basic retry
|
||||||
> loop lets us attempt our request multiple times if the redis service is
|
> loop lets us attempt our request multiple times if the redis service is
|
||||||
> not available. This is useful at startup while the application comes
|
> not available. This is useful at startup while the application comes
|
||||||
> online, but also makes our application more resilient if the Redis
|
> online, but also makes the application more resilient if the Redis
|
||||||
> service needs to be restarted anytime during the app's lifetime. In a
|
> service needs to be restarted anytime during the app's lifetime. In a
|
||||||
> cluster, this also helps handling momentary connection drops between
|
> cluster, this also helps handling momentary connection drops between
|
||||||
> nodes.
|
> nodes.
|
||||||
|
|
||||||
3. Create another file called `requirements.txt` in your project directory and
|
3. Create another file called `requirements.txt` in your project directory and
|
||||||
paste this in:
|
paste the following code in:
|
||||||
|
|
||||||
```text
|
```text
|
||||||
flask
|
flask
|
||||||
|
|
@ -77,12 +77,11 @@ Define the application dependencies.
|
||||||
|
|
||||||
## Step 2: Create a Dockerfile
|
## Step 2: Create a Dockerfile
|
||||||
|
|
||||||
In this step, you write a Dockerfile that builds a Docker image. The image
|
The Dockerfile is used to build a Docker image. The image
|
||||||
contains all the dependencies the Python application requires, including Python
|
contains all the dependencies the Python application requires, including Python
|
||||||
itself.
|
itself.
|
||||||
|
|
||||||
In your project directory, create a file named `Dockerfile` and paste the
|
In your project directory, create a file named `Dockerfile` and paste the following code in:
|
||||||
following:
|
|
||||||
|
|
||||||
```dockerfile
|
```dockerfile
|
||||||
# syntax=docker/dockerfile:1
|
# syntax=docker/dockerfile:1
|
||||||
|
|
@ -109,6 +108,11 @@ This tells Docker to:
|
||||||
* Copy the current directory `.` in the project to the workdir `.` in the image.
|
* Copy the current directory `.` in the project to the workdir `.` in the image.
|
||||||
* Set the default command for the container to `flask run`.
|
* Set the default command for the container to `flask run`.
|
||||||
|
|
||||||
|
>Important
|
||||||
|
>
|
||||||
|
>Check that the `Dockerfile` has no file extension like `.txt`. Some editors may append this file extension automatically and which results in an error when you run the application.
|
||||||
|
{: .important}
|
||||||
|
|
||||||
For more information on how to write Dockerfiles, see the
|
For more information on how to write Dockerfiles, see the
|
||||||
[Docker user guide](../develop/index.md)
|
[Docker user guide](../develop/index.md)
|
||||||
and the [Dockerfile reference](/engine/reference/builder/).
|
and the [Dockerfile reference](/engine/reference/builder/).
|
||||||
|
|
@ -132,13 +136,8 @@ services:
|
||||||
|
|
||||||
This Compose file defines two services: `web` and `redis`.
|
This Compose file defines two services: `web` and `redis`.
|
||||||
|
|
||||||
### Web service
|
|
||||||
|
|
||||||
The `web` service uses an image that's built from the `Dockerfile` in the current directory.
|
The `web` service uses an image that's built from the `Dockerfile` in the current directory.
|
||||||
It then binds the container and the host machine to the exposed port, `8000`. This example service uses the default port for
|
It then binds the container and the host machine to the exposed port, `8000`. This example service uses the default port for the Flask web server, `5000`.
|
||||||
the Flask web server, `5000`.
|
|
||||||
|
|
||||||
### Redis service
|
|
||||||
|
|
||||||
The `redis` service uses a public [Redis](https://registry.hub.docker.com/_/redis/)
|
The `redis` service uses a public [Redis](https://registry.hub.docker.com/_/redis/)
|
||||||
image pulled from the Docker Hub registry.
|
image pulled from the Docker Hub registry.
|
||||||
|
|
@ -175,11 +174,7 @@ image pulled from the Docker Hub registry.
|
||||||
|
|
||||||
2. Enter http://localhost:8000/ in a browser to see the application running.
|
2. Enter http://localhost:8000/ in a browser to see the application running.
|
||||||
|
|
||||||
If you're using Docker natively on Linux, Docker Desktop for Mac, or Docker Desktop for
|
If this doesn't resolve, you can also try http://127.0.0.1:8000.
|
||||||
Windows, then the web app should now be listening on port 8000 on your
|
|
||||||
Docker daemon host. Point your web browser to http://localhost:8000 to
|
|
||||||
find the `Hello World` message. If this doesn't resolve, you can also try
|
|
||||||
http://127.0.0.1:8000.
|
|
||||||
|
|
||||||
You should see a message in your browser saying:
|
You should see a message in your browser saying:
|
||||||
|
|
||||||
|
|
@ -346,12 +341,9 @@ container:
|
||||||
$ docker compose down --volumes
|
$ docker compose down --volumes
|
||||||
```
|
```
|
||||||
|
|
||||||
At this point, you have seen the basics of how Compose works.
|
|
||||||
|
|
||||||
|
|
||||||
## Where to go next
|
## Where to go next
|
||||||
|
|
||||||
- Next, try the [Sample apps with Compose](samples-for-compose.md)
|
- Next, try the [Sample apps with Compose](https://github.com/docker/awesome-compose)
|
||||||
- [Explore the full list of Compose commands](reference/index.md)
|
- [Explore the full list of Compose commands](reference/index.md)
|
||||||
- [Compose configuration file reference](compose-file/index.md)
|
- [Explore the Compose configuration file reference](compose-file/index.md)
|
||||||
- To learn more about volumes and bind mounts, see [Manage data in Docker](../storage/index.md)
|
- To learn more about volumes and bind mounts, see [Manage data in Docker](../storage/index.md)
|
||||||
|
|
|
||||||
266
compose/index.md
266
compose/index.md
|
|
@ -10,216 +10,88 @@ redirect_from:
|
||||||
- /compose/completion/
|
- /compose/completion/
|
||||||
---
|
---
|
||||||
|
|
||||||
>**Looking for Compose file reference?** [Find the latest version here](compose-file/index.md).
|
|
||||||
|
|
||||||
Compose is a tool for defining and running multi-container Docker applications.
|
Compose is a tool for defining and running multi-container Docker applications.
|
||||||
With Compose, you use a YAML file to configure your application's services.
|
With Compose, you use a YAML file to configure your application's services.
|
||||||
Then, with a single command, you create and start all the services
|
Then, with a single command, you create and start all the services
|
||||||
from your configuration. To learn more about all the features of Compose,
|
from your configuration.
|
||||||
see [the list of features](#features).
|
|
||||||
|
|
||||||
Compose works in all environments: production, staging, development, testing, as
|
Compose works in all environments: production, staging, development, testing, as
|
||||||
well as CI workflows. You can learn more about each case in [Common Use
|
well as CI workflows. It also has commands for managing the whole lifecycle of your application:
|
||||||
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.
|
|
||||||
|
|
||||||
3. Run `docker compose up` and the [Docker compose command](#compose-v2-and-the-new-docker-compose-command) starts and runs your entire app. You can alternatively run `docker-compose up` using Compose standalone(`docker-compose` binary).
|
|
||||||
|
|
||||||
A `docker-compose.yml` looks like this:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
version: "{{ site.compose_file_v3 }}" # optional since v1.27.0
|
|
||||||
services:
|
|
||||||
web:
|
|
||||||
build: .
|
|
||||||
ports:
|
|
||||||
- "8000:5000"
|
|
||||||
volumes:
|
|
||||||
- .:/code
|
|
||||||
- logvolume01:/var/log
|
|
||||||
depends_on:
|
|
||||||
- redis
|
|
||||||
redis:
|
|
||||||
image: redis
|
|
||||||
volumes:
|
|
||||||
logvolume01: {}
|
|
||||||
```
|
|
||||||
|
|
||||||
For more information about the Compose file, see the
|
|
||||||
[Compose file reference](compose-file/index.md).
|
|
||||||
|
|
||||||
Compose has commands for managing the whole lifecycle of your application:
|
|
||||||
|
|
||||||
* Start, stop, and rebuild services
|
* Start, stop, and rebuild services
|
||||||
* View the status of running services
|
* View the status of running services
|
||||||
* Stream the log output of running services
|
* Stream the log output of running services
|
||||||
* Run a one-off command on a service
|
* Run a one-off command on a service
|
||||||
|
|
||||||
## Compose V2 and the new `docker compose` command
|
The key features of Compose that make it effective are:
|
||||||
|
|
||||||
> Important
|
* [Have multiple isolated environments on a single host](features-uses.md#have-multiple-isolated-environments-on-a-single-host)
|
||||||
>
|
* [Preserves volume data when containers are created](features-uses.md#preserves-volume-data-when-containers-are-created)
|
||||||
> The new Compose V2, which supports the `compose` command as part of the Docker
|
* [Only recreate containers that have changed](features-uses.md#only-recreate-containers-that-have-changed)
|
||||||
> CLI, is now available.
|
* [Supports variables and moving a composition between environments](features-uses.md#supports-variables-and-moving-a-composition-between-environments)
|
||||||
>
|
|
||||||
> Compose V2 integrates compose functions into the Docker platform, continuing
|
|
||||||
> to support most of the previous `docker-compose` features and flags. You can
|
|
||||||
> run Compose V2 by replacing the hyphen (`-`) with a space, using `docker compose`,
|
|
||||||
> instead of `docker-compose`.
|
|
||||||
{: .important}
|
|
||||||
|
|
||||||
If you rely on using Docker Compose as `docker-compose` (with a hyphen), you can
|
<div class="component-container">
|
||||||
set up Compose V2 to act as a drop-in replacement of the previous `docker-compose`.
|
<!--start row-->
|
||||||
Refer to the [Installing Compose](install/index.md) section for detailed instructions.
|
<div class="row">
|
||||||
|
<div class="col-xs-12 col-sm-12 col-md-12 col-lg-4 block">
|
||||||
## Context of Docker Compose evolution
|
<div class="component">
|
||||||
|
<div class="component-icon">
|
||||||
Introduction of the [Compose specification](https://github.com/compose-spec/compose-spec){:target="_blank" rel="noopener" class="_"}
|
<a href="/compose/install/"><img src="/assets/images/download.svg" alt="Download and install" width="70" height="70"></a>
|
||||||
makes a clean distinction between the Compose YAML file model and the `docker-compose`
|
</div>
|
||||||
implementation. Making this change has enabled a number of enhancements, including
|
<h2 id="docker-compose"><a href="/compose/install/">Install Compose </a></h2>
|
||||||
adding the `compose` command directly into the Docker CLI, being able to "up" a
|
<p>Follow the instructions on how to install Docker Compose.</p>
|
||||||
Compose application on cloud platforms by simply switching the Docker context,
|
</div>
|
||||||
and launching of [Amazon ECS](../cloud/ecs-integration.md) and [Microsoft ACI](../cloud/aci-integration.md).
|
</div>
|
||||||
As the Compose specification evolves, new features land faster in the Docker CLI.
|
<div class="col-xs-12 col-sm-12 col-md-12 col-lg-4 block">
|
||||||
|
<div class="component">
|
||||||
Compose V2 relies directly on the compose-go bindings which are maintained as part
|
<div class="component-icon">
|
||||||
of the specification. This allows us to include community proposals, experimental
|
<a href="/compose/gettingstarted/"><img src="/assets/images/explore.svg" alt="Docker Compose" width="70" height="70"></a>
|
||||||
implementations by the Docker CLI and/or Engine, and deliver features faster to
|
</div>
|
||||||
users. Compose V2 also supports some of the newer additions to the specification,
|
<h2 id="docker-compose"><a href="/compose/gettingstarted/">Try Compose</a></h2>
|
||||||
such as [profiles](profiles.md) and [GPU](gpu-support.md) devices.
|
<p>Learn the key concepts of Docker Compose whilst building a simple Python web application.</p>
|
||||||
|
</div>
|
||||||
Compose V2 has been re-written in [Go](https://go.dev), which improves integration
|
</div>
|
||||||
with other Docker command-line features, and allows it to run natively on
|
<div class="col-xs-12 col-sm-12 col-md-12 col-lg-4 block">
|
||||||
[macOS on Apple silicon](../desktop/mac/apple-silicon.md), Windows, and Linux,
|
<div class="component">
|
||||||
without dependencies such as Python.
|
<div class="component-icon">
|
||||||
|
<a href="/compose/release-notes/"><img src="/assets/images/note-add.svg" alt="Release notes" width="70" height="70"></a>
|
||||||
For more information about compatibility with the compose v1 command-line, see the [docker-compose compatibility list](cli-command-compatibility.md).
|
</div>
|
||||||
|
<h2 id="docker-compose"><a href="/compose/release-notes/">View the release notes</a></h2>
|
||||||
|
<p>Find out about the latest enhancements and bug fixes.</p>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
<!--start row-->
|
||||||
|
<div class="row">
|
||||||
|
<div class="col-xs-12 col-sm-12 col-md-12 col-lg-4 block">
|
||||||
|
<div class="component">
|
||||||
|
<div class="component-icon">
|
||||||
|
<a href="/compose/features-uses/"><img src="/assets/images/help.svg" alt="FAQs" width="70" height="70"></a>
|
||||||
|
</div>
|
||||||
|
<h2 id="docker-compose"><a href="/compose/features-uses/">Understand key features of Compose</a></h2>
|
||||||
|
<p>Understand its key features and explore common use cases.</p>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
<div class="col-xs-12 col-sm-12 col-md-12 col-lg-4 block">
|
||||||
|
<div class="component">
|
||||||
|
<div class="component-icon">
|
||||||
|
<a href="/compose/compose-file/"><img src="/assets/images/all-inbox.svg" alt="Additional resources" width="70" height="70"></a>
|
||||||
|
</div>
|
||||||
|
<h2 id="docker-compose"><a href="/compose/compose-file/">Explore the Compose file reference</a></h2>
|
||||||
|
<p>Find information on defining services, networks, and volumes for a Docker application.</p>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
<div class="col-xs-12 col-sm-12 col-md-12 col-lg-4 block">
|
||||||
|
<div class="component">
|
||||||
|
<div class="component-icon">
|
||||||
|
<a href="/compose/faq/"><img src="/assets/images/sms.svg" alt="Give feedback" width="70" height="70"></a>
|
||||||
|
</div>
|
||||||
|
<h2 id="docker-compose"><a href="/compose/faq/">Browse common FAQs</a></h2>
|
||||||
|
<p>Explore general FAQs and find out how to give feedback.</p>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
|
||||||
## Features
|
|
||||||
|
|
||||||
The features of Compose that make it effective are:
|
|
||||||
|
|
||||||
* [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)
|
|
||||||
|
|
||||||
### Multiple isolated environments on a single host
|
|
||||||
|
|
||||||
Compose uses a project name to isolate environments from each other. You can make use of this project name in several different contexts:
|
|
||||||
|
|
||||||
* on a dev host, to create multiple copies of a single environment, such as when 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/index.md) or the
|
|
||||||
[`COMPOSE_PROJECT_NAME` environment variable](reference/envvars.md#compose_project_name).
|
|
||||||
|
|
||||||
The default project directory is the base directory of the Compose file. A custom value
|
|
||||||
for it can be defined with the `--project-directory` command line option.
|
|
||||||
|
|
||||||
|
|
||||||
### 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
|
|
||||||
the old container to the new container. This process ensures that any data
|
|
||||||
you've created in volumes isn't lost.
|
|
||||||
|
|
||||||
If you use `docker-compose` on a Windows machine, see
|
|
||||||
[Environment variables](reference/envvars.md) and adjust the necessary environment
|
|
||||||
variables for your specific needs.
|
|
||||||
|
|
||||||
|
|
||||||
### 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 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/compose-file-v3.md#variable-substitution) 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
|
|
||||||
|
|
||||||
Compose can be used in many different ways. Some common use cases are outlined
|
|
||||||
below.
|
|
||||||
|
|
||||||
### Development environments
|
|
||||||
|
|
||||||
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/index.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
|
|
||||||
|
|
||||||
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/index.md), you can create and destroy these environments in just a few commands:
|
|
||||||
|
|
||||||
```console
|
|
||||||
$ docker compose up -d
|
|
||||||
$ ./run_tests
|
|
||||||
$ docker compose down
|
|
||||||
```
|
|
||||||
|
|
||||||
### 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.
|
|
||||||
|
|
||||||
For details on using production-oriented features, see
|
|
||||||
[compose in production](production.md) in this documentation.
|
|
||||||
|
|
||||||
|
|
||||||
## Release notes
|
|
||||||
|
|
||||||
To see a detailed list of changes for past and current releases of Docker
|
|
||||||
Compose, refer to the
|
|
||||||
[CHANGELOG](https://github.com/docker/compose/blob/master/CHANGELOG.md).
|
|
||||||
|
|
||||||
## 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: use the [issue tracker on Github](https://github.com/docker/compose/issues).
|
|
||||||
|
|
||||||
* To talk about the project with people in real time: join the
|
|
||||||
`#docker-compose` channel on the Docker Community Slack.
|
|
||||||
|
|
||||||
* To contribute code or documentation changes: submit a [pull request on Github](https://github.com/docker/compose/pulls).
|
|
||||||
|
|
|
||||||
|
|
@ -34,7 +34,7 @@ On the **General** tab, you can configure when to start Docker and specify other
|
||||||
dashboard when starting Docker Desktop.
|
dashboard when starting Docker Desktop.
|
||||||
|
|
||||||
- **Use Docker Compose V2**. Select to enable the `docker-compose` command to
|
- **Use Docker Compose V2**. Select to enable the `docker-compose` command to
|
||||||
use Docker Compose V2. For more information, see [Docker Compose V2](../../compose/index.md#compose-v2-and-the-new-docker-compose-command).
|
use Docker Compose V2. For more information, see [Docker Compose V2](../../compose/compose-v2/index.md).
|
||||||
|
|
||||||
## Resources
|
## Resources
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -45,7 +45,7 @@ On the **General** tab, you can configure when to start Docker and specify other
|
||||||
dashboard when starting Docker Desktop.
|
dashboard when starting Docker Desktop.
|
||||||
|
|
||||||
- **Use Docker Compose V2**. Select to enable the `docker-compose` command to
|
- **Use Docker Compose V2**. Select to enable the `docker-compose` command to
|
||||||
use Docker Compose V2. For more information, see [Docker Compose V2](../../compose/index.md#compose-v2-and-the-new-docker-compose-command).
|
use Docker Compose V2. For more information, see [Docker Compose V2](../../compose/compose-v2/index.md).
|
||||||
|
|
||||||
## Resources
|
## Resources
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -42,7 +42,7 @@ On the **General** tab, you can configure when to start Docker and specify other
|
||||||
dashboard when starting Docker Desktop.
|
dashboard when starting Docker Desktop.
|
||||||
|
|
||||||
- **Use Docker Compose V2**. Select to enable the `docker-compose` command to
|
- **Use Docker Compose V2**. Select to enable the `docker-compose` command to
|
||||||
use Docker Compose V2. For more information, see [Docker Compose V2](../../compose/index.md#compose-v2-and-the-new-docker-compose-command).
|
use Docker Compose V2. For more information, see [Docker Compose V2](../../compose/compose-v2/index.md).
|
||||||
|
|
||||||
## Resources
|
## Resources
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue