Skip to content

Commit b45d765

Browse files
aevesdockerglours
aevesdocker
and
glours
authored
publish updates from main (#22261)
Automated pull request for publishing docs updates. Co-authored-by: Guillaume Lours <[email protected]>
2 parents 1454432 + 763a789 commit b45d765

File tree

2 files changed

+145
-0
lines changed

2 files changed

+145
-0
lines changed

‎content/manuals/compose/how-tos/oci-artifact.md

+143
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
---
2+
title: Using Docker Compose with OCI artifacts
3+
linkTitle: OCI artifact applications
4+
weight: 110
5+
description: How to publish and start Compose applications as OCI artifacts
6+
keywords: cli, compose, oci, docker hub, artificats, publish, package, distribute
7+
params:
8+
sidebar:
9+
badge:
10+
color: green
11+
text: New
12+
---
13+
14+
{{< summary-bar feature_name="Compose OCI artifact" >}}
15+
16+
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.
17+
18+
## Publish your Compose application as an OCI artifact
19+
20+
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.
21+
This allows others to deploy your application directly from the registry.
22+
23+
The publish function supports most of the composition capabilities of Compose, like overrides, extends or include, [with some limitations](#limitations).
24+
25+
### General steps
26+
27+
1. Navigate to your Compose application's directory.
28+
Ensure you're in the directory containing your `compose.yml` file or that you are specifying your Compose file with the `-f` flag.
29+
30+
2. In your terminal, sign in to your Docker account so you're authenticated with Docker Hub.
31+
32+
```console
33+
$ docker login
34+
```
35+
36+
3. Use the `docker compose publish` command to push your application as an OCI artifact:
37+
38+
```console
39+
$ docker compose publish username/my-compose-app:latest
40+
```
41+
If you have multiple Compose files, run:
42+
43+
```console
44+
$ docker compose -f compose-base.yml -f compose-production.yml publish username/my-compose-app:latest
45+
```
46+
47+
### Advanced publishing options
48+
49+
When publishing, you can pass additional options:
50+
- `--oci-version`: Specify the OCI version (default is automatically determined).
51+
- `--resolve-image-digests`: Pin image tags to digests.
52+
- `--with-env`: Include environment variables in the published OCI artifact.
53+
54+
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.
55+
56+
```text
57+
...
58+
you are about to publish sensitive data within your OCI artifact.
59+
please double check that you are not leaking sensitive data
60+
AWS Client ID
61+
"services.serviceA.environment.AWS_ACCESS_KEY_ID": xxxxxxxxxx
62+
AWS Secret Key
63+
"services.serviceA.environment.AWS_SECRET_ACCESS_KEY": aws"xxxx/xxxx+xxxx+"
64+
Github authentication
65+
"GITHUB_TOKEN": ghp_xxxxxxxxxx
66+
JSON Web Token
67+
"": xxxxxxx.xxxxxxxx.xxxxxxxx
68+
Private Key
69+
"": -----BEGIN DSA PRIVATE KEY-----
70+
xxxxx
71+
-----END DSA PRIVATE KEY-----
72+
Are you ok to publish these sensitive data? [y/N]:y
73+
74+
you are about to publish environment variables within your OCI artifact.
75+
please double check that you are not leaking sensitive data
76+
Service/Config serviceA
77+
FOO=bar
78+
Service/Config serviceB
79+
FOO=bar
80+
QUIX=
81+
BAR=baz
82+
Are you ok to publish these environment variables? [y/N]:
83+
```
84+
85+
If you decline, the publish process stops without sending anything to the registry.
86+
87+
### Limitations
88+
89+
There is limitations to publishing Compose applications as OCI artifacts. You can't publish a Compose configuration:
90+
- With service(s) containing bind mounts
91+
- With service(s) containing only a `build` section
92+
- 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.
93+
94+
## Start an OCI artifact application
95+
96+
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.
97+
98+
The `oci://` prefix indicates that the Compose file should be pulled from an OCI-compliant registry rather than loaded from the local filesystem.
99+
100+
```console
101+
$ docker compose -f oci://docker.io/username/my-compose-app:latest up
102+
```
103+
104+
To then run the Compose application, use the `docker compose up` command with the `-f` flag pointing to your OCI artifact:
105+
106+
```console
107+
$ docker compose -f oci://docker.io/username/my-compose-app:latest up
108+
```
109+
110+
### Troubleshooting
111+
112+
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:
113+
114+
- A list of the interpolation variables used along with their values
115+
- A list of all environment variables used by the application
116+
- If your OCI artifact application is using another remote resources, for example via [`include`](/reference/compose-file/include/).
117+
118+
```text
119+
$ REGISTRY=myregistry.com docker compose -f oci://docker.io/username/my-compose-app:latest up
120+
121+
Found the following variables in configuration:
122+
VARIABLE VALUE SOURCE REQUIRED DEFAULT
123+
REGISTRY myregistry.com command-line yes
124+
TAG v1.0 environment no latest
125+
DOCKERFILE Dockerfile default no Dockerfile
126+
API_KEY <unset> none no
127+
128+
Do you want to proceed with these variables? [Y/n]:y
129+
130+
Warning: This Compose project includes files from remote sources:
131+
- oci://registry.example.com/stack:latest
132+
Remote includes could potentially be malicious. Make sure you trust the source.
133+
Do you want to continue? [y/N]:
134+
```
135+
136+
If you agree to start the application, Compose displays the directory where all the resources from the OCI artifact have been downloaded:
137+
138+
```text
139+
...
140+
Do you want to continue? [y/N]: y
141+
142+
Your compose stack "oci://registry.example.com/stack:latest" is stored in "~/Library/Caches/docker-compose/964e715660d6f6c3b384e05e7338613795f7dcd3613890cfa57e3540353b9d6d"
143+
```

‎data/summary.yaml

+2
Original file line numberDiff line numberDiff line change
@@ -100,6 +100,8 @@ Compose mac address:
100100
requires: Docker Compose [2.23.2](/manuals/compose/releases/release-notes.md#2232) and later
101101
Compose menu:
102102
requires: Docker Compose [2.26.0](/manuals/compose/releases/release-notes.md#2260) and later
103+
Compose OCI artifact:
104+
requires: Docker Compose [2.34.0](/manuals/compose/releases/release-notes.md#2340) and later
103105
Compose replace file:
104106
requires: Docker Compose [2.24.4](/manuals/compose/releases/release-notes.md#2244) and later
105107
Compose required:

0 commit comments

Comments
 (0)