DigitalOcean’s Container Registry gives you a private space in the cloud to store and distribute your Docker images. As well as offering an image repository, the service also integrates into DigitalOcean’s other services. You can deploy stored images to App Platform and use them with your Managed Kubernetes clusters.

Benefits and Features

Container Registry is a Docker Hub competitor which lets you keep your Docker images within your DigitalOcean account. It’s ideal when you’ll be accessing those images with other DigitalOcean features. You don’t need to set up a separate paid Docker Hub account for your app’s private images.

Data held in the Container Registry is automatically load balanced across multiple DigitalOcean datacentre regions. This accelerates image retrieval when you’re starting containers and pulling them to your machine. Unlike other DigitalOcean features, you can’t manually select the datacentre of a Container Registry.

DigitalOcean’s registry implementation is OCI-compliant so you can interact with it using familiar ecosystem tools. Commands like docker push and docker pull will “just work” once you’ve added your registry’s credentials to your CLI. Similarly, orchestrators such as Kubernetes will have no trouble referencing images in your registry.

Creating a Registry

Container Registry is available for free but the gratis plan does come with some severe limitations. You get one image repository (top-level image name), 500MB of storage, and a 500MB outbound data transfer cap – adequate for evaluating the service but probably not suitable for long-term use. The $5/mo Basic plan gives you five repositories and 5GB while the $20/Professional version comes with unlimited repositories and 100GB storage. Storage overages are billed at $0.02/GB.

Create a registry by logging into the DigitalOcean control panel and clicking the “Container Registry” link in the left sidebar. Give your new registry a name and select your storage plan. The name has to be globally unique across every DigitalOcean registry so your first choice might not be available. It needs to consist of up to 63 characters including letters, numbers, and hyphens.

It can take a few seconds to create a new registry. You’ll be taken to your registry’s dashboard screen once the process is complete.

Connecting Your Docker CLI

Your next step is to connect your Docker CLI to the registry. You need to supply Docker with your registry credentials so it can push and pull images using your account. There are three different ways of achieving this.

Using Doctl

DigitalOcean’s official command-line utility, Doctl, includes a convenience script that configures your Docker client to work with your Container Registry.

You’ll need to have Doctl installed and authenticated to your DigitalOcean account to use this method. Run the following command to set up the integration:

doctl registry login

Using a DigitalOcean API Token

DigitalOcean API tokens can be used to authenticate to Container Registries. Generate a token by clicking the “API” link at the bottom of the left sidebar in your DigitalOcean account. Click “Generate New Token”, give it a name, and press “Generate Token” in the following popup.

The token value will be displayed. Make a note of this as you won’t be able to retrieve it later. Now return to your CLI and use the docker login command to connect to your registry:

docker login registry.digitalocean.com

You’ll be prompted to supply a username and password. Use the value of your generated API token for both fields. Docker will now be able to interact with DigitalOcean registries that belong to your account.

Downloading a Docker Credentials File

If you don’t want to generate an API key or use Doctl, head to your Container Registry dashboard page and click the blue “Actions” button in the top-right. Select “Download Docker Credentials” from the menu.

This file is a Docker-compatible config.json that includes the credentials for your registry. You could either merge it with your main ~/.docker/config.json file or use the --config flag with docker commands:

docker --config ~/downloaded-config.json pull registry.digitalocean.com/<your-registry-name>/example-image:latest

Using Docker to Push and Pull Images

With Docker correctly configured, you can now use the CLI to push and pull images with your Container Registry. Images must be tagged in the following format:

registry.digitalocean.com/<your-registry-name>/example-image:latest

Here’s a simple example of pushing a copy of an existing image to your registry:

docker pull httpd:latest
docker tag httpd:latest registry.digitalocean.com/<your-registry-name>/httpd:latest
docker push registry.digitalocean.com/<your-registry-name>/httpd:latest

Head to your registry’s dashboard in the DigitalOcean control panel. Your newly pushed image should show up within your registry. You can click the image to see the available tags. Delete a specific tag, or all the tags available for an image, by clicking the three dots icon on the far-right and selecting from the menu.

Garbage Collection

Deleting images from the registry might leave behind redundant layers that are no longer used by any remaining manifests. These layers will still count towards your storage cost.

DigitalOcean provides a garbage collection facility to remove orphaned layers and manifests. You’ll see a tile on your registry’s dashboard screen when garbage collection could free up storage space. Click “Empty garbage” to begin the process.

You’ll see a popup dialog that lets you choose whether to remove untagged manifests as part of the clean-up. These are valid images which have no tag assigned so they can only be referenced by their full ID, such as registry.digitalocean.com/<your-registry-name>/example-image:a1bc23. Deleting these manifests is usually desirable unless you’re intentionally retaining them.

Garbage Collection puts your registry into a read-only state until all the unused layers have been deleted. New pushes will be rejected for the duration of the clean-up. Collection doesn’t begin until existing writes have finished so there may be a slight delay after you initiate the process. Progress is displayed on your registry’s dashboard page in the control panel.

DigitalOcean doesn’t offer automatic garbage collection. However it is possible to run the process using Doctl and the DigitalOcean API so you could write your own script and schedule it with cron.

Conclusion

DigitalOcean’s Container Registry gives you a convenient way to store Docker images. You authenticate to the registry using an existing DigitalOcean API token. You should keep in mind that API tokens give total access to your account – they’re not confined to registry access.

Whether you should use Container Registry in favor of Docker Hub comes down to what you’ll be doing with the images. If you’ll be deploying them to DigitalOcean, it makes sense to put your images alongside your infrastructure, maximizing performance. Docker Hub has benefits in other areas though, such as automatic image rebuilds and vulnerability scans that can quickly flag security issues. DigitalOcean’s service has neither of these, instead focusing on pure and simple image storage.