Docker Registry

In this page, you’ll learn everything you need to know about Docker Registries:

• Docker Registry
• What is a Docker Registry?
• DockerHub
• Other Public Registries
• Common Operations Using DockerHub
• Private Registries
• Common Operations for Managing an On-Premises Registry
• Summary

What is a Docker Registry?

A Docker registry is a storage and distribution system for named Docker images. The same image might have multiple different versions, identified by their tags.

A Docker registry is organized into Docker repositories , where a repository holds all the versions of a specific image. The registry allows Docker users to pull images locally, as well as push new images to the registry (given adequate access permissions when applicable).

By default, the Docker engine interacts with DockerHub , Docker’s public registry instance. However, it is possible to run on-premise the open-source Docker registry/distribution, as well as a commercially supported version called Docker Trusted Registry . There are other public registries available online.

To pull an image from an on-premises registry, you could run a command similar to:

docker pull my-registry:9000/foo/bar:2.1

where you pull the version of foo/bar image with tag 2.1 from our on-premise registry located at my-registry domain, port 9000 .

If you used DockerHub instead, and 2.1 was also the latest version, you could run this command to pull the same image locally:

docker pull foo/bar

For further reading, see Docker Documentation: About Registry › and Distribution ›

DockerHub

DockerHub is a hosted registry solution by Docker Inc. Besides public and private repositories, it also provides automated builds, organization accounts, and integration with source control solutions like Github and Bitbucket .

A public repository is accessible by anyone running Docker, and image names include the organization/user name. For example, docker pull jenkins/jenkins will pull the Jenkins CI server image with tag latest from the Jenkins organization. There are hundreds of thousands public images available. Private repositories restrict access to the repository creator or members of its organization.

DockerHub supports official repositories, which include images verified for security and best practices. These do not require an organization/user name, for example docker pull nginx will pull the latest image of the Nginx load balancer.

DockerHub can perform automated image builds if the DockerHub repository is linked to a source control repository which contains a build context (Dockerfile and all any files in the same folder). A commit in the source repository will trigger a build in DockerHub.

For further reading, see Docker Documentation: Configure automated Docker builds ›

DockerHub can also automatically scan images in private repositories for vulnerabilities, producing a report detailing vulnerabilities found in each image layer, by severity (critical, major or minor).

For further reading, see Docker Documentation: Docker Security Scanning ›

Note that multiple private repos, parallel builds and image security scanning are only available with paid subscriptions.

For further reading, see Docker Documentation: Overview of Docker Hub ›

Other Public Registries

Other companies host paid online Docker registries for public use. Cloud providers like AWS and Google, who also offer container-hosting services, market the high availability of their registries.

• Amazon Elastic Container Registry (ECR) integrates with AWS Identity and Access Management (IAM) service for authentication. It supports only private repositories and does not provide automated image building.
• Google Container Registry (GCR) authentication is based on Google’s Cloud Storage service permissions. It supports only private repositories and provides automated image builds via integration with Google Cloud Source Repositories, GitHub, and Bitbucket.
• Azure Container Registry (ACR) supports multi-region registries and authenticates with Active Directory. It supports only private repositories and does not provide automated image building.
• CoreOS Quay supports OAuth and LDAP authentication. It offers both (paid) private and (free) public repositories, automatic security scanning and automated image builds via integration with GitLab, GitHub, and Bitbucket.
• Private Docker Registry supports OAuth, LDAP and Active Directory authentication. It offers both private and public repositories, free up to 3 repositories (private or public).

Common Operations Using DockerHub

Common operations using DockerHub include:

• Login to DockerHub: Running docker login will ask for your DockerHub ID and password.
• Searching for an image in a public repository: Use the docker search command with a search term to find all images in public (including official) repositories that match that term.
• Pulling an existing image: Use docker pull and specify the image name. By default, the latest version is retrieved, but this behavior can be overridden by specifying a different image tag/version. For example, to pull the (older) version 14.04 of the Ubuntu image:

docker pull ubuntu:14.04

• Pushing a local image: You can push an image by running the docker push command. For example, to push the (latest) local version of my-image to my registry:

docker push my-username/my-image

• Create a new organization: This must be done from a browser . Go to DockerHub , click Organizations and then click Create Organization and fill in the required data.

• Creating a new repository: This must be done from a browser . Go to DockerHub , click the Create drop-down and select Create Repository. Fill in the required data. You will now be able to start pushing images to this repository.
• Create an automated build: This must be done from a browser . First, link your Github or Bitbucket account to DockerHub , by navigating to your profile settings, then click Linked Accounts & Services . Select Public and Private access (mandatory) and authorize.  Then, click the Create drop-down, select Create Automated Build and select which source repository you want to build images from. 

For further reading, see Docker Documentation: Overview of Docker Hub ›, Repositories on Docker Hub ›, and Configure automated builds on Docker Hub ›

Private Registries

Use cases for running a private registry on-premise (internal to the organization) include:

• Distributing images inside an isolated network (not sending images over the Internet)
• Creating faster CI/CD pipelines (pulling and pushing images from internal network), including faster deployments to on-premise environments
• Deploying a new image over a large cluster of machines
• Tightly controlling where images are being stored

Running a private registry system, especially when delivery to production depends on it, requires operational skills such as ensuring availability, logging and log processing, monitoring, and security. Strong understanding of http and overall network communications is also important.

Some vendors provide their own extensions of the open source Docker registry. These can help alleviate some of the above operational concerns:

• Docker Trusted Registry is Docker Inc’s commercially supported version, providing high availability via replication, image auditing, signing and security scanning, integration with LDAP and Active Directory.
• Harbor is a VMWare open source offering which also provides high availability via replication, image auditing, integration with LDAP and Active Directory.
• GitLab Container Registry is tightly integrated with GitLab CI’s workflow, with minimal setup.
• JFrog Artifactory for strong artifact management (not only Docker images but any artifact).

For further reading, see Docker Documentation: About Registry ›

Common Operations for Managing an On-Premises Registry

Common operations necessary to manage an on-premises registry installation include:

• Start registry: The registry is itself a Docker image that needs to be run as a container using docker run . For example, to run it based on the default configuration and forwarding requests on host port 5001 to container port 5000 (the default port the registry will listen to):

docker run -d -p 5001:5000 --name registry registry:2 

By default, registry data is persisted as a Docker volume. To specify a particular storage location on the host (for example, an SSD or SAN filesystem) use the bind mount option:

-v <host location>:<container location>

• Automatically restart registry: To keep the registry running when the host restarts or simply because the registry container stopped, simply add the option --restart=always to the command.
• Stop registry: Stopping the registry is simply a matter of stopping the running registry container with docker stop registry command. To actually remove the container also run:

docker rm -v registry

Note that the open source Docker registry comes with a set of default configurations for logging, storage, authentication, middleware, reporting, http, notifications, health checks and more. These can be overridden individually by passing in specific environment variables to the registry start command. For example, the following command tells the registry to listen for requests on the container’s port 5001 instead of default port 5000.

docker run -d -e REGISTRY_HTTP_ADDR=0.0.0.0:5001 -p 5001:5001 \
--name registry registry:2

The other option is to completely override the configuration settings with a YAML file . Also it needs to be mounted as a volume on the container, for example:

docker run -d -p 5001:5000 -v config.yml:/etc/docker/registry/config.yml \
--name registry registry:2

For further reading, see Docker Documentation: Deploy a registry server › and Configuring a registry ›

Summary

A Docker registry is a system for versioning, storing and distributing Docker images. DockerHub is a hosted registry used by default when installing the Docker engine, but there are other hosted registries available for public use such as AWS and Google’s own registries.

It is also possible to host a registry on-premise for isolation and/or tighter integration with CI/CD workflows. Extensions to the open source Docker registry such as Docker’s own Trusted Registry or VMWare’s Harbor can help alleviate some of the operational burden of running a registry on-premise.

Image repositories inside a registry can be public (anyone can download them) or private (restricted access to the user or organization owning them).

The following tutorials teach you more about Docker registries:

Docker Security Scanning

Tutorial by: Docker

Length: Short

Can help you learn: How to scan images in private repositories to verify that they are free from known security vulnerabilities or exposures, and report the results of the scan for each image tag.

Tutorial steps:

• Opt in to Docker security scanning.
• View Docker security scanning results.
• The Docker security scan process.
• Frequently asked questions.

The following videos can help you learn more about Docker registries: