From 7d48392476f9afed107d93fa446b8d98fea50f8e Mon Sep 17 00:00:00 2001 From: Guillaume Lours <705411+glours@users.noreply.github.com> Date: Thu, 13 Mar 2025 11:34:40 +0100 Subject: [PATCH 1/4] add Compose OCI artifact how-to page Signed-off-by: Guillaume Lours <705411+glours@users.noreply.github.com> --- content/includes/compose/oci-artifact.md | 1 + .../manuals/compose/how-tos/oci-artifact.md | 136 ++++++++++++++++++ 2 files changed, 137 insertions(+) create mode 100644 content/includes/compose/oci-artifact.md create mode 100644 content/manuals/compose/how-tos/oci-artifact.md diff --git a/content/includes/compose/oci-artifact.md b/content/includes/compose/oci-artifact.md new file mode 100644 index 000000000000..03b6166e4dcc --- /dev/null +++ b/content/includes/compose/oci-artifact.md @@ -0,0 +1 @@ +Docker Compose supports working with [OCI artifacts](https://docs.docker.com/docker-hub/repos/manage/hub-images/oci-artifacts/), allowing you to package and distribute your Compose applications through container registries. This means you can store your Compose files alongside your container images, making it easier to version, share, and deploy your multi-container applications. \ No newline at end of file diff --git a/content/manuals/compose/how-tos/oci-artifact.md b/content/manuals/compose/how-tos/oci-artifact.md new file mode 100644 index 000000000000..f2822e7c7ae2 --- /dev/null +++ b/content/manuals/compose/how-tos/oci-artifact.md @@ -0,0 +1,136 @@ +--- +title: Using Docker Compose with OCI artifacts +linkTitle: Use Compose OCI artifacts applications +weight: 20 +description: How to start and publish Compose applications as OCI artifacts +keywords: cli, compose, oci +aliases: +- /compose/oci-artifact/ +--- + +{{% include "compose/oci-artifact.md" %}} + +## Starting an OCI artifact application + +To start a Docker Compose application using an OCI artifact, you can use the `-f` (or `--file`) flag followed by the OCI artifact reference. +This allows you to specify a Compose file stored as an OCI artifact in a registry. +The `oci://` prefix indicates that the Compose file should be pulled from an OCI-compliant registry rather than loaded from the local filesystem. + +```bash +$ docker compose -f oci://docker.io/username/my-compose-app:latest up +``` + +To run the Compose application, use the `docker compose` command with the `-f` flag pointing to your OCI artifact: +```bash +$ docker compose -f oci://docker.io/username/my-compose-app:latest up +``` + +### Warnings/Messages displayed + +When you run an application from an OCI artifact, Compose may display warning messages requiring your confirmation to limit risks of running a malicious application: +* Listing the interpolation variables used along with their values +* Listing all environment variables used by the application +* Let you know if your OCI artifact application is using another remote resources (via [`include`](/reference/compose-file/include/) for example) + +```bash +$ REGISTRY=myregistry.com docker compose -f oci://docker.io/username/my-compose-app:latest up + +Found the following variables in configuration: +VARIABLE VALUE SOURCE REQUIRED DEFAULT +REGISTRY myregistry.com command-line yes +TAG v1.0 environment no latest +DOCKERFILE Dockerfile default no Dockerfile +API_KEY none no + +Do you want to proceed with these variables? [Y/n]:y + +Warning: This Compose project includes files from remote sources: +- oci://registry.example.com/stack:latest +Remote includes could potentially be malicious. Make sure you trust the source. +Do you want to continue? [y/N]: +``` + +If you agree to start the application, Compose will display the directory where all the resources from the OCI artifact have been downloaded. +```bash +... +Do you want to continue? [y/N]: y + +Your compose stack "oci://registry.example.com/stack:latest" is stored in "~/Library/Caches/docker-compose/964e715660d6f6c3b384e05e7338613795f7dcd3613890cfa57e3540353b9d6d" +``` +--- + +## Publishing your Compose application as an OCI artifact + +To distribute your Compose application as an OCI artifact, you can **publish** it to an OCI-compliant registry. +This allows others to 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-and-considerations) + +### Steps + +1. Navigate to Your Compose Application Directory + Ensure you're in the directory containing your `compose.yml` file or that you are specifying your Compose file with the `-f` flag. + +2. Log in to Docker Hub + Before publishing, make sure you're authenticated with Docker Hub: + + ```bash + $ docker login + ``` + +3. Publish the Compose application to Docker Hub + Use the `docker compose publish` command to push your application as an OCI artifact: + + ```bash + $ docker compose publish username/my-compose-app:latest + ``` + or passing multiple Compose files + ```bash + $ docker compose -f compose-base.yml -f compose-production.yml publish username/my-compose-app:latest + ``` +When publishing you can use options to specify the OCI version, whether to resolve image digests and if you want to include environment variables: +* `--oci-version`: Specify the OCI version (default is automatically determined). +* `--resolve-image-digests`: Pin image tags to digests. +* `--with-env`: Include environment variables in the published OCI artifact. + +Compose checks for you if there isn't any sensitive data in your configuration and displays your environment variables to confirm you want to publish them. + +```bash +... +you are about to publish sensitive data within your OCI artifact. +please double check that you are not leaking sensitive data +AWS Client ID +"services.serviceA.environment.AWS_ACCESS_KEY_ID": xxxxxxxxxx +AWS Secret Key +"services.serviceA.environment.AWS_SECRET_ACCESS_KEY": aws"xxxx/xxxx+xxxx+" +Github authentication +"GITHUB_TOKEN": ghp_xxxxxxxxxx +JSON Web Token +"": xxxxxxx.xxxxxxxx.xxxxxxxx +Private Key +"": -----BEGIN DSA PRIVATE KEY----- +xxxxx +-----END DSA PRIVATE KEY----- +Are you ok to publish these sensitive data? [y/N]:y + +you are about to publish environment variables within your OCI artifact. +please double check that you are not leaking sensitive data +Service/Config serviceA +FOO=bar +Service/Config serviceB +FOO=bar +QUIX= +BAR=baz +Are you ok to publish these environment variables? [y/N]: +``` + +If you refuse the publish process will stop without sending anything to the registry. + +--- + +## Limitations and considerations + +There is limitations to publishing Compose applications as OCI artifacts: +* You can't publish Compose configuration with service(s) containing bind mounts +* You can't publish Compose configuration with service(s) containing only `build` section +* You can't publish Compose configuration using `include` of local files, publish them as well as remote `include` is supported From b1ff63ef8ff92fd7d9a3de97f8436e908c0cf1c6 Mon Sep 17 00:00:00 2001 From: aevesdocker Date: Mon, 17 Mar 2025 09:49:04 +0000 Subject: [PATCH 2/4] edits --- content/includes/compose/oci-artifact.md | 1 - .../manuals/compose/how-tos/oci-artifact.md | 169 +++++++++--------- data/summary.yaml | 2 + 3 files changed, 90 insertions(+), 82 deletions(-) delete mode 100644 content/includes/compose/oci-artifact.md diff --git a/content/includes/compose/oci-artifact.md b/content/includes/compose/oci-artifact.md deleted file mode 100644 index 03b6166e4dcc..000000000000 --- a/content/includes/compose/oci-artifact.md +++ /dev/null @@ -1 +0,0 @@ -Docker Compose supports working with [OCI artifacts](https://docs.docker.com/docker-hub/repos/manage/hub-images/oci-artifacts/), allowing you to package and distribute your Compose applications through container registries. This means you can store your Compose files alongside your container images, making it easier to version, share, and deploy your multi-container applications. \ No newline at end of file diff --git a/content/manuals/compose/how-tos/oci-artifact.md b/content/manuals/compose/how-tos/oci-artifact.md index f2822e7c7ae2..b9ee903aec94 100644 --- a/content/manuals/compose/how-tos/oci-artifact.md +++ b/content/manuals/compose/how-tos/oci-artifact.md @@ -1,101 +1,59 @@ --- title: Using Docker Compose with OCI artifacts -linkTitle: Use Compose OCI artifacts applications -weight: 20 -description: How to start and publish Compose applications as OCI artifacts -keywords: cli, compose, oci -aliases: -- /compose/oci-artifact/ +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 +params: + sidebar: + badge: + color: green + text: New --- -{{% include "compose/oci-artifact.md" %}} +{{< summary-bar feature_name="Compose OCI artifact" >}} -## Starting an OCI artifact application +Docker Compose supports working with [OCI artifacts](/manuals/docker-hub/repos/manage/hub-images/oci-artifacts.md), allowing you to package and distribute your Compose applications through container registries. This means you can store your Compose files alongside your container images, making it easier to version, share, and deploy your multi-container applications. -To start a Docker Compose application using an OCI artifact, you can use the `-f` (or `--file`) flag followed by the OCI artifact reference. -This allows you to specify a Compose file stored as an OCI artifact in a registry. -The `oci://` prefix indicates that the Compose file should be pulled from an OCI-compliant registry rather than loaded from the local filesystem. - -```bash -$ docker compose -f oci://docker.io/username/my-compose-app:latest up -``` - -To run the Compose application, use the `docker compose` command with the `-f` flag pointing to your OCI artifact: -```bash -$ docker compose -f oci://docker.io/username/my-compose-app:latest up -``` - -### Warnings/Messages displayed - -When you run an application from an OCI artifact, Compose may display warning messages requiring your confirmation to limit risks of running a malicious application: -* Listing the interpolation variables used along with their values -* Listing all environment variables used by the application -* Let you know if your OCI artifact application is using another remote resources (via [`include`](/reference/compose-file/include/) for example) - -```bash -$ REGISTRY=myregistry.com docker compose -f oci://docker.io/username/my-compose-app:latest up - -Found the following variables in configuration: -VARIABLE VALUE SOURCE REQUIRED DEFAULT -REGISTRY myregistry.com command-line yes -TAG v1.0 environment no latest -DOCKERFILE Dockerfile default no Dockerfile -API_KEY none no - -Do you want to proceed with these variables? [Y/n]:y - -Warning: This Compose project includes files from remote sources: -- oci://registry.example.com/stack:latest -Remote includes could potentially be malicious. Make sure you trust the source. -Do you want to continue? [y/N]: -``` - -If you agree to start the application, Compose will display the directory where all the resources from the OCI artifact have been downloaded. -```bash -... -Do you want to continue? [y/N]: y +## Publish your Compose application as an OCI artifact -Your compose stack "oci://registry.example.com/stack:latest" is stored in "~/Library/Caches/docker-compose/964e715660d6f6c3b384e05e7338613795f7dcd3613890cfa57e3540353b9d6d" -``` ---- - -## Publishing your Compose application as an OCI artifact - -To distribute your Compose application as an OCI artifact, you can **publish** it to an OCI-compliant registry. +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. -The publish function supports most of the composition capabilities of Compose, like overrides, extends or include, [with some limitations](#limitations-and-considerations) +The publish function supports most of the composition capabilities of Compose, like overrides, extends or include, [with some limitations](#limitations). -### Steps +### General steps -1. Navigate to Your Compose Application Directory +1. Navigate to your Compose application's directory. Ensure you're in the directory containing your `compose.yml` file or that you are specifying your Compose file with the `-f` flag. -2. Log in to Docker Hub - Before publishing, make sure you're authenticated with Docker Hub: +2. In your terminal, sign in to your Docker account so you're authenticated with Docker Hub. - ```bash + ```console $ docker login ``` -3. Publish the Compose application to Docker Hub - Use the `docker compose publish` command to push your application as an OCI artifact: +3. Use the `docker compose publish` command to push your application as an OCI artifact: - ```bash + ```console $ docker compose publish username/my-compose-app:latest ``` - or passing multiple Compose files - ```bash + If you have multiple Compose files, run: + + ```console $ docker compose -f compose-base.yml -f compose-production.yml publish username/my-compose-app:latest ``` -When publishing you can use options to specify the OCI version, whether to resolve image digests and if you want to include environment variables: -* `--oci-version`: Specify the OCI version (default is automatically determined). -* `--resolve-image-digests`: Pin image tags to digests. -* `--with-env`: Include environment variables in the published OCI artifact. -Compose checks for you if there isn't any sensitive data in your configuration and displays your environment variables to confirm you want to publish them. +### Advanced publishing options + +When publishing, you can pass additional options: +- `--oci-version`: Specify the OCI version (default is automatically determined). +- `--resolve-image-digests`: Pin image tags to digests. +- `--with-env`: Include environment variables in the published OCI artifact. -```bash +Compose checks to make sure there isn't any sensitive data in your configuration and displays your environment variables to confirm you want to publish them. + +```text ... you are about to publish sensitive data within your OCI artifact. please double check that you are not leaking sensitive data @@ -124,13 +82,62 @@ BAR=baz Are you ok to publish these environment variables? [y/N]: ``` -If you refuse the publish process will stop without sending anything to the registry. +If you decline, the publish process stops without sending anything to the registry. ---- +### Limitations -## Limitations and considerations +There is limitations to publishing Compose applications as OCI artifacts. You can't publish a Compose configuration with: +- With service(s) containing bind mounts +- With service(s) containing only a `build` section +- That that includes local files using the `include` attribute. To publish successfully, ensure that any included local files are also published. Alternatively, use remote file references, as remote `include` is supported. -There is limitations to publishing Compose applications as OCI artifacts: -* You can't publish Compose configuration with service(s) containing bind mounts -* You can't publish Compose configuration with service(s) containing only `build` section -* You can't publish Compose configuration using `include` of local files, publish them as well as remote `include` is supported +## Start an OCI artifact application + +To start a Docker Compose application that uses an OCI artifact, you can use the `-f` (or `--file`) flag followed by the OCI artifact reference. This allows you to specify a Compose file stored as an OCI artifact in a registry. + +The `oci://` prefix indicates that the Compose file should be pulled from an OCI-compliant registry rather than loaded from the local filesystem. + +```console +$ docker compose -f oci://docker.io/username/my-compose-app:latest up +``` + +To then run the Compose application, use the `docker compose up ` command with the `-f` flag pointing to your OCI artifact: + +```console +$ docker compose -f oci://docker.io/username/my-compose-app:latest up +``` + +### Troubleshooting + +When you run an application from an OCI artifact, Compose may display warning messages that require you to confirm the following so as to limit the risk of running a malicious application: + +- A list of the interpolation variables used along with their values +- A list of all environment variables used by the application +- If your OCI artifact application is using another remote resources, for example via [`include`](/reference/compose-file/include/). + +```text +$ REGISTRY=myregistry.com docker compose -f oci://docker.io/username/my-compose-app:latest up + +Found the following variables in configuration: +VARIABLE VALUE SOURCE REQUIRED DEFAULT +REGISTRY myregistry.com command-line yes +TAG v1.0 environment no latest +DOCKERFILE Dockerfile default no Dockerfile +API_KEY none no + +Do you want to proceed with these variables? [Y/n]:y + +Warning: This Compose project includes files from remote sources: +- oci://registry.example.com/stack:latest +Remote includes could potentially be malicious. Make sure you trust the source. +Do you want to continue? [y/N]: +``` + +If you agree to start the application, Compose displays the directory where all the resources from the OCI artifact have been downloaded: + +```text +... +Do you want to continue? [y/N]: y + +Your compose stack "oci://registry.example.com/stack:latest" is stored in "~/Library/Caches/docker-compose/964e715660d6f6c3b384e05e7338613795f7dcd3613890cfa57e3540353b9d6d" +``` diff --git a/data/summary.yaml b/data/summary.yaml index 5b928f39cb56..300c53985dc2 100644 --- a/data/summary.yaml +++ b/data/summary.yaml @@ -100,6 +100,8 @@ Compose mac address: requires: Docker Compose [2.23.2](/manuals/compose/releases/release-notes.md#2232) and later Compose menu: requires: Docker Compose [2.26.0](/manuals/compose/releases/release-notes.md#2260) and later +Compose OCI artifact: + requires: Docker Compose [2.34.0](/manuals/compose/releases/release-notes.md#2340) and later Compose replace file: requires: Docker Compose [2.24.4](/manuals/compose/releases/release-notes.md#2244) and later Compose required: From 863e0c1722110e65ff47ab5e1dc97bb9d5d3b679 Mon Sep 17 00:00:00 2001 From: aevesdocker Date: Mon, 17 Mar 2025 09:51:05 +0000 Subject: [PATCH 3/4] fix lint --- content/manuals/compose/how-tos/oci-artifact.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/manuals/compose/how-tos/oci-artifact.md b/content/manuals/compose/how-tos/oci-artifact.md index b9ee903aec94..56728a71e900 100644 --- a/content/manuals/compose/how-tos/oci-artifact.md +++ b/content/manuals/compose/how-tos/oci-artifact.md @@ -101,7 +101,7 @@ The `oci://` prefix indicates that the Compose file should be pulled from an OCI $ docker compose -f oci://docker.io/username/my-compose-app:latest up ``` -To then run the Compose application, use the `docker compose up ` command with the `-f` flag pointing to your OCI artifact: +To then run the Compose application, use the `docker compose up` command with the `-f` flag pointing to your OCI artifact: ```console $ docker compose -f oci://docker.io/username/my-compose-app:latest up From 361ba130e334a91b243afbade7c672c067223408 Mon Sep 17 00:00:00 2001 From: aevesdocker Date: Mon, 17 Mar 2025 10:13:22 +0000 Subject: [PATCH 4/4] sentence clarity --- content/manuals/compose/how-tos/oci-artifact.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/manuals/compose/how-tos/oci-artifact.md b/content/manuals/compose/how-tos/oci-artifact.md index 56728a71e900..33ce8042fc22 100644 --- a/content/manuals/compose/how-tos/oci-artifact.md +++ b/content/manuals/compose/how-tos/oci-artifact.md @@ -86,10 +86,10 @@ If you decline, the publish process stops without sending anything to the regist ### Limitations -There is limitations to publishing Compose applications as OCI artifacts. You can't publish a Compose configuration with: +There is 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 that includes local files using the `include` attribute. To publish successfully, ensure that any included local files are also published. Alternatively, use remote file references, 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 `include` to reference these files as remote `include` is supported. ## Start an OCI artifact application