Docker Hub is the best known registry for distributing and sharing container images. Docker Hub and other OCI-compliant registries can now do more than just container images, though. The ORAS (OCI Registry As Storage) project transforms registries into generic artifact stores, capable of publishing any asset relevant to your application.

In this article, you’ll learn what ORAS is, the challenges it solves, and how to get started using it with Docker Hub.

Docker Hub vs OCI Registries

First, let’s get one detail clear: the container ecosystem is more than just Docker. The tools and processes which Docker pioneered have been standardized by the OCI. Docker is now one implementation of the OCI specifications, alongside other compatible container systems such as Podman and Kubernetes.

Docker Hub is an OCI Registry-compatible platform for delivering container images. OCI container tools can consume content from Docker Hub and other registries via commands like docker pull and docker push. While these have previously only worked with container images, now you can use the same mechanism to distribute your app’s other components.

Why Generic Artifacts Matter

This functionality is being developed under the ORAS banner. It remodels registries as “generic artifact stores” which you can interact with using the familiar push/pull workflow.

An artifact is anything that a user might need to successfully run your software. This could be a container image, or another type of asset that makes sense for your project:

• Helm charts
• Precompiled binaries and installer packages
• SBOMs
• Recommended security policy configurations, such as OPA rules
• Release signatures, certificates, and metadata

These vital assets can often be hard for users to find. They tend to be scattered across different source control platforms, package managers, and direct website downloads. With ORAS, you can deposit everything into one centralized registry, then let users retrieve content using a single set of tools and credentials. Viewing the SBOM for your v1.1.0 release is as simple as oras pull example.com/my-app/sbom:v1.1.0, for example.

Is ORAS a Breaking Change for Container Images?

ORAS doesn’t break any existing container registry features. You can keep running commands such as docker push my-image:latest to move your images around.

There are significant changes to content storage behind the scenes, however. ORAS removes the historical assumption that all registry content is an image. To support artifacts, registries have to track the type of each upload that’s completed. Different kinds of artifact are termed “media types” within ORAS.

Popular community projects can register their own media types to identify commonly used artifact classifications, such as Helm charts. This allows registry providers to display relevant information about the artifacts you’ve stored.

The container image media type is automatically used when you push from existing tools such as docker push. A default “unknown” type is applied when you upload directly from the ORAS CLI, unless you specify a registered type.

Installing the ORAS CLI

You need the ORAS CLI to push and pull artifacts with arbitrary types. You can download the latest version from the project’s GitHub releases page. Only macOS and Linux systems are currently supported.

Extract the downloaded archive, then copy the oras binary to a location that’s in your path:

$ tar -zxf oras_0.16.0_*.tar.gz -C oras-install/
$ mv oras-install/oras /usr/local/bin/
$ rm -rf oras_0.16.0_*.tar.gz oras-install/

Check your binary’s working by running the oras version command:

$ oras version
0.16.0

Now you’re ready to start using ORAS.

Using ORAS With Docker Hub

ORAS is only compatible with registries that have implemented support for the OCI Artifacts specification. This list now features most major vendors, including Amazon ECR, Azure, Google, and GitHub, as well as self-hosted instances deployed using the CNCF distribution.

We’ll use Docker Hub for this article as it’s the most popular registry solution. It added full support for OCI Artifacts in November 2022.

Login to Your Registry

ORAS automatically reuses registry credentials you’ve previously added to your ~/.docker/config.json file. If you need to login to Docker Hub, you can run either docker login or oras login to do so:

$ oras login -u username -p password_or_personal_access_token

$ docker login -u username -p password_or_personal_access_token

Next create a simple file to upload to the registry. Remember there’s no restrictions on the kind of asset you push. This example is a contrived JSON file that describes the project’s status, but you can upload anything that’ll be useful to your users or developers.

$ echo '{"app": "oras-demo", "version": "1.1.0"}' > artifact.json

Now you’re ready to push your file with the ORAS CLI.

Push Your Artifact

Run the following command to push your artifact, after replacing <username> with your actual Docker Hub username:

$ oras push docker.io/<username>/oras-demo:1.1.0 \
    artifact.json:application/json \
    --artifact-type application/vnd.unknown.config.v1+json
Uploading 7ac68d8d2a12 artifact.json
Uploaded  7ac68d8d2a12 artifact.json
Pushed docker.io/ilmiont/oras-demo:1.1.0
Digest: sha256:41abfed0ab43a24933c5eafe3c363418264a59eee527821a39fe7c0abf25570b

There are a few noteworthy details in this command:

• The first argument defines the registry to push to and the tag to assign to the artifact. This is similar to pushing a container image tag.
• Unlike the docker CLI, ORAS requires you to specify the registry URL (docker.io for Docker Hub). ORAS is a generic tool that can’t make assumptions about what or where you’re pushing.
• The second argument specifies the path to the file you’re uploading in filename:content-type format. As the example file is JSON, the application/json content type is selected.
• The third argument specifies the ORAS artifact type (media type) to assign to your artifact. You should use a standard media type if you’re uploading a registered kind of artifact, like a Helm chart, but the “unknown” default is appropriate for this demo.

The upload progress is shown in your terminal, similarly to a regular docker push. Try running the oras repo tags command to confirm the push completed:

$ oras repo tags docker.io/<username>/oras-demo
1.1.0

Managing Artifacts In Docker Hub’s UI

Your artifact will also appear on the Docker Hub website. In the Repositories list, you’ll see Contains: Other to denote that the repository holds a generic artifact. Container image repositories are labelled as Contains: Image.

Select the repository to view its details, add a description, and see all the available tags. It’s similar to working with container images.

Pulling Your Artifact

With your artifact available in the registry, you can now switch to another machine and repeat the steps to install the ORAS CLI and login to your Docker Hub account. Once you’ve authenticated, use the oras pull command to retrieve your artifact:

$ oras pull docker.io/<username>/oras-demo:1.1.0
Downloading 7ac68d8d2a12 artifact.json
Downloaded  7ac68d8d2a12 artifact.json
Pulled docker.io/ilmiont/oras-demo:1.1.0
Digest: sha256:41abfed0ab43a24933c5eafe3c363418264a59eee527821a39fe7c0abf25570b

The files in the artifact will be deposited into your working directory:

$ ls
artifact.json

$ cat artifact.json
{"app": "demo-oras", "version": "1.1.0"}

You’ve successfully used ORAS to distribute your application’s artifacts, using the existing infrastructure available from your container registry provider.

Summary

ORAS transforms container image registries into generic distribution platforms. You can push any artifact relevant to your application and users can retrieve it using one consistent mechanism. This avoids having to maintain, publish to, and switch between multiple delivery channels.

ORAS support is being added to popular ecosystem tools too. Helm lets you directly push charts to an ORAS registry using its helm push command, for example. This avoids having to manually export the chart so you can push it with oras push. It also handles setting the correct ORAS media type for you. You can expect more tools to start integrating ORAS, allowing you to push all kinds of content straight to your centralized registry.