How to: Build a Docker Container Registry backed by the Decentralized Cloud

November 2, 2020

Docker Registry is a stateless, highly scalable server-side application that stores and lets you distribute Docker images. The Registry is open-source, under the permissive Apache license.

Docker containers are a foundational building block of many companies' software infrastructure. 

A registry is a storage and content delivery system holding named Docker images, available in different tagged versions. Users interact with a registry by using Docker push and pull commands.

Storage itself is delegated to drivers. Today we’re excited to showcase the Docker Registry for Storj DCS, enabling anyone to host their Docker Registries on the Decentralized Cloud via the Storj DCS S3-compatible gateway.

Easily Pull/tag/push containers to the Decentralized Cloud

“Docker Registry’s native features are greatly improved by the globally distributed nature of Storj DCS, which breaks files up into small redundant pieces and streams them in parallel,” said Nick Stinemates, application containerization expert.

“Having a distributed registry minimizes global latency between the build and run environment and can improve the image transfer efficiency. Storj DCS distributes registry storage across the global edge, making it quick and efficient to spin-up a container process anywhere.”

We’re excited to showcase this new Storj DCS Connector for Docker Registry, making it easy and economical for developers to choose a distributed back-end storage layer for container images storage with Docker Registry.

Developing a Distributed Storage Plugin for Docker Registry

Running a Registry on Storj DCS is a great solution to integrate with and complement your CI/CD system. In a typical workflow, a commit to your source revision control system would trigger a build on your CI system, which would then push a new image to your Registry if the build is successful. A notification from the Registry would then trigger a deployment on a staging environment or notify other systems that a new image is available.

It’s also a game-changer if you want to quickly deploy a new image over a large cluster of machines spread across a diverse set of geographic locations.

Finally, it’s the best way to distribute images inside an isolated network.

Docker Registry plugs into reliable blob storage options, like S3, GCS, ECR, HDFS, or another registry, instead of managing data. The storage interface is simple, and new options are straightforward to add.

Quickstart Guide: Run your own Storj DCS Gateway-backed Registry

To get started running your own Storj DCS-backed Registry, you can follow these steps:

Storj S3 Gateway Driver configuration

1. Create and login to your free account on Storj DCS

2. Go to “Objects” and create your first S3 bucket:

3. On your Dashboard, create your access grants (if you did not create an access grant during the initial setup wizard): 

Storj Plesk blog 1

4. While creating your credentials, select “Generate S3 Gateway Credentials” in the last step:

Storj Plesk blog 2

To connect your Docker Registry to the Decentralized Cloud, you can run the following command:

# run the gateway setup command
docker run --interactive --tty --volume ${PWD}:/root/.storj storjlabs/gateway:latest setup --config-dir=/root/.storj

# launch the gateway
docker run --detach --volume ${PWD}:/root/.storj --publish 7777:7777 --name gateway storjlabs/gateway:latest run --config-dir=/root/.storj

# collect access key and secret from logs
docker logs gateway

# create a storj bucket for our backend
uplink --config-dir=${PWD} mb sj://registry-backend

# point the docker registry to the s3 gateway as a backend
docker run --detach --publish 5000:5000 -e "REGISTRY_STORAGE=s3" \
-e "REGISTRY_STORAGES_S3_BUCKET=registry-backend" \
--name docker-registry registry:2


This hooks up the S3 gateway with the docker registry specifically in the S3 REGIONENDPOINT.

Storj DCS offers more distributed, resilient, and economical storage for Docker Registry

Storj DCS is a distributed storage solution created by Storj Labs (led by Ben Golub, Docker’s former CEO). Data is encrypted on Storj DCS, broken into small overlapping pieces, and spread across tens of thousands of uncorrelated endpoints. This creates a much more distributed, performant, and resilient backend for Docker Registry container image storage and distribution.

Storj DCS represents an opportunity for Docker Registry developers to reduce their cloud storage and bandwidth bills by a significant amount. Storj DCS Storage is less than half the price of most AWS Availability Zones. It’s globally distributed, meaning there’s no need to replicate your container set across US-East, US-West, Europe, and Asia.

Finally, while just starting a decentralized registry is fairly easy, operating it in a production environment requires operational skills, just like any other service. You’re expected to be familiar with systems availability and scalability, logging and log processing, systems monitoring, and security 101. Strong understanding of Http and overall network communications, plus familiarity with golang, are certainly useful as well for advanced operations or hacking.

If you have any questions or comments around this integration, join our community and reach out – at

Share this blog post

Build on the
decentralized cloud.

Start for free