Docker Registries 101
Learn about Docker Registries,DockerHub, other public registries, and private registries
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:
where you pull the version of
foo/bar image with tag
from our on-premise registry located at
If you used DockerHub instead, and 2.1 was also the latest version, you could run this command to pull the same image locally:
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
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
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.
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 loginwill ask for your DockerHub ID and password.
Searching for an image in a public repository: Use the
docker searchcommand with a search term to find all images in public (including official) repositories that match that term.
- Pulling an existing image: Use
docker pulland 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:
- Pushing a local image: You can push an image by running the
docker pushcommand. For example, to push the (latest) local version of my-image to my registry:
- 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.
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).
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):
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:
Automatically restart registry: To keep the registry running when the host restarts or simply because the registry container stopped, simply add the option
--restart=alwaysto the command.
Stop registry: Stopping the registry is simply a matter of stopping the running registry container with
docker stop registrycommand. To actually remove the container also run:
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.
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:
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).
Tutorial by: Christopher Negus
Can help you learn: How to create a private Docker registry in Fedora or Ubuntu, use the docker-registry package, use the registry container image, and understand the Docker image namespace
- Getting and starting a private Docker registry.
- Setting up a Docker registry in Fedora.
- Setting up a Docker registry in Ubuntu.
- Configuring a private Docker registry.
- Configuring the docker-registry package.
- Configuring the registry container.
- Understanding the Docker image namespace.
Tutorial by: Play-with-docker (PWD)
Can help you learn: How to run a local registry in a container and configure your Docker engine to use the registry.
- Running a registry container in Linux.
- Testing the registry image.
- Understanding image names.
- Pushing and pulling from the local registry.
- Running a registry container with external storage.
Tutorial by: Play-with-docker (PWD)
Can help you learn: How to generate SSL certificates and run a secure local registry with a friendly domain name and basic authentication over HTTPS.
- Generating the SSL certificate in Linux.
- Running the registry securely.
- Accessing the secure registry.
- Running an authenticated secure registry.
- Authenticating with the registry.
Tutorial by: Codeship
Can help you learn: How to use the Docker push command to login and upload images to Docker registries.
- Creating a Docker repository.
- Building a new image.
- Logging in to Docker Hub.
- Pushing Docker images.
- Pushing to a non-Docker-Hub registry.
Tutorial by: Docker
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.
- Opt in to Docker security scanning.
- View Docker security scanning results.
- The Docker security scan process.
- Frequently asked questions.
- No labels