docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

ENGDOCS-2586 (#22496) 

<!--Delete sections as needed -->

## Description

Freshness on some Compose sections

## Related issues or tickets

<!-- Related issues, pull requests, or Jira tickets -->

## Reviews

<!-- Notes for reviewers here -->
<!-- List applicable reviews (optionally @tag reviewers) -->

- [ ] Technical review
- [ ] Editorial review
- [ ] Product review

---------

Co-authored-by: Sarah Sanders <sarah.sanders@docker.com>
This commit is contained in:
Allie Sadler 2025-04-28 15:58:30 +01:00 committed by GitHub
parent ad49ff482f
commit eda11f9331
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
9 changed files with 66 additions and 89 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
content/manuals/compose/_index.md
View File

@ -40,8 +40,8 @@ grid:
description: Explore general FAQs and find out how to give feedback.
icon: help
link: /compose/faq
- title: Migrate to Compose V2
description: Learn how to migrate from Compose V1 to V2
- title: Migrate to Compose v2
description: Learn how to migrate from Compose v1 to v2
icon: folder_delete
link: /compose/releases/migrate/
aliases:
@ -55,7 +55,7 @@ aliases:
Docker Compose is a tool for defining and running multi-container applications.
It is the key to unlocking a streamlined and efficient development and deployment experience.
Compose simplifies the control of your entire application stack, making it easy to manage services, networks, and volumes in a single, comprehensible YAML configuration file. Then, with a single command, you create and start all the services
Compose simplifies the control of your entire application stack, making it easy to manage services, networks, and volumes in a single YAML configuration file. Then, with a single command, you create and start all the services
from your configuration file.
Compose works in all environments; production, staging, development, testing, as

4
content/manuals/compose/gettingstarted.md
View File

@ -16,13 +16,13 @@ Using the Flask framework, the application features a hit counter in Redis, prov
The concepts demonstrated here should be understandable even if you're not familiar with Python.
This is a non-normative example that just highlights the key things you can do with Compose.
This is a non-normative example that demonstrates core Compose functionality.
## Prerequisites
Make sure you have:
- Installed the latest version of Docker Compose
- [Installed the latest version of Docker Compose](/manuals/compose/install/_index.md)
- A basic understanding of Docker concepts and how Docker works
## Step 1: Set up

6
content/manuals/compose/intro/compose-application-model.md
View File

@ -23,7 +23,7 @@ Services store and share persistent data into [volumes](/reference/compose-file/
Some services require configuration data that is dependent on the runtime or platform. For this, the Specification defines a dedicated [configs](/reference/compose-file/configs.md) concept. From a service container point of view, configs are comparable to volumes, in that they are files mounted into the container. But the actual definition involves distinct platform resources and services, which are abstracted by this type.
A [secret](/reference/compose-file/secrets.md) is a specific flavor of configuration data for sensitive data that should not be exposed without security considerations. Secrets are made available to services as files mounted into their containers, but the platform-specific resources to provide sensitive data are specific enough to deserve a distinct concept and definition within the Compose specification.
A [secret](/reference/compose-file/secrets.md) is a specific flavor of configuration data for sensitive data that should not be exposed without security considerations. Secrets are made available to services as files mounted into their containers, but the platform-specific resources to provide sensitive data are specific enough to deserve a distinct concept and definition within the Compose Specification.
> [!NOTE]
>
@ -77,7 +77,7 @@ If you want to monitor the output of your running containers and debug issues, y
$ docker compose logs
```
To lists all the services along with their current status:
To list all the services along with their current status:
```console
$ docker compose ps
@ -148,7 +148,7 @@ networks:
back-tier: {}
```
The `docker compose up` command starts the `frontend` and `backend` services, create the necessary networks and volumes, and injects the configuration and secret into the frontend service.
The `docker compose up` command starts the `frontend` and `backend` services, creates the necessary networks and volumes, and injects the configuration and secret into the frontend service.
`docker compose ps` provides a snapshot of the current state of your services, making it easy to see which containers are running, their status, and the ports they are using:

18
content/manuals/compose/intro/history.md
View File

@ -1,7 +1,7 @@
---
title: History and development of Docker Compose
linkTitle: History and development
description: History of Compose V1 and Compose YAML schema versioning
description: History of Compose v1 and Compose YAML schema versioning
keywords: compose, compose yaml, swarm, migration, compatibility, docker compose vs docker-compose
weight: 30
aliases:
@ -10,14 +10,14 @@ aliases:
This page provides:
- A brief history of the development of the Docker Compose CLI
- A clear explanation of the major versions and file formats that make up Compose V1 and Compose V2
- The main differences between Compose V1 and Compose V2
- A clear explanation of the major versions and file formats that make up Compose v1 and Compose v2
- The main differences between Compose V1 and Compose v2
## Introduction
![Image showing the main differences between Compose V1 and Compose V2](../images/v1-versus-v2.png)
![Image showing the main differences between Compose v1 and Compose v2](../images/v1-versus-v2.png)
The image above shows that the currently supported version of the Docker Compose CLI is Compose V2 which is defined by the [Compose Specification](/reference/compose-file/_index.md).
The previous image shows that the currently supported version of the Docker Compose CLI is Compose v2 which is defined by the [Compose Specification](/reference/compose-file/_index.md).
It also provides a quick snapshot of the differences in file formats, command-line syntax, and top-level elements. This is covered in more detail in the following sections.
@ -27,7 +27,7 @@ Version one of the Docker Compose command-line binary was first released in 2014
Typically, Compose V1 projects include a top-level `version` element in the `compose.yaml` file, with values ranging from `2.0` to `3.8`, which refer to the specific [file formats](#compose-file-format-versioning).
Version two of the Docker Compose command-line binary was announced in 2020, is written in Go, and is invoked with `docker compose`.
Compose V2 ignores the `version` top-level element in the `compose.yaml` file.
Compose v2 ignores the `version` top-level element in the `compose.yaml` file.
### Compose file format versioning
@ -39,12 +39,12 @@ Three major versions of the Compose file format for Compose V1 were released:
- Compose file format 3.x with Compose 1.10.0 in 2017
Compose file format 1 is substantially different to all the following formats as it lacks a top-level `services` key.
Its usage is historical and files written in this format don't run with Compose V2.
Its usage is historical and files written in this format don't run with Compose v2.
Compose file format 2.x and 3.x are very similar to each other, but the latter introduced many new options targeted at Swarm deployments.
To address confusion around Compose CLI versioning, Compose file format versioning, and feature parity depending on whether Swarm mode was in use, file format 2.x and 3.x were merged into the [Compose Specification](/reference/compose-file/_index.md).
Compose V2 uses the Compose Specification for project definition. Unlike the prior file formats, the Compose Specification is rolling and makes the `version` top-level element optional. Compose V2 also makes use of optional specifications - [Deploy](/reference/compose-file/deploy.md), [Develop](/reference/compose-file/develop.md) and [Build](/reference/compose-file/build.md).
Compose v2 uses the Compose Specification for project definition. Unlike the prior file formats, the Compose Specification is rolling and makes the `version` top-level element optional. Compose v2 also makes use of optional specifications - [Deploy](/reference/compose-file/deploy.md), [Develop](/reference/compose-file/develop.md), and [Build](/reference/compose-file/build.md).
To make [migration](/manuals/compose/releases/migrate.md) easier, Compose V2 has backwards compatibility for certain elements that have been deprecated or changed between Compose file format 2.x/3.x and the Compose Specification.
To make [migration](/manuals/compose/releases/migrate.md) easier, Compose v2 has backwards compatibility for certain elements that have been deprecated or changed between Compose file format 2.x/3.x and the Compose Specification.

87
content/manuals/compose/releases/migrate.md
View File

@ -1,7 +1,7 @@
---
title: Migrate to Compose V2
title: Migrate to Compose v2
weight: 20
description: How to migrate from Compose V1 to V2
description: How to migrate from Compose v1 to v2
keywords: compose, upgrade, migration, v1, v2, docker compose vs docker-compose
aliases:
- /compose/compose-v2/
@ -9,26 +9,25 @@ aliases:
- /compose/migrate/
---
From July 2023 Compose V1 stopped receiving updates. It’s also no longer available in new releases of Docker Desktop.
From July 2023, Compose v1 stopped receiving updates. It’s also no longer available in new releases of Docker Desktop.
Compose V2, which was first released in 2020, is included with all currently supported versions of Docker Desktop. It offers an improved CLI experience, improved build performance with BuildKit, and continued new-feature development.
Compose v2, which was first released in 2020, is included with all currently supported versions of Docker Desktop. It offers an improved CLI experience, improved build performance with BuildKit, and continued new-feature development.
## How do I switch to Compose V2?
## How do I switch to Compose v2?
The easiest and recommended way is to make sure you have the latest version of [Docker Desktop](/manuals/desktop/release-notes.md), which bundles the Docker Engine and Docker CLI platform including Compose V2.
The easiest and recommended way is to make sure you have the latest version of [Docker Desktop](/manuals/desktop/release-notes.md), which bundles the Docker Engine and Docker CLI platform including Compose v2.
With Docker Desktop, Compose V2 is always accessible as `docker compose`.
Additionally, the **Use Compose V2** setting is turned on by default, which provides an alias from `docker-compose`.
With Docker Desktop, Compose v2 is always accessible as `docker compose`.
For manual installs on Linux, you can get Compose V2 by either:
For manual installs on Linux, you can get Compose v2 by either:
- [Using Docker's repository](/manuals/compose/install/linux.md#install-using-the-repository) (recommended)
- [Downloading and installing manually](/manuals/compose/install/linux.md#install-the-plugin-manually)
## What are the differences between Compose V1 and Compose V2?
## What are the differences between Compose v1 and Compose v2?
### `docker-compose` vs `docker compose`
Unlike Compose V1, Compose V2 integrates into the Docker CLI platform and the recommended command-line syntax is `docker compose`.
Unlike Compose v1, Compose v2 integrates into the Docker CLI platform and the recommended command-line syntax is `docker compose`.
The Docker CLI platform provides a consistent and predictable set of options and flags, such as the `DOCKER_HOST` environment variable or the `--context` command-line flag.
@ -37,49 +36,49 @@ For example, `docker --log-level=debug --tls compose up` enables debug logging f
> [!TIP]
>
> Update scripts to use Compose V2 by replacing the hyphen (`-`) with a space, using `docker compose` instead of `docker-compose`.
> Update scripts to use Compose v2 by replacing the hyphen (`-`) with a space, using `docker compose` instead of `docker-compose`.
### Service container names
Compose generates container names based on the project name, service name, and scale/replica count.
In Compose V1, an underscore (`_`) was used as the word separator.
In Compose V2, a hyphen (`-`) is used as the word separator.
In Compose v1, an underscore (`_`) was used as the word separator.
In Compose v2, a hyphen (`-`) is used as the word separator.
Underscores aren't valid characters in DNS hostnames.
By using a hyphen instead, Compose V2 ensures service containers can be accessed over the network via consistent, predictable hostnames.
By using a hyphen instead, Compose v2 ensures service containers can be accessed over the network via consistent, predictable hostnames.
For example, running the Compose command `-p myproject up --scale=1 svc` results in a container named `myproject_svc_1` with Compose V1 and a container named `myproject-svc-1` with Compose V2.
For example, running the Compose command `-p myproject up --scale=1 svc` results in a container named `myproject_svc_1` with Compose v1 and a container named `myproject-svc-1` with Compose v2.
> [!TIP]
>
>In Compose V2, the global `--compatibility` flag or `COMPOSE_COMPATIBILITY` environment variable preserves the Compose V1 behavior to use underscores (`_`) as the word separator.
As this option must be specified for every Compose V2 command run, it's recommended that you only use this as a temporary measure while transitioning to Compose V2.
> In Compose v2, the global `--compatibility` flag or `COMPOSE_COMPATIBILITY` environment variable preserves the Compose v1 behavior to use underscores (`_`) as the word separator.
As this option must be specified for every Compose v2 command run, it's recommended that you only use this as a temporary measure while transitioning to Compose v2.
### Command-line flags and subcommands
Compose V2 supports almost all Compose V1 flags and subcommands, so in most cases, it can be used as a drop-in replacement in scripts.
Compose v2 supports almost all Compose V1 flags and subcommands, so in most cases, it can be used as a drop-in replacement in scripts.
#### Unsupported in V2
#### Unsupported in v2
The following were deprecated in Compose V1 and aren't supported in Compose V2:
The following were deprecated in Compose v1 and aren't supported in Compose v2:
* `docker-compose scale`. Use `docker compose up --scale` instead.
* `docker-compose rm --all`
#### Different in V2
#### Different in v2
The following behave differently between Compose V1 and V2:
The following behave differently between Compose v1 and v2:
| | Compose V1 | Compose V2 |
| | Compose v1 | Compose v2 |
|-------------------------|------------------------------------------------------------------|-------------------------------------------------------------------------------|
| `--compatibility` | Deprecated. Migrates YAML fields based on legacy schema version. | Uses `_` as word separator for container names instead of `-` to match V1. |
| `--compatibility` | Deprecated. Migrates YAML fields based on legacy schema version. | Uses `_` as word separator for container names instead of `-` to match v1. |
| `ps --filter KEY-VALUE` | Undocumented. Allows filtering by arbitrary service properties. | Only allows filtering by specific properties, e.g. `--filter=status=running`. |
### Environment variables
Environment variable behavior in Compose V1 wasn't formally documented and behaved inconsistently in some edge cases.
Environment variable behavior in Compose v1 wasn't formally documented and behaved inconsistently in some edge cases.
For Compose V2, the [Environment variables](/manuals/compose/how-tos/environment-variables/_index.md) section covers both [precedence](/manuals/compose/how-tos/environment-variables/envvars-precedence.md) as well as [`.env` file interpolation](/manuals/compose/how-tos/environment-variables/variable-interpolation.md) and includes many examples covering tricky situations such as escaping nested quotes.
For Compose v2, the [Environment variables](/manuals/compose/how-tos/environment-variables/_index.md) section covers both [precedence](/manuals/compose/how-tos/environment-variables/envvars-precedence.md) as well as [`.env` file interpolation](/manuals/compose/how-tos/environment-variables/variable-interpolation.md) and includes many examples covering tricky situations such as escaping nested quotes.
Check if:
- Your project uses multiple levels of environment variable overrides, for example `.env` file and `--env` CLI flags.
@ -89,17 +88,17 @@ Check if:
> [!TIP]
>
> Run `docker compose config` on the project to preview the configuration after Compose V2 has performed interpolation to
> Run `docker compose config` on the project to preview the configuration after Compose v2 has performed interpolation to
verify that values appear as expected.
>
> Maintaining backwards compatibility with Compose V1 is typically achievable by ensuring that literal values (no
> Maintaining backwards compatibility with Compose v1 is typically achievable by ensuring that literal values (no
interpolation) are single-quoted and values that should have interpolation applied are double-quoted.
## What does this mean for my projects that use Compose V1?
## What does this mean for my projects that use Compose v1?
For most projects, switching to Compose V2 requires no changes to the Compose YAML or your development workflow.
For most projects, switching to Compose v2 requires no changes to the Compose YAML or your development workflow.
It's recommended that you adapt to the new preferred way of running Compose V2, which is to use `docker compose` instead of `docker-compose`.
It's recommended that you adapt to the new preferred way of running Compose v2, which is to use `docker compose` instead of `docker-compose`.
This provides additional flexibility and removes the requirement for a `docker-compose` compatibility alias.
However, Docker Desktop continues to support a `docker-compose` alias to redirect commands to `docker compose` for convenience and improved compatibility with third-party tools and scripts.
@ -108,28 +107,28 @@ However, Docker Desktop continues to support a `docker-compose` alias to redirec
### Migrating running projects
In both V1 and V2, running `up` on a Compose project recreates service containers as necessary to reach the desired state based on comparing the actual state in the Docker Engine to the resolved project configuration including Compose YAML, environment variables, and command-line flags.
In both v1 and v2, running up on a Compose project recreates service containers as needed. It compares the actual state in the Docker Engine to the resolved project configuration, which includes the Compose YAML, environment variables, and command-line flags.
Because Compose V1 and V2 [name service containers differently](#service-container-names), running `up` using V2 the first time on a project with running services originally launched by V1, results in service containers being recreated with updated names.
Because Compose v1 and v2 [name service containers differently](#service-container-names), running `up` using v2 the first time on a project with running services originally launched by v1, results in service containers being recreated with updated names.
Note that even if `--compatibility` flag is used to preserve the V1 naming style, Compose still needs to recreate service containers originally launched by V1 the first time `up` is run by V2 to migrate the internal state.
Note that even if `--compatibility` flag is used to preserve the v1 naming style, Compose still needs to recreate service containers originally launched by v1 the first time `up` is run by v2 to migrate the internal state.
### Using Compose V2 with Docker-in-Docker
### Using Compose v2 with Docker-in-Docker
Compose V2 is now included in the [Docker official image on Docker Hub](https://hub.docker.com/_/docker).
Compose v2 is now included in the [Docker official image on Docker Hub](https://hub.docker.com/_/docker).
Additionally, a new [docker/compose-bin image on Docker Hub](https://hub.docker.com/r/docker/compose-bin) packages the latest version of Compose V2 for use in multi-stage builds.
Additionally, a new [docker/compose-bin image on Docker Hub](https://hub.docker.com/r/docker/compose-bin) packages the latest version of Compose v2 for use in multi-stage builds.
## Can I still use Compose V1 if I want to?
## Can I still use Compose v1 if I want to?
Yes. You can still download and install Compose V1 packages, but you won't get support from Docker if anything breaks.
Yes. You can still download and install Compose v1 packages, but you won't get support from Docker if anything breaks.
>[!WARNING]
>
> The final Compose V1 release, version 1.29.2, was May 10, 2021. These packages haven't received any security updates since then. Use at your own risk.
> The final Compose v1 release, version 1.29.2, was May 10, 2021. These packages haven't received any security updates since then. Use at your own risk.
## Additional Resources
- [docker-compose V1 on PyPI](https://pypi.org/project/docker-compose/1.29.2/)
- [docker/compose V1 on Docker Hub](https://hub.docker.com/r/docker/compose)
- [docker-compose V1 source on GitHub](https://github.com/docker/compose/releases/tag/1.29.2)
- [docker-compose v1 on PyPI](https://pypi.org/project/docker-compose/1.29.2/)
- [docker/compose v1 on Docker Hub](https://hub.docker.com/r/docker/compose)
- [docker-compose v1 source on GitHub](https://github.com/docker/compose/releases/tag/1.29.2)

6
content/manuals/compose/releases/release-notes.md
View File

@ -27,16 +27,13 @@ For more detailed information, see the [release notes in the Compose repo](https
- Dependencies upgrade: bump docker engine and cli to v28.0.4
- Dependencies upgrade: bump buildx to v0.22.0
## 2.35.0
{{< release-date date="2025-04-10" >}}
### Bug fixes and enhancements
- Added support for Docker Model Runner to easily integrate AI models into your Compose applications
- Added support for [Docker Model Runner](/manuals/desktop/features/model-runner.md) to easily integrate AI models into your Compose applications
- Added `build --print` command to help debug complex build configurations by showing the equivalent bake file
- Added `volume.type=image` to provide more flexible volume management for container images
- Added `--quiet` options to the `run` command for cleaner output when running containers
@ -51,7 +48,6 @@ For more detailed information, see the [release notes in the Compose repo](https
- Dependencies upgrade: bump buildx to v0.23.0
- Dependencies upgrade: bump buildkit to v0.21.0
## 2.34.0
{{< release-date date="2025-03-14" >}}

6
content/manuals/compose/support-and-feedback/faq.md
View File

@ -11,9 +11,9 @@ aliases:
### What is the difference between `docker compose` and `docker-compose`
Version one of the Docker Compose command-line binary was first released in 2014. It was written in Python, and is invoked with `docker-compose`. Typically, Compose V1 projects include a top-level version element in the compose.yaml file, with values ranging from 2.0 to 3.8, which refer to the specific file formats.
Version one of the Docker Compose command-line binary was first released in 2014. It was written in Python, and is invoked with `docker-compose`. Typically, Compose v1 projects include a top-level version element in the `compose.yaml` file, with values ranging from 2.0 to 3.8, which refer to the specific file formats.
Version two of the Docker Compose command-line binary was announced in 2020, is written in Go, and is invoked with `docker compose`. Compose V2 ignores the version top-level element in the compose.yaml file.
Version two of the Docker Compose command-line binary was announced in 2020, is written in Go, and is invoked with `docker compose`. Compose v2 ignores the version top-level element in the compose.yaml file.
For further information, see [History and development of Compose](/manuals/compose/intro/history.md).
@ -91,7 +91,7 @@ any JSON file should be valid YAML. To use a JSON file with Compose,
specify the filename to use, for example:
```console
$ docker compose -f docker-compose.json up
$ docker compose -f compose.json up
```
### Should I include my code with `COPY`/`ADD` or a volume?

2
content/manuals/compose/support-and-feedback/feedback.md
View File

@ -21,4 +21,4 @@ To report bugs or problems, visit [Docker Compose on GitHub](https://github.com/
### Feedback via Community Slack channels
You can also provide feedback through the #docker-compose [Docker Community Slack](https://dockr.ly/comm-slack) channel.
You can also provide feedback through the `#docker-compose` [Docker Community Slack](https://dockr.ly/comm-slack) channel.

20
content/manuals/compose/support-and-feedback/samples-for-compose.md
View File

@ -17,30 +17,12 @@ if you have not already done so.
The samples should help you to:
- Define services based on Docker images using
[Compose files](/reference/compose-file/_index.md): `compose.yaml` and
`docker-stack.yml`
[Compose files](/reference/compose-file/_index.md)
- Understand the relationship between `compose.yaml` and
[Dockerfiles](/reference/dockerfile/)
- Learn how to make calls to your application services from Compose files
- Learn how to deploy applications and services to a [swarm](/manuals/engine/swarm/_index.md)
## Samples tailored to demo Compose
These samples focus specifically on Docker Compose:
- [Quickstart: Compose and ELK](https://github.com/docker/awesome-compose/tree/master/elasticsearch-logstash-kibana/README.md) - Shows
how to use Docker Compose to set up and run ELK - Elasticsearch-Logstash-Kibana.
- [Quickstart: Compose and Django](https://github.com/docker/awesome-compose/tree/master/official-documentation-samples/django/README.md) - Shows
how to use Docker Compose to set up and run a simple Django/PostgreSQL app.
- [Quickstart: Compose and Rails](https://github.com/docker/awesome-compose/tree/master/official-documentation-samples/rails/README.md) - Shows
how to use Docker Compose to set up and run a Rails/PostgreSQL app.
- [Quickstart: Compose and WordPress](https://github.com/docker/awesome-compose/tree/master/official-documentation-samples/wordpress/README.md) - Shows
how to use Docker Compose to set up and run WordPress in an isolated
environment with Docker containers.
## Awesome Compose samples
The Awesome Compose samples provide a starting point on how to integrate different frameworks and technologies using Docker Compose. All samples are available in the [Awesome-compose GitHub repo](https://github.com/docker/awesome-compose) and are ready to run with `docker compose up`.