How to Setup Your Private Docker Registry?

Introduction

Docker provides various services to manage the docker images and those are hub.docker.com, cloud.docker.com, docker trusted registry and docker registry. Each service was designed with different goals and requirements. Docker hub (hub.docker.com) is the primary source for the public images. We can set up our own private registry by using the Docker Registry, it is a free and open source tool to manage docker images. In this article, we are going to see how to set up our own private Docker registry. To follow this article, you should have basic knowledge about Docker container and related concepts.

To set up the private registry, we have two options, the first one is a standalone setup (it is available through package installer for Linux operating systems) and the second one is docker registry image (registry on docker hub). Here, we are going to see how to set up the private registry with docker registry image.

For this article, I am using the docker for windows, however, I am also providing the equivalent commands for Linux OS as well. The docker registry image was built on alpine Linux so I am using the Linux container in windows docker. I plan to cover more topics related to private registry setup with a series of articles and this is the first article of the series. The following list shows the article wise topics coverage:

• Part 1: How to set up your private Docker registry?
  • Private Docker Registry Setup
  • Storage Customization
• Part 2: How to secure your private Docker registry?
  • CA Certificate
  • Self-Signed Certificate
  • Basic Authentication
• Part 3: How to run your private registry as a service?
  • Configuring the Swarm
  • Generate Secrets
  • Run the Registry as a Service

Private Docker Registry Setup

Follow the steps below to create your private Docker registry:

• Open a PowerShell console (terminal in Linux).
• First, I want you to create a folder to share with the container and it will be used in the upcoming steps.
• Navigate to C:\ drive and create a folder with the name of localhub (md localhub). For Linux, create the same folder under /home.
• Navigate to C:\localhub folder in windows or /home/localhub in Linux and create a subfolder with the name of “registry“.
• Type the following command to pull the registry image from the docker hub:

  Windows/Linux:
  docker pull registry

• Before going to the docker registry set up, I want to set up a meaningful local domain name for your private registry instead of using localhost but this step is completely optional. I prefer to have the local domain as hub.docker.local. To configure the local domain in windows and Linux, do the following steps:
  • Windows
    • Open an elevated Notepad in docker host.
    • Open the C:\Windows\System32\drivers\etc\hosts file in the Notepad and add this hub.docker.local 127.0.0.1 as an entry in it.
    • Save and close the file.
  • Linux
    • Open a terminal in docker host and type nano /etc/hosts or vi /etc/hosts
    • Add this hub.docker.local 127.0.0.1 as an entry in it.
    • Save and close the file.
• Spin up a container with the docker registry image:

• Windows: 
  docker run -d -p 5000:5000 -v C:/localhub/registry:/var/lib/registry 
  --restart=always --name hub.local registry
  Linux:
  docker run -d -p 5000:5000 -v /home/localhub/registry:/var/lib/registry 
  --restart=always --name hub.local registry

Docker registry uses the 5000 port as default. –restart=always flag is enable the auto start after the docker restarted. -v will bind the given host folder with container file system.

Docker might ask you for the user name and password to share the localhub folder with container if you have not setup the share folder already in docker.

• Ensure the registry container is up and running:

  Windows/Linux:
  docker ps or docker container ls

  

• The next step is to prepare the docker image and push to our private registry. You can use any one of the existing images to quickly understand the concepts of the Docker Registry. Alpine is one of the lite weight Linux distribution(~2MB) so you can use this image for a quick assessment:

  Windows/Linux:
  docker pull alpine

• Create a tag to alpine Linux with hub.docker.local:5000/my-alpine.

  Windows/Linux:
  docker tag alpine hub.docker.local:5000/my-alpine

• It creates an additional tag on an existing alpine image. Tag format will be like registry hostname port/new name. Docker will extract the location from the given tag while pushing to your private registry
• Push the my-alpine image to your private registry:

  Windows/Linux:
  docker push hub.docker.local:5000/my-alpine

• Remove the alpine and its tagged version to ensure docker is pulling the image from your private registry instead of docker hub:

  Windows/Linux:
  docker rmi hub.docker.local:5000/my-alpine 
  docker rmi alpine
  

  

• Now, pull the my-alpine image from your private registry.

  Windows/Linux:
  docker pull hub.docker.local:5000/my-alpine

• Spin up a container with newly downloaded image and ask the container to list out its root directory.

  Windows/Linux:
  docker run hub.docker.local:5000/my-alpine ls

  

• You can check registry catalog on this http://hub.docker.local:5000/v2/_catalog address.
• You can inspect the localhub/registry folder to understand how docker images are stored in the docker registry.

             

• Well done! You have successfully created your own private Docker registry.
• (Optional)Stop and remove the registry container and image to move on to the next articles.

  Windows/Linux:
  docker container stop hub.local
  docker container rm hub.local

• (Optional)Finally, remove the my-alpine image as well.

  Windows/Linux:
  docker ps -a
  docker container rm container_id
  docker rmi hub.docker.local:5000/my-alpine
  

  

Storage Customization

Docker registry stores the images on the host file system(/var/lib/registry). Storing images on the file system is not a reliable solution for a production environment. You can use SSD and SAN for storing your private registry images. First, you have to mount these drives into your host, then you can easily bind to the container through volume binding. For example, you have mounted an SSD or SAN into R: drive in windows then you can mount these drives into the container through -v R:/registry:/var/lib/registry. For Linux, the volume binding will be like this -v /mnt/registry:/var/lib/registry.

Docker registry also supports to use storage driver compliant storage back-ends so you can use some third party storage back-ends like Amazon S3 bucket, Google Cloud Platform, etc.

Thanks for reading this article and I hope you find something useful. Please share your comments below. In the next article, I have written about “how to secure your private registry?”.