publish Compose application as compose.yaml + images

[ndeloof]

What I did

Introduce option to publish a Compose application as compose.yaml artifact + references to images

In addition to the compose.yaml file(s) stored in OCI artifact, command creates an OCI index for all images used by the compose application. This index is linked to compose artifact using an OCI Subject

flowchart TD
    TAG --> A
    A[Compose OCI Artifact] -->|layer| B(compose.yaml)
    A -->|layer| C(image-digests.yaml)
    I[Index] -->|Subject| A
    I -->|Manifest| R1[image]
    I -->|Manifest| R2[image]

Loading

# Publish compose application
#
$ docker compose --progress=plain publish --app nicolasdeloof582/bidule:chose
...
 nicolasdeloof582/bidule:chose published 

# Search for referrers for published OCI artifact
#
$ regctl artifact list nicolasdeloof582/bidule:chose
Subject:                        docker.io/nicolasdeloof582/bidule@sha256:1eb94ed3a7261bef470b21af724e0b925df9986d4a4aa1db052c35c154361da4
                                
Referrers:                      
                                
  Name:                         docker.io/nicolasdeloof582/bidule@sha256:f335c03f80b2915a4d978e4e9ea315058ff170db7e457a97b851eceea8e83622
  Digest:                       sha256:f335c03f80b2915a4d978e4e9ea315058ff170db7e457a97b851eceea8e83622
  MediaType:                    application/vnd.oci.image.index.v1+json
  Annotations:                  
    com.docker.compose.version: 2.39.4

# Inspect the referrer manifest
#
$ regctl manifest get docker.io/nicolasdeloof582/bidule@sha256:f335c03f80b2915a4d978e4e9ea315058ff170db7e457a97b851eceea8e83622
time=2025-10-01T17:22:45.360+02:00 level=WARN msg="Changing login user for registry" orig=nicolasdeloof582 new=ndeloof host=docker.io
Name:                                            docker.io/nicolasdeloof582/bidule@sha256:f335c03f80b2915a4d978e4e9ea315058ff170db7e457a97b851eceea8e83622
MediaType:                                       application/vnd.oci.image.index.v1+json
Digest:                                          sha256:f335c03f80b2915a4d978e4e9ea315058ff170db7e457a97b851eceea8e83622
Annotations:                                     
  com.docker.compose.version:                    2.39.4
                                                 
Manifests:                                       
                                                 
  Name:                                          docker.io/nicolasdeloof582/bidule@sha256:4bcff63911fcb4448bd4fdacec207030997caf25e9bea4045fa6c8c44de311d1
  Digest:                                        sha256:4bcff63911fcb4448bd4fdacec207030997caf25e9bea4045fa6c8c44de311d1
  MediaType:                                     application/vnd.oci.image.index.v1+json
  Annotations:                                   
    containerd.io/distribution.source.docker.io: library/alpine

# 4bcff639.. is actually alpine/latest, mounted in compose artifact repository
#

Related issue
see #13238
see https://github.com/docker-archive-public/docker.app

(not mandatory) A picture of a cute animal, if possible in relation to what you did

[glours]

LGTM + tests ok 👌

[Silvanoc]

@ndeloof I have some comments on the design of the OCI artifact:

1. For the time being I would avoid the use of Subject as only mechanism to define the relationship. The API required to query which manifests refer the subject and therefore depend on its existence (the referrers API) is not supported yet by widely used container registries like those of GitHub and GitLab.
2. I personally would rather try to use so-called "nested indexes", because they are much better supported that Subject. Although I have to admit that I don't have a clear idea on how to structure it yet.
3. If using Subject, the inverse relationship should be used. The way you've defined it, you're forcing exiting container image indexes/manifests to be modified in order to add the Subject. It is the docker-compose document the one establishing the relationship and not the container images.

In general, the lifecycle of a manifest providing a Subject depends on the lifecycle of the referred manifests. But not the way around. And it is the compose that depends on the existence of the images and not the other way around. You can create and destroy compose configurations without needing any changes to the images.

[ndeloof]

My initial implementation was relying on publishing an image index, the OCI artifact being one of the entries and service images the many others. This is the approach we adopted for https://github.com/docker-archive-public/docker.app by the time
This comes with a few drawbacks:

• the OCI artifact is "hidden" as an entry in the index list, and as such we loose web UI integration on Docker Hub to give user guidance on how to use
• this requires the consuming code to be updated, which means older version of Compose would not be able to use compose application published by a recent release

Use of Subject made a balanced solution, with backward compatibility and benefits to get registry aware of OCI artifact relation with images. For sure, this require registry to support this, and some don't (yet) support this - but I guess they will mid-terms as this is the basis for secure supply chain (see https://learn.microsoft.com/en-us/azure/container-registry/container-registry-manage-artifact for illustration)

If using Subject, the inverse relationship should be used. The way you've defined it, you're forcing exiting container image indexes/manifests to be modified in order to add the Subject. It is the docker-compose document the one establishing the relationship and not the container images.

the artifact being published is an index list, will all services images. This group only exists because it is used by a Compose application. So the lifecycle of this manifest depends on the referred manifest: if compose application is updated, index list will probably be as well (until images aren't updated)

[Silvanoc]

I'm not convinced that this OCI artifact structure is the best one I can think of. I've created therefore #13354 to sketch my ideas.