From 91c81cd3aca24125e2837f6ec34d11c2b259a0eb Mon Sep 17 00:00:00 2001 From: Allie Sadler <102604716+aevesdocker@users.noreply.github.com> Date: Fri, 4 Jul 2025 08:19:21 +0100 Subject: [PATCH] Merge pull request #22981 from aevesdocker/ENGDOCS-2805 Compose freshness: gpu, production, multiple files, oci artifacts --- .../manuals/compose/how-tos/gpu-support.md | 12 ++++++----- .../how-tos/multiple-compose-files/extends.md | 9 ++++----- .../how-tos/multiple-compose-files/include.md | 9 +++++---- .../manuals/compose/how-tos/oci-artifact.md | 20 ++++++++++++------- content/manuals/compose/how-tos/production.md | 15 +++++++++----- 5 files changed, 39 insertions(+), 26 deletions(-) diff --git a/content/manuals/compose/how-tos/gpu-support.md b/content/manuals/compose/how-tos/gpu-support.md index a9b0bb899f..8bbd955cb5 100644 --- a/content/manuals/compose/how-tos/gpu-support.md +++ b/content/manuals/compose/how-tos/gpu-support.md @@ -1,7 +1,7 @@ --- -description: Understand GPU support in Docker Compose +description: Learn how to configure Docker Compose to use NVIDIA GPUs with CUDA-based containers keywords: documentation, docs, docker, compose, GPU access, NVIDIA, samples -title: Enable GPU access with Docker Compose +title: Run Docker Compose services with GPU access linkTitle: Enable GPU support weight: 90 aliases: @@ -19,16 +19,18 @@ GPUs are referenced in a `compose.yaml` file using the [device](/reference/compo This provides more granular control over a GPU reservation as custom values can be set for the following device properties: -- `capabilities`. This value specifies as a list of strings (eg. `capabilities: [gpu]`). You must set this field in the Compose file. Otherwise, it returns an error on service deployment. -- `count`. This value, specified as an integer or the value `all`, represents the number of GPU devices that should be reserved (providing the host holds that number of GPUs). If `count` is set to `all` or not specified, all GPUs available on the host are used by default. +- `capabilities`. This value is specified as a list of strings. For example, `capabilities: [gpu]`. You must set this field in the Compose file. Otherwise, it returns an error on service deployment. +- `count`. Specified as an integer or the value `all`, represents the number of GPU devices that should be reserved (providing the host holds that number of GPUs). If `count` is set to `all` or not specified, all GPUs available on the host are used by default. - `device_ids`. This value, specified as a list of strings, represents GPU device IDs from the host. You can find the device ID in the output of `nvidia-smi` on the host. If no `device_ids` are set, all GPUs available on the host are used by default. -- `driver`. This value is specified as a string, for example `driver: 'nvidia'` +- `driver`. Specified as a string, for example `driver: 'nvidia'` - `options`. Key-value pairs representing driver specific options. > [!IMPORTANT] > > You must set the `capabilities` field. Otherwise, it returns an error on service deployment. + +> [!NOTE] > > `count` and `device_ids` are mutually exclusive. You must only define one field at a time. diff --git a/content/manuals/compose/how-tos/multiple-compose-files/extends.md b/content/manuals/compose/how-tos/multiple-compose-files/extends.md index 2ba1bb55b9..5380c555b2 100644 --- a/content/manuals/compose/how-tos/multiple-compose-files/extends.md +++ b/content/manuals/compose/how-tos/multiple-compose-files/extends.md @@ -1,7 +1,6 @@ --- -description: How to use Docker Compose's extends keyword to share configuration between - files and projects -keywords: fig, composition, compose, docker, orchestration, documentation, docs +description: Learn how to reuse service configurations across files and projects using Docker Compose’s extends attribute. +keywords: fig, composition, compose, docker, orchestration, documentation, docs, compose file modularization title: Extend your Compose file linkTitle: Extend weight: 20 @@ -29,7 +28,7 @@ configuration. Tracking which fragment of a service is relative to which path is difficult and confusing, so to keep paths easier to understand, all paths must be defined relative to the base file. -## How it works +## How the `extends` attribute works ### Extending services from another file @@ -62,7 +61,7 @@ You get exactly the same result as if you wrote `compose.yaml` with the same `build`, `ports`, and `volumes` configuration values defined directly under `web`. -To include the service `webapp` in the final project when extending services from another file, you need to explicitly include both services in your current Compose file. For example (note this is a non-normative example): +To include the service `webapp` in the final project when extending services from another file, you need to explicitly include both services in your current Compose file. For example (this is for illustrative purposes only): ```yaml services: diff --git a/content/manuals/compose/how-tos/multiple-compose-files/include.md b/content/manuals/compose/how-tos/multiple-compose-files/include.md index 2f0ebc22a6..db6139af59 100644 --- a/content/manuals/compose/how-tos/multiple-compose-files/include.md +++ b/content/manuals/compose/how-tos/multiple-compose-files/include.md @@ -18,7 +18,7 @@ Once the included Compose application loads, all resources are copied into the c > [!NOTE] > -> `include` applies recursively so an included Compose file which declares its own `include` section, results in those other files being included as well. +> `include` applies recursively so an included Compose file which declares its own `include` section, causes those files to also be included. ## Example @@ -48,11 +48,12 @@ services: `include` allows you to reference Compose files from remote sources, such as OCI artifacts or Git repositories. Here `serviceB` is defined in a Compose file stored on Docker Hub. -## Include and overrides +## Using overrides with included Compose files Compose reports an error if any resource from `include` conflicts with resources from the included Compose file. This rule prevents -unexpected conflicts with resources defined by the included compose file author. However, there may be some circumstances where you might want to tweak the +unexpected conflicts with resources defined by the included compose file author. However, there may be some circumstances where you might want to customize the included model. This can be achieved by adding an override file to the include directive: + ```yaml include: - path : @@ -61,7 +62,7 @@ include: ``` The main limitation with this approach is that you need to maintain a dedicated override file per include. For complex projects with multiple -includes this would result into many Compose files. +includes this would result in many Compose files. The other option is to use a `compose.override.yaml` file. While conflicts will be rejected from the file using `include` when same resource is declared, a global Compose override file can override the resulting merged model, as demonstrated in following example: diff --git a/content/manuals/compose/how-tos/oci-artifact.md b/content/manuals/compose/how-tos/oci-artifact.md index 0791df4e6f..6125ea989c 100644 --- a/content/manuals/compose/how-tos/oci-artifact.md +++ b/content/manuals/compose/how-tos/oci-artifact.md @@ -1,9 +1,9 @@ --- -title: Using Docker Compose with OCI artifacts +title: Package and deploy Docker Compose applications as OCI artifacts linkTitle: OCI artifact applications weight: 110 -description: How to publish and start Compose applications as OCI artifacts -keywords: cli, compose, oci, docker hub, artificats, publish, package, distribute +description: Learn how to package, publish, and securely run Docker Compose applications from OCI-compliant registries. +keywords: cli, compose, oci, docker hub, artificats, publish, package, distribute, docker compose oci support params: sidebar: badge: @@ -18,7 +18,7 @@ Docker Compose supports working with [OCI artifacts](/manuals/docker-hub/repos/m ## Publish your Compose application as an OCI artifact To distribute your Compose application as an OCI artifact, you can use the `docker compose publish` command, to publish it to an OCI-compliant registry. -This allows others to deploy your application directly from the registry. +This allows others to then deploy your application directly from the registry. The publish function supports most of the composition capabilities of Compose, like overrides, extends or include, [with some limitations](#limitations). @@ -84,12 +84,12 @@ Are you ok to publish these environment variables? [y/N]: If you decline, the publish process stops without sending anything to the registry. -### Limitations +## Limitations -There is limitations to publishing Compose applications as OCI artifacts. You can't publish a Compose configuration: +There are limitations to publishing Compose applications as OCI artifacts. You can't publish a Compose configuration: - With service(s) containing bind mounts - With service(s) containing only a `build` section -- That includes local files with the `include` attribute. To publish successfully, ensure that any included local files are also published. You can then `include` to reference these files as remote `include` is supported. +- That includes local files with the `include` attribute. To publish successfully, ensure that any included local files are also published. You can then use `include` to reference these files as remote `include` is supported. ## Start an OCI artifact application @@ -147,3 +147,9 @@ The `docker compose publish` command supports non-interactive execution, letting ```console $ docker compose publish -y username/my-compose-app:latest ``` + +## Next steps + +- [Learn about OCI artifacts in Docker Hub](/manuals/docker-hub/repos/manage/hub-images/oci-artifacts.md) +- [Compose publish command](/reference/cli/docker/compose/publish.md) +- [Understand `include`](/reference/compose-file/include.md) diff --git a/content/manuals/compose/how-tos/production.md b/content/manuals/compose/how-tos/production.md index 0392c00ff9..d2c8e41899 100644 --- a/content/manuals/compose/how-tos/production.md +++ b/content/manuals/compose/how-tos/production.md @@ -1,6 +1,6 @@ --- -description: Guide to using Docker Compose in production -keywords: compose, orchestration, containers, production +description: Learn how to configure, deploy, and update Docker Compose applications for production environments. +keywords: compose, orchestration, containers, production, production docker compose configuration title: Use Compose in production weight: 100 aliases: @@ -29,8 +29,8 @@ production. These changes might include: - Adding extra services such as a log aggregator For this reason, consider defining an additional Compose file, for example -`compose.production.yaml`, which specifies production-appropriate -configuration. This configuration file only needs to include the changes you want to make from the original Compose file. The additional Compose file +`compose.production.yaml`, with production-specific +configuration details. This configuration file only needs to include the changes you want to make from the original Compose file. The additional Compose file is then applied over the original `compose.yaml` to create a new configuration. Once you have a second configuration file, you can use it with the @@ -55,7 +55,7 @@ $ docker compose up --no-deps -d web This first command rebuilds the image for `web` and then stops, destroys, and recreates just the `web` service. The `--no-deps` flag prevents Compose from also -recreating any services which `web` depends on. +recreating any services that `web` depends on. ### Running Compose on a single server @@ -65,3 +65,8 @@ appropriately. For more information, see [pre-defined environment variables](env Once you've set up your environment variables, all the normal `docker compose` commands work with no further configuration. + +## Next steps + +- [Using multiple Compose files](multiple-compose-files/_index.md) +