Using Docker Compose with OCI artifacts

Table of contents
Requires: Docker Compose 2.34.0 and later

Docker Compose supports working with 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.

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.

The publish function supports most of the composition capabilities of Compose, like overrides, extends or include, with some limitations.

General steps

  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. In your terminal, sign in to your Docker account so you're authenticated with Docker Hub.

    $ docker login

  3. Use the docker compose publish command to push your application as an OCI artifact:

    $ docker compose publish username/my-compose-app:latest

    If you have multiple Compose files, run:

    $ docker compose -f compose-base.yml -f compose-production.yml publish username/my-compose-app:latest

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.

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.

...
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 decline, the publish process stops without sending anything to the registry.

Limitations

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

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.

$ 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:

$ 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.
$ 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      <unset>             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:

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