Docker OCI Repositories

Docker/OCI Repositories

The Docker/OCI repository support is still experimental but should work well enough for most use cases.

Setup

Since the OCI spec doesn't support registries hosted under a sub-path, you unfortunately need to set up a reverse proxy in front of your OCI repositories. All requests to your proxy will need to be forwarded to the path /repositories/oci/{repository-name}/{uri} where {repository-name} is a placeholder for the name of your OCI repository. An example configuration for caddy and a repository named "docker" could look like this:

:8081 {
    rewrite * /repositories/oci/docker{uri}
    reverse_proxy http://localhost:8080
}

With this setup caddy will forward all requests received on http://localhost:8081 to http://localhost:8080/repositories/oci/docker/.... Of course you are free to use any proxy you like. The only requirement is that your proxy needs to add the X-Forwarded-Host and X-Forwarded-Proto headers, otherwise the client will not be able to authenticate itself.

Kubernetes Gateway routing

The repository supports creating, updating and deleting HTTPRoute resources for the Gateway API should you be using it. To do this, the repository pod will need the permissions to create, delete, list, get & patch HTTPRoute resources in the namespace it's running in. If your pod has these permissions and has successfully connected to the kubernetes API server, you should see a new "Kubernetes Gateway Routing" option in the "External Access" section of the OCI repository configuration.

After enabling this option, you need to enter the name and port of the service that provides access to the repository (this is where the created HTTPRoute will route its traffic) and then you enter the name & namespace of your gateway.

Note

Hostnames with port numbers are not supported. Should your "External Host" value contain a port, an error will likely occur.

Authentication

Authentication is only required when performing actions not permitted to anonymous users. By default, anonymous users have read access unless configured otherwise in the repository. To authenticate, you need to generate an access-token in the settings and run the following command or its equivalent for your OCI client:

docker login <your-repo-host>

Then the client should prompt you for your username. This is the same username you use to log into the web interface. After that you are prompted for a password, use your access-token here. And that's it. Now you should be able to do anything your user is permitted to do.