How to Setup Our Own 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:
  BAT

  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:
  BAT

  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:
  BAT

  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:
  BAT

  Windows/Linux:
  docker pull alpine

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

  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:
  BAT

  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:
  BAT

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

  

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

  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.
  BAT

  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.
  BAT

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

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

  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?".

History

• 17^th October, 2018: Initial version