Static hosting for local OCI format

[smil2k]

Hosting docker containers is not easy. The protocol requires lot of specialized headers and authentication techniques. I was wondering whether it would be possible to make it more simpler and more HTTP standard compliant. My ultimate goal would be to be able to support hosting containers on plain static web servers.

My idea is the following:
What is we would use the OCI local directory layout -which is already standardized-, and put that (maybe with some minor changes) to a static HTTP server?
Authorization for static web servers are standardized: (basic auth, oauth2 etc... ).

Eg. static.bla.org
/oci-layout (optional)
/index.json (optional)
/blobs (optional)
/library/postgres:
+ oci-layout
+ index.json
+ blobs

podman pull https+oci://static.bla.org/library/postgres:17

• Would first check "oci-layout" file
• then downloads the index.json and locate the image and downloads it.

podman search https+oci://static.bla.org/library/postgres
Would do the same and just parse the json.

It might make sense to allow sharing blobs in the root between all images (like os layers etc...).

What do you think about this?

[sudo-bmitch]

Personally, my preference is for tools to natively support the OCI Layout, allowing images to be deployed directly from that without any http or registry server. Until then, as a shameless self promotion, there's olareg that serves content from an OCI Layout with a minimal Go based server implementing the APIs that clients expect.

[smil2k]

I see your point, but somehow we need to get that oci-layout to the machine, right? I'm thinking kubernetes, google run etc...

[sudo-bmitch]

If you have to run a server, then I think a registry has some advantages over running a static web server, and even more for the push workflows. There's a lot of room to make the spec follow the upstream HTTP specs more closely, but much of that is already baked into clients where a change would require a major version bump and be incompatible with existing clients.

[smil2k]

My idea would be to use any static server, for example a storage blob. So it would not require any specialized server. I don't think that existing protocol should be modified at all. It is what it is, it could stay as such. My proposal would be to standardize an "protocol" like https+oci:// for network serving oci-layout based repositories on a static file server.

How this container ends up on the static server? That can be left blank at the moment.

[tianon]

In reading this, my first thought was that most of this should just work, so I set up some static content at https://tmp.tianon.xyz/v2/ with a latest tag under a test repository (ie, https://tmp.tianon.xyz/v2/test/manifests/latest returns manifest content). This is all running on a pretty stock NGINX configuration that I don't have any plans to change to support this better, and the content itself is small enough that I plan to keep this hosted here for now.

My testing with clients is that crane doesn't care at all and works just fine, but both Docker and containerd are more particular about the headers -- there was some debate on today's call as to whether they need to be so particular about the server, even though we probably still want to consider servers that don't supply the appropriate headers as "non-conformant" to the spec:

$ crane digest tmp.tianon.xyz/test:latest
2025/10/30 10:52:17 HEAD request failed, falling back on GET: HEAD https://tmp.tianon.xyz/v2/test/manifests/latest: response did not include Docker-Content-Digest header
sha256:54601ace1bfa6c5f1fade4c284f730491c8b3072dbe40ec56e7df7d65dde589b
$ crane manifest tmp.tianon.xyz/test:latest
{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.index.v1+json",
  "manifests": [
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:9ef42f1d602fb423fad935aac1caa0cfdbce1ad7edce64d080a4eb7b13f7cd9d",
      "size": 1165,
      "platform": {
        "os": "linux",
        "architecture": "amd64"
      },
      "annotations": {
        "com.docker.official-images.bashbrew.arch": "amd64",
        "org.opencontainers.image.base.name": "scratch",
        "org.opencontainers.image.created": "2025-04-25T23:09:46Z",
        "org.opencontainers.image.revision": "fd07cf2c5b1aa4a00d10701124615cee90956ce0",
        "org.opencontainers.image.source": "https://github.com/tianon/dockerfiles.git",
        "org.opencontainers.image.url": "https://hub.docker.com/r/tianon/true",
        "org.opencontainers.image.version": "oci"
      }
    }
  ]
}

$ docker pull tmp.tianon.xyz/test:latest
Error response from daemon: missing signature key

$ sudo ctr content fetch tmp.tianon.xyz/test:latest
WARN[0000] reference for unknown type: application/octet-stream  digest="sha256:54601ace1bfa6c5f1fade4c284f730491c8b3072dbe40ec56e7df7d65dde589b" mediatype=application/octet-stream size=901
ctr: failed to copy: httpReadSeeker: failed open: could not fetch content descriptor sha256:54601ace1bfa6c5f1fade4c284f730491c8b3072dbe40ec56e7df7d65dde589b (application/octet-stream) from remote: not found

[tianon]

I added the tag listing file so that oci.dag.dev can work nicely too:

https://oci.dag.dev/?repo=tmp.tianon.xyz/test

[sudo-bmitch]

Looking over the spec, it does say the Content-Type SHOULD be validated:

The Content-Type header SHOULD match what the client pushed as the manifest's Content-Type. If the manifest has a mediaType field, clients SHOULD reject unless the mediaType field's value matches the type specified by the Content-Type header.

I think there's something to be said for clients verifying the header and data match for security and forward compatibility. The request Accept and response Content-Type headers are one of OCIs ways to add functionality to existing APIs avoiding major version bumps. And without that, I worry we're on the path to requiring clients to accept an HTTP 200 containing an {"error": "request failed"} body.

[smil2k]

@tianon I ran some tests against your server.

skopeo

$ skopeo list-tags docker://tmp.tianon.xyz/test
{
    "Repository": "tmp.tianon.xyz/test",
    "Tags": [
        "latest"
    ]
}

$ skopeo inspect docker://tmp.tianon.xyz/test
FATA[0000] Error parsing manifest for image: unsupported schema version 2

ORAS

$ oras pull tmp.tianon.xyz/test:latest --debug
DEBU[0000] Request #0
> Request URL: "https://tmp.tianon.xyz/v2/test/manifests/latest"
> Request method: "GET"
> Request headers:
   "Accept": "application/vnd.docker.distribution.manifest.v2+json, application/vnd.docker.distribution.manifest.list.v2+json, application/vnd.oci.image.manifest.v1+json, application/vnd.oci.image.index.v1+json, application/vnd.oci.artifact.manifest.v1+json"
   "User-Agent": "oras/1.2.0+Homebrew"
DEBU[0000] Response #0
< Response Status: "200 OK"
< Response headers:
   "Nel": "{\"report_to\":\"cf-nel\",\"success_fraction\":0.0,\"max_age\":604800}"
   "Accept-Ranges": "bytes"
   "Vary": "accept-encoding"
   "Alt-Svc": "h3=\":443\"; ma=86400"
   "Server": "cloudflare"
   "Cache-Control": "no-store, max-age=0"
   "Cf-Cache-Status": "BYPASS"
   "Etag": "\"6903a2d9-385\""
   "Last-Modified": "Thu, 30 Oct 2025 17:39:37 GMT"
   "Cf-Ray": "999d1c466973c2a0-VIE"
   "Content-Type": "application/octet-stream"
   "Content-Length": "901"
   "Report-To": "{\"group\":\"cf-nel\",\"max_age\":604800,\"endpoints\":[{\"url\":\"https://a.nel.cloudflare.com/report/v4?s=d5xK68mBinWimtFq%2Fqm8pxlR07pBpcvkCJeZlW3QeI4Ln4biUjG9ourXy9PRB3ATW97F2SHrvWO9BQ5X%2BdwZfsUSa16BeviyypYqAw%3D%3D\"}]}"
   "Date": "Wed, 05 Nov 2025 14:41:10 GMT"
DEBU[0000] Request #1
> Request URL: "https://tmp.tianon.xyz/v2/test/blobs/sha256:54601ace1bfa6c5f1fade4c284f730491c8b3072dbe40ec56e7df7d65dde589b"
> Request method: "GET"
> Request headers:
   "User-Agent": "oras/1.2.0+Homebrew"
DEBU[0000] Response #1
< Response Status: "404 Not Found"
< Response headers:
   "Date": "Wed, 05 Nov 2025 14:41:10 GMT"
   "Content-Type": "text/html"
   "Server": "cloudflare"
   "Age": "4"
   "Cf-Cache-Status": "HIT"
   "Nel": "{\"report_to\":\"cf-nel\",\"success_fraction\":0.0,\"max_age\":604800}"
   "Cache-Control": "max-age=14400"
   "Vary": "accept-encoding"
   "Report-To": "{\"group\":\"cf-nel\",\"max_age\":604800,\"endpoints\":[{\"url\":\"https://a.nel.cloudflare.com/report/v4?s=nUEDfGBLW1aTtUcgK9x3MOlncfvemnKe0ipudF%2By5rOjV3djDCPQXHAK65CrapiEJFpwSpoAO0WtfyaERLagdiQ109VzcYfTwU%2FtZw%3D%3D\"}]}"
   "Cf-Ray": "999d1c47cb1fc2a0-VIE"
   "Alt-Svc": "h3=\":443\"; ma=86400"
Error response from registry: sha256:54601ace1bfa6c5f1fade4c284f730491c8b3072dbe40ec56e7df7d65dde589b: not found