Engdocs 1019 1021

_data/toc.yaml

@@ -1518,6 +1518,8 @@ manuals:
   section:
   - path: /compose/
     title: Overview
+  - path: /compose/features-uses/
+    title: Key features and use cases
   - sectiontitle: Install Docker Compose
     section:
       - path: /compose/install/
@@ -1529,7 +1531,13 @@ manuals:
       - path: /compose/install/uninstall/
         title: Uninstall Docker Compose
   - 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
     section:
     - path: /compose/environment-variables/
@@ -1552,8 +1560,6 @@ manuals:
     title: Control startup order
   - path: /compose/samples-for-compose/
     title: Sample apps with Compose
-  - path: /compose/cli-command-compatibility/
-    title: Compose v2 compatibility
   - path: /compose/release-notes/
     title: Release notes
 

compose/compose-v2/index.md

@@ -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).

compose/faq.md

@@ -112,6 +112,19 @@ the directory contents of the image.
 There are [many examples of Compose files on
 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/features-uses.md

@@ -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.

compose/gettingstarted.md

@@ -1,23 +1,23 @@
 ---
 description: Get started with Docker Compose
 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
-Compose. The application uses the Flask framework and maintains a hit counter in
-Redis. While the sample uses Python, the concepts demonstrated here should be
-understandable even if you're not familiar with it.
+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
+Redis. 
+
+The concepts demonstrated here should be understandable even if you're not familiar Python. 
 
 ## Prerequisites
 
-Make sure you have already installed both [Docker Engine](../get-docker.md)
-and [Docker Compose](install/index.md). You don't need to install Python or Redis, as
-both are provided by Docker images.
+You need to have Docker Engine and Docker Compose on your machine. You can either:
+- Install [Docker Engine](../get-docker.md) and [Docker Compose](install/index.md) as standalone binaries
+- 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:
 
@@ -26,7 +26,7 @@ Define the application dependencies.
    $ 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
    import time
@@ -62,13 +62,13 @@ Define the application dependencies.
    > 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
    > 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
    > cluster, this also helps handling momentary connection drops between
    > nodes.
 
 3. Create another file called `requirements.txt` in your project directory and
-   paste this in:
+   paste the following code in:
 
    ```text
    flask
@@ -77,12 +77,11 @@ Define the application dependencies.
 
 ## 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
 itself.
 
-In your project directory, create a file named `Dockerfile` and paste the
-following:
+In your project directory, create a file named `Dockerfile` and paste the following code in:
 
 ```dockerfile
 # 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.
 * 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
 [Docker user guide](../develop/index.md)
 and the [Dockerfile reference](/engine/reference/builder/).
@@ -132,13 +136,8 @@ services:
 
 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.
-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`.
-
-### Redis service
+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 `redis` service uses a public [Redis](https://registry.hub.docker.com/_/redis/) 
 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.
 
-   If you're using Docker natively on Linux, Docker Desktop for Mac, or Docker Desktop for
-   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.
+   If this doesn't resolve, you can also try http://127.0.0.1:8000.
 
    You should see a message in your browser saying:
 
@@ -346,12 +341,9 @@ container:
 $ docker compose down --volumes
 ```
 
-At this point, you have seen the basics of how Compose works.
-
-
 ## 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)
-- [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)