Engdocs 2080 (#19953)

* ENGDOCS-2080

* consistency fix

* file watch addition

* file watch addition

* edits

* edits

* review edits and further includes files

content/compose/compose-file/05-services.md

@@ -4,11 +4,7 @@ description: Explore all the attributes the services top-level element can have.
 keywords: compose, compose specification, services, compose file reference
 ---
 
-A service is an abstract definition of a computing resource within an application which can be scaled or replaced
-independently from other components. Services are backed by a set of containers, run by the platform
-according to replication requirements and placement constraints. As services are backed by containers, they are defined
-by a Docker image and set of runtime arguments. All containers within a service are identically created with these
-arguments.
+{{< include "compose/services.md" >}}
 
 A Compose file must declare a `services` top-level element as a map whose keys are string representations of service names,
 and whose values are service definitions. A service  definition contains the configuration that is applied to each
@@ -350,7 +346,7 @@ configs:
 
 ## depends_on
 
-`depends_on` expresses startup and shutdown dependencies between services.
+{{< include "compose/services-depends-on.md" >}}
 
 ### Short syntax
 
@@ -545,7 +541,7 @@ i.e. overridden to be empty.
 
 ## env_file
 
-`env_file` adds environment variables to the container based on the file content.
+{{< include "compose/services-env-file.md" >}} 
 
 ```yml
 env_file: .env
@@ -618,9 +614,7 @@ VAR="quoted"
 
 ## environment
 
-`environment` defines environment variables set in the container. `environment` can use either an array or a
-map. Any boolean values; true, false, yes, no, should be enclosed in quotes to ensure
-they are not converted to True or False by the YAML parser.
+{{< include "compose/services-environment.md" >}}
 
 Environment variables can be declared by a single key (no value to equals sign). In this case Compose
 relies on you to resolve the value. If the value is not resolved, the variable
@@ -938,9 +932,7 @@ been the case if `group_add` were not declared.
 
 ## healthcheck
 
-`healthcheck` declares a check that's run to determine whether or not the service containers are "healthy". It works in the same way, and has the same default values, as the
-[HEALTHCHECK Dockerfile instruction](https://docs.docker.com/reference/dockerfile/#healthcheck)
-set by the service's Docker image. Your Compose file can override the values set in the Dockerfile. 
+{{< include "compose/services-healthcheck.md" >}}
 
 ```yml
 healthcheck:
@@ -1169,8 +1161,7 @@ Compose file containing both attributes.
 
 ## networks
 
-`networks` defines the networks that service containers are attached to, referencing entries under the
-[top-level `networks` key](06-networks.md).
+{{< include "compose/services-networks.md" >}}
 
 ```yml
 services:
@@ -1358,7 +1349,7 @@ platform: linux/arm64/v8
 
 ## ports
 
-Exposes container ports.
+{{< include "compose/services-ports.md" >}}
 
 > **Note**
 >
@@ -1522,14 +1513,14 @@ When both are set, `scale` must be consistent with the `replicas` attribute in t
 
 ## secrets
 
-`secrets` grants access to sensitive data defined by [secrets](09-secrets.md) on a per-service basis. Two
-different syntax variants are supported; the short syntax and the long syntax.
+{{< include "compose/services-secrets.md" >}}
+
+Two different syntax variants are supported; the short syntax and the long syntax. Long and short syntax for secrets may be used in the same Compose file.
 
 Compose reports an error if the secret doesn't exist on the platform or isn't defined in the
-[`secrets`](09-secrets.md) section of the Compose file.
+`secrets` top-level section of the Compose file.
 
-Services can be granted access to multiple secrets. Long and short syntax for secrets may be used in the
-same Compose file. Defining a secret in the top-level `secrets` must not imply granting any service access to it.
+Defining a secret in the top-level `secrets` must not imply granting any service access to it.
 Such grant must be explicit within service specification as [secrets](09-secrets.md) service element.
 
 ### Short syntax
@@ -1728,11 +1719,7 @@ it is the runtime's decision to assign a UTS namespace, if supported. Available
 
 ## volumes
 
-`volumes` define mount host paths or named volumes that are accessible by service containers. You can use `volumes` to define multiple types of mounts; `volume`, `bind`, `tmpfs`, or `npipe`. 
-
-If the mount is a host path and is only used by a single service, it can be declared as part of the service
-definition. To reuse a volume across multiple services, a named
-volume must be declared in the [top-level `volumes` key](07-volumes.md).
+{{< include "compose/services-volumes.md" >}}
 
 The following example shows a named volume (`db-data`) being used by the `backend` service,
 and a bind mount defined for a single service.

content/compose/compose-file/06-networks.md

@@ -4,9 +4,9 @@ description: Explore all the attributes the networks top-level element can have.
 keywords: compose, compose specification, networks, compose file reference
 ---
 
-Networks are the layer that allow services to communicate with each other.
+{{< include "compose/networks.md" >}}
 
-The top-level `networks` element lets you configure named networks that can be reused across multiple services. To use a network across multiple services, you must explicitly grant each service access by using the [networks](05-services.md) attribute within the `services` top-level element. The `networks` top-level element has additional syntax that provides more granular control.
+To use a network across multiple services, you must explicitly grant each service access by using the [networks](05-services.md) attribute within the `services` top-level element. The `networks` top-level element has additional syntax that provides more granular control.
 
 ## Examples
 

content/compose/compose-file/07-volumes.md

@@ -4,9 +4,9 @@ description: Explore all the attributes the volumes top-level element can have.
 keywords: compose, compose specification, volumes, compose file reference
 ---
 
-Volumes are persistent data stores implemented by the container engine. Compose offers a neutral way for services to mount volumes, and configuration parameters to allocate them to infrastructure.
+{{< include "compose/volumes.md" >}}
 
-The top-level `volumes` declaration lets you configure named volumes that can be reused across multiple services. To use a volume across multiple services, you must explicitly grant each service access by using the [volumes](05-services.md#volumes) attribute within the `services` top-level element. The `volumes` attribute has additional syntax that provides more granular control.
+To use a volume across multiple services, you must explicitly grant each service access by using the [volumes](05-services.md#volumes) attribute within the `services` top-level element. The `volumes` attribute has additional syntax that provides more granular control.
 
 > **Tip**
 >

content/compose/compose-file/08-configs.md

@@ -4,12 +4,10 @@ description: Explore all the attributes the configs top-level element can have.
 keywords: compose, compose specification, configs, compose file reference
 ---
 
-Configs allow services to adapt their behaviour without the need to rebuild a Docker image.
+{{< include "compose/configs.md" >}}
 
 Services can only access configs when explicitly granted by a [`configs`](05-services.md#configs) attribute within the `services` top-level element.
 
-As with volumes, configs are mounted as files into a service's container's filesystem. The location of the mount point within the container defaults to `/<config-name>` in Linux containers and `C:\<config-name>` in Windows containers. 
-
 By default, the config:
 - Is owned by the user running the container command but can be overridden by service configuration.
 - Has world-readable permissions (mode 0444), unless the service is configured to override this.

content/compose/compose-file/10-fragments.md

@@ -4,7 +4,7 @@ description: Understand how to use fragments
 keywords: compose, compose specification, fragments, compose file reference
 ---
 
-With Compose, you can use built-in [YAML](https://www.yaml.org/spec/1.2/spec.html#id2765878) features to make your Compose file neater and more efficient. Anchors and aliases let you create re-usable blocks. This is useful if you start to find common configurations that span multiple services. Having re-usable blocks minimizes potential mistakes.
+{{< include "compose/fragments.md" >}}
 
 Anchors are created using the `&` sign. The sign is followed by an alias name. You can use this alias with the `*` sign later to reference the value following the anchor. Make sure there is no space between the `&` and the `*` characters and the following alias name. 
 

content/compose/compose-file/11-extension.md

@@ -4,10 +4,7 @@ description: Understand how to use extensions
 keywords: compose, compose specification, extensions, compose file reference
 ---
 
-As with [Fragments](10-fragments.md), Extensions can be used to make your Compose file more efficient and easier to maintain. Extensions can also be used with [anchors and aliases](10-fragments.md).
-
-Use the prefix `x-` as a top-level element to modularize configurations that you want to reuse. 
-Compose ignores any fields that start with `x-`, this is the sole exception where Compose silently ignores unrecognized fields.
+{{< include "compose/extension.md" >}}
 
 They also can be used within any structure in a Compose file where user-defined keys are not expected. 
 Compose uses those to enable experimental features, the same way browsers add support for [custom CSS features](https://www.w3.org/TR/2011/REC-CSS2-20110607/syndata.html#vendor-keywords)

content/compose/compose-file/12-interpolation.md

@@ -4,10 +4,9 @@ description: Learn about interpolation
 keywords: compose, compose specification, interpolation, compose file reference
 ---
 
-Values in a Compose file can be set by variables and interpolated at runtime. Compose files use a Bash-like
-syntax `${VARIABLE}`.
+{{< include "compose/interpolation.md" >}}
 
-Both `$VARIABLE` and `${VARIABLE}` syntax is supported. Default values can be defined inline using typical shell syntax:
+Default values can be defined inline using typical shell syntax:
 
 - `${VARIABLE:-default}` evaluates to `default` if `VARIABLE` is unset or
   empty in the environment.

content/compose/compose-file/13-merge.md

@@ -4,8 +4,9 @@ description: Learn about merging rules
 keywords: compose, compose specification, merge, compose file reference
 ---
 
-Compose lets you define a Compose application model through [multiple Compose files](https://docs.docker.com/compose/multiple-compose-files/). 
-When doing so, Compose follows the rules declared in this section to merge Compose files.
+{{< include "compose/merge.md" >}}
+
+These rules are outlined below. 
 
 ## Mapping
 

content/compose/compose-file/build.md

@@ -4,14 +4,7 @@ description: Learn about the Compose Build Specification
 keywords: compose, compose specification, compose file reference, compose build specification
 ---
 
-> **Note:** 
->
-> Build is an optional part of the Compose Specification
-
-A Compose implementation which focuses on running an application on a local machine needs to also support (re)building the application from source. The Compose Build Specification lets you define the build process within a Compose file
-in a portable way.
-
-`build` can be either specified as a single string defining a context path, or as a detailed build definition.
+{{< include "compose/build.md" >}}
 
 In the former case, the whole path is used as a Docker context to execute a Docker build, looking for a canonical
 `Dockerfile` at the root of the directory. The path can be absolute or relative. If it is relative, it is resolved

content/compose/compose-file/deploy.md

@@ -4,12 +4,7 @@ description: Learn about the Compose Deploy Specification
 keywords: compose, compose specification, compose file reference, compose deploy specification
 ---
 
-> **Note:** 
->
-> Deploy is an optional part of the Compose Specification
-
-The Compose Deploy Specification lets you declare additional metadata on services so Compose gets
-relevant data to allocate adequate resources on the platform and configure them to match your needs.
+{{< include "compose/deploy.md" >}}
 
 ## Attributes
 

content/compose/compose-file/develop.md

@@ -6,13 +6,11 @@ keywords: compose, compose specification, compose file reference, compose develo
 
 > **Note:** 
 >
-> Develop is an optional part of the Compose Specification. It's available with Docker Compose version 2.22.0 and later.
+> Develop is an optional part of the Compose Specification. It is available with Docker Compose version 2.22.0 and later.
 
-## Introduction
+{{< include "compose/develop.md" >}}
 
-Compose focuses on the development use-case of running applications on a local machine. It also supports some development hooks to improve the velocity of your local workflow, also known as your "inner loop". This document defines how Compose behaves to efficiently assist the developer.
-
-This section defines the development constraints and workflows set by Compose. Only a subset of
+This page defines how Compose behaves to efficiently assist you and defines the development constraints and workflows set by Compose. Only a subset of
 Compose file services may require a `develop` subsection.
 
 ## Illustrative example

content/compose/file-watch.md

@@ -6,9 +6,7 @@ title: Use Compose Watch
 
 {{< introduced compose 2.22.0 "release-notes.md#2220" >}}
 
-Use `watch` to automatically update and preview your running Compose services as you edit and save your code. 
-
-For many projects, this allows for a hands-off development workflow once Compose is running, as services automatically update themselves when you save your work.
+{{< include "compose/watch.md" >}}
 
 `watch` adheres to the following file path rules:
 * All paths are relative to the project directory
@@ -157,17 +155,7 @@ This pattern can be followed for many languages and frameworks, such as Python w
 
 ## Use `watch`
 
-1. Add `watch` sections to one or more services in `compose.yaml`.
-2. Run `docker compose up --watch` to build and launch a Compose project and start the file watch mode.
-3. Edit service source files using your preferred IDE or editor.
-
-> **Looking for a sample project to test things out?**
->
-> Check out [`dockersamples/avatars`](https://github.com/dockersamples/avatars),
-> or [local setup for Docker docs](https://github.com/docker/docs/blob/main/CONTRIBUTING.md)
-> for a demonstration of Compose `watch`.
-{ .tip }
-
+{{< include "compose/configure-watch.md" >}}
 
 > **Tip**
 >
@@ -175,6 +163,11 @@ This pattern can be followed for many languages and frameworks, such as Python w
 > get the application logs mixed with the (re)build logs and filesystem sync events.
 { .tip }
 
+> **Looking for a sample project to test things out?**
+>
+> Check out [`dockersamples/avatars`](https://github.com/dockersamples/avatars),
+> or [local setup for Docker docs](https://github.com/docker/docs/blob/main/CONTRIBUTING.md)
+> for a demonstration of Compose `watch`.
 
 ## Feedback
 

content/compose/multiple-compose-files/include.md

@@ -6,9 +6,9 @@ title: Include
 
 {{< introduced compose 2.20.3 "../release-notes.md#2203" >}}
 
-With the [`include` top-level element](../compose-file/14-include.md), you can include a separate Compose file directly in your local Compose file. This solves the relative path problem that [`extends`](extends.md) and [merge](merge.md) present. 
+{{< include "compose/include.md" >}}
 
-`include` makes it easier to modularize complex applications into sub-Compose files. This allows application configurations to be made simpler and more explicit. This also helps to reflect in the config file organization the engineering team responsible for the code.
+The [`include` top-level element](../compose-file/14-include.md) helps to reflect the engineering team responsible for the code directly in the config file's organization. It also solves the relative path problem that [`extends`](extends.md) and [merge](merge.md) present. 
 
 Each path listed in the `include` section loads as an individual Compose application model, with its own project directory, in order to resolve relative paths.
 

content/compose/profiles.md

@@ -4,15 +4,7 @@ desription: How to use profiles with Docker Compose
 keywords: cli, compose, profile, profiles reference
 ---
 
-Profiles help you adjust the Compose application model for various uses and
-environments by selectively starting services.
-This is achieved by assigning each service to zero or more profiles. If
-unassigned, the service is always started but if assigned, it is only started
-if the profile is activated.
-
-This allows you to define additional services in a single `compose.yml` file
-that should only be started in specific scenarios, for example for debugging or
-development tasks.
+{{< include "compose/profiles.md" >}}
 
 ## Assigning profiles to services
 

content/compose/use-secrets.md

@@ -7,7 +7,9 @@ tags: [Secrets]
 
 A secret is any piece of data, such as a password, certificate, or API key, that shouldn’t be transmitted over a network or stored unencrypted in a Dockerfile or in your application’s source code.
 
-Docker Compose provides a way for you to use secrets without having to use environment variables to store information. If you’re injecting passwords and API keys as environment variables, you risk unintentional information exposure. Environment variables are often available to all processes, and it can be difficult to track access. They can also be printed in logs when debugging errors without your knowledge. Using secrets mitigates these risks.
+{{< include "compose/secrets.md" >}}
+
+Environment variables are often available to all processes, and it can be difficult to track access. They can also be printed in logs when debugging errors without your knowledge. Using secrets mitigates these risks.
 
 ## Use secrets
 

content/includes/compose/build.md

@@ -0,0 +1 @@
+Build is an optional part of the Compose Specification. It tells Compose how to (re)build an application from source and lets you define the build process within a Compose file in a portable way.  `build` can be either specified as a single string defining a context path, or as a detailed build definition.

content/includes/compose/configs.md

@@ -0,0 +1 @@
+Configs let services to adapt their behaviour without the need to rebuild a Docker image. As with volumes, configs are mounted as files into a container's filesystem. The location of the mount point within the container defaults to `/<config-name>` in Linux containers and `C:\<config-name>` in Windows containers. 

content/includes/compose/configure-watch.md

@@ -0,0 +1,3 @@
+1. Add `watch` sections to one or more services in `compose.yaml`.
+2. Run `docker compose up --watch` to build and launch a Compose project and start the file watch mode.
+3. Edit service source files using your preferred IDE or editor.

content/includes/compose/deploy.md

@@ -0,0 +1 @@
+Deploy is an optional part of the Compose Specification. It is used to configure how services are deployed and managed in a Docker Swarm mode. Essentially, it provides a set of deployment specifications for managing the behavior of containers across different environments.

content/includes/compose/extension.md

@@ -0,0 +1,4 @@
+As with [Fragments](10-fragments.md), Extensions can be used to make your Compose file more efficient and easier to maintain. Extensions can also be used with [anchors and aliases](10-fragments.md).
+
+Use the prefix `x-` as a top-level element to modularize configurations that you want to reuse. 
+Compose ignores any fields that start with `x-`, this is the sole exception where Compose silently ignores unrecognized fields.

content/includes/compose/fragments.md

@@ -0,0 +1 @@
+With Compose, you can use built-in [YAML](https://www.yaml.org/spec/1.2/spec.html#id2765878) features to make your Compose file neater and more efficient. Anchors and aliases let you create re-usable blocks. This is useful if you start to find common configurations that span multiple services. Having re-usable blocks minimizes potential mistakes.

content/includes/compose/include.md

@@ -0,0 +1 @@
+With `include`, you can incorporate a separate `compose.yaml` file directly in your current `compose.yaml` file. This makes it easy to modularize complex applications into sub-Compose files, which in turn enables application configurations to be made simpler and more explicit.

content/includes/compose/interpolation.md

@@ -0,0 +1,2 @@
+Values in a Compose file can be set by variables and interpolated at runtime. Compose files use a Bash-like
+syntax `${VARIABLE}`. Both `$VARIABLE` and `${VARIABLE}` syntax is supported. 

content/includes/compose/merge.md

@@ -0,0 +1,2 @@
+Compose lets you define a Compose application model through [multiple Compose files](https://docs.docker.com/compose/multiple-compose-files/). 
+When doing so, Compose follows certain rules to merge Compose files.

content/includes/compose/networks.md

@@ -0,0 +1 @@
+Networks let services communicate with each other. By default Compose sets up a single network for your app. Each container for a service joins the default network and is both reachable by other containers on that network, and discoverable by the service's name. The top-level `networks` element lets you configure named networks that can be reused across multiple services. 

content/includes/compose/profiles.md

@@ -0,0 +1 @@
+Profiles help you adjust your Compose application for different environments or use cases by selectively activating services. Services can be assigned to one or more profiles; unassigned services start by default, while assigned ones only start when their profile is active. This setup means specific services, like those for debugging or development, to be included in a single `compose.yml` file and activated only as needed.

content/includes/compose/secrets.md

@@ -0,0 +1 @@
+Docker Compose provides a way for you to use secrets without having to use environment variables to store information. If you’re injecting passwords and API keys as environment variables, you risk unintentional information exposure. Services can only access secrets when explicitly granted by a `secrets` attribute within the `services` top-level element.

content/includes/compose/services-depends-on.md

@@ -0,0 +1 @@
+With the `depends_on` attribute, you can control the order of service startup and shutdown. It is useful if services are closely coupled, and the startup sequence impacts the application's functionality.

content/includes/compose/services-develop.md

@@ -0,0 +1 @@
+Develop lets Compose focus on the development use-case of running applications on a local machine. It also supports some development hooks to improve the velocity of your local workflow, also known as your "inner loop". 

content/includes/compose/services-env-file.md

@@ -0,0 +1 @@
+The `env_file` attribute is used to specify one or more files that contain environment variables to be passed to the containers.

content/includes/compose/services-environment.md

@@ -0,0 +1,3 @@
+The `environment` attribute defines environment variables set in the container. `environment` can use either an array or a
+map. Any boolean values; true, false, yes, no, should be enclosed in quotes to ensure
+they are not converted to True or False by the YAML parser.

content/includes/compose/services-healthcheck.md

@@ -0,0 +1,3 @@
+The `healthcheck` attribute declares a check that's run to determine whether or not the service containers are "healthy". It works in the same way, and has the same default values, as the
+[HEALTHCHECK Dockerfile instruction](https://docs.docker.com/reference/dockerfile/#healthcheck)
+set by the service's Docker image. Your Compose file can override the values set in the Dockerfile. 

content/includes/compose/services-networks.md

@@ -0,0 +1,2 @@
+The `networks` attribute defines the networks that service containers are attached to, referencing entries under the
+[`networks` top-level element](06-networks.md). The `networks` attribute helps manage the networking aspects of containers, providing control over how services are segmented and interact within the Docker environment. This is used to specify which networks the containers for that service should connect to. This is important for defining how containers communicate with each other and externally.

content/includes/compose/services-ports.md

@@ -0,0 +1 @@
+The `ports` is used to define the port mappings between the host machine and the containers.  This is crucial for allowing external access to services running inside containers. It can be defined using short syntax for simple port mapping or long syntax, which includes additional options like protocol type and network mode. 

content/includes/compose/services-secrets.md

@@ -0,0 +1 @@
+The `secrets` attribute grants access to sensitive data defined by the [secrets](09-secrets.md) top-level element on a per-service basis. Services can be granted access to multiple secrets.

content/includes/compose/services-volumes.md

@@ -0,0 +1,5 @@
+The `volumes` attribute define mount host paths or named volumes that are accessible by service containers. You can use `volumes` to define multiple types of mounts; `volume`, `bind`, `tmpfs`, or `npipe`. 
+
+If the mount is a host path and is only used by a single service, it can be declared as part of the service
+definition. To reuse a volume across multiple services, a named
+volume must be declared in the [top-level `volumes` key](07-volumes.md).

content/includes/compose/services.md

@@ -0,0 +1,5 @@
+A service is an abstract definition of a computing resource within an application which can be scaled or replaced
+independently from other components. Services are backed by a set of containers, run by the platform
+according to replication requirements and placement constraints. As services are backed by containers, they are defined
+by a Docker image and set of runtime arguments. All containers within a service are identically created with these
+arguments.

content/includes/compose/volumes.md

@@ -0,0 +1 @@
+Volumes are persistent data stores implemented by the container engine. Compose offers a neutral way for services to mount volumes, and configuration parameters to allocate them to infrastructure. The top-level `volumes` declaration lets you configure named volumes that can be reused across multiple services. 

content/includes/compose/watch.md

@@ -0,0 +1 @@
+The `watch` attribute automatically updates and previews your running Compose services as you edit and save your code. For many projects, this enables a hands-off development workflow once Compose is running, as services automatically update themselves when you save your work.