How to Create Your Own Private Docker Registry

How to Create Your Own Private Docker Registry
How to Create Your Own Private Docker Registry

Running your own Docker registry gives you a private place to store your Docker images. Whether you’re in a corporate environment or simply want to reduce your reliance on Docker Hub, here’s how you can proceed with registry deployment.

The Docker Registry is a server-side system that stores and indexes Docker images. You “push” precompiled images to the registry. Other users can “pull” them to run, without needing access to the original Dockerfile.

The most famous public registry is Docker Hub. Using your own registry allows you to have control over image storage and access methods. It may also feature integration with third-party tools.

There are managed services available that let you quickly create a registry installation. This guide focuses on self-hosting the registry on your own server. The only condition is that you need to install Docker and docker-compose on the machine that will host the registry.

Running a Registry

The Docker Registry is a server-side system that stores and indexes Docker images. You “push” precompiled images to the registry. Other users can “pull” them to run, without needing access to the original Dockerfile.

The most famous public registry is Docker Hub. Using your own registry allows you to have control over image storage and access methods. It may also feature integration with third-party tools.

There are managed services available that let you quickly create a registry installation. This guide focuses on self-hosting the registry on your own server. The only condition is that you need to install Docker and docker-compose on the machine that will host the registry.

run registry

Docker Registry Server is distributed as its own Docker image. You can get it from Docker Hub. The server is displayed on port 5000; You need to bind a host port to it so clients can connect.

You’ll also need to set up a volume so that Docker Hub has some place to persistently store uploaded images. Make sure you have enough free space on your host. An actively used registry can grow rapidly.

Start by creating a docker-compose.yml file to describe your deployment. You can adjust the port and file system path to match your preferences. This example will make the registry accessible on port 5000. The images will be stored in the data folder within your working directory.

version: "3"
services:
  registry:
      image: registry:2
      ports:
        - 5000:5000
      environment:
        - REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY: /data
      restart: unless-stopped
      volumes:
        - ./data:/data

Save the file and run docker-compose up -d to launch your registry. docker-compose will pull the registry image from Docker Hub. It’ll then start a new container using your configuration.

Accessing Your Registry

You should now be able to start using your registry. Tag an image using a path which resolves to your registry. You can use localhost if you’re working on the registry server itself. You should then be able to push the image up to the registry.

docker tag my-image localhost:5000/my-image
docker push localhost:5000/my-image

The image will now be available in the registry. If you inspect your data folder, you will see the layers that make up the image. You can pull it down from another machine using Docker pull. Replace localhost with the network address of the server running the registry.

Read Also-What is Shell Scripting ? – Shell Scripting for Beginner’s .

Setting up Authentication

The registry is currently unsafe. Anyone can drag and push images! Let’s solve this by setting up authentication. Once configured, you will need to use a Docker login before you can interact with the registry.

Docker Registry’s default approach to authentication uses HTTP Basic Auth. You will need to create a htpasswd file – this is best done using the commands provided by apache2-utils.

sudo apt install apache2-utils
mkdir auth
htpasswd -Bc auth/.htpasswd my-username

This user will create an authentication file for my-username. You will be prompted to provide a password. The htpasswd file will then be written to the working directory as auth/.htpasswd.

Next update your docker-compose.yml to configure the authentication system. You must specify the type of authentication used and the path to the htpasswd file. It will need to be mounted as a new volume.

version: "3"
services:
  registry:
      image: registry:2
      ports:
        - 5000:5000
      environment:
        - REGISTRY_AUTH: htpasswd
        - REGISTRY_AUTH_HTPASSWD_REALM: Registry Realm
        - REGISTRY_AUTH_HTPASSWD_PATH: /auth/.htpasswd
        - REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY: /data
      restart: unless-stopped
      volumes:
        - ./auth:/auth
        - ./data:/data

Run docker-compose up -d –force-recreate to recreate the running registry container using the new configuration. You should see that the Docker CLI is now preventing you from interacting with the registry.

To restore access, run docker login localhost:5000. If you are not running Docker on the same machine you will need to adjust the registry URI. Docker will ask you to provide your username and password. Use the values you set when you created the .htpasswd file.

Once authentication is successful, you will be able to start pushing and pulling images again. Docker caches your credentials so you won’t need to repeat authentication until you log out of Docker.

Setting Up SSL

You’ll need to add an SSL certificate for all but the most basic connections to localhost. You can add an SSL certificate to the registry by mounting the certificate in a volume and setting additional environment variables. You should usually update the port configuration so that the registry listens on the default HTTPS port 443.

version: "3"
services:
  registry:
      image: registry:2
      ports:
        - 443:5000
      environment:
        - REGISTRY_AUTH: htpasswd
        - REGISTRY_AUTH_HTPASSWD_REALM: Registry Realm
        - REGISTRY_AUTH_HTPASSWD_PATH: /auth/.htpasswd
        - REGISTRY_HTTP_ADDR: 0.0.0.0:443
        - REGISTRY_HTTP_TLS_CERTIFICATE=/certs/cert.crt
        - REGISTRY_HTTP_TLS_KEY=/certs/cert.key
        - REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY: /data
      restart: unless-stopped
      volumes:
        - ./auth:/auth
        - ./certs:/certs
        - ./data:/data

Add your certificate files to certs and then restart the registry. It should come back up with HTTPS support, using the provided certificate file.

SSL via LetsEncrypt

The registry server has built-in support for Let’s Encrypt. It lets you generate and renew your SSL certificates automatically. To use Let’s Encrypt, you need to publicly expose your registry on port 443.

Set the REGISTRY_HTTP_TLS_LETSENCRYPT_EMAIL and REGISTRY_HTTP_TLS_LETSENCRYPT_HOSTS environment variables to add TLS support to your registry. Let’s Encrypt will use the email address as the contact for your SSL certificates.

version: "3"
services:
  registry:
      image: registry:2
      ports:
        - 443:5000
      environment:
        - REGISTRY_AUTH: htpasswd
        - REGISTRY_AUTH_HTPASSWD_REALM: Registry Realm
        - REGISTRY_AUTH_HTPASSWD_PATH: /auth/.htpasswd
        - REGISTRY_HTTP_TLS_LETSENCRYPT_EMAIL: example@example.com
        - REGISTRY_HTTP_TLS_LETSENCRYPT_HOSTS: [my-registry.com]
        - REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY: /data
      restart: unless-stopped
      volumes:
        - ./auth:/auth
        - ./certs:/certs
        - ./data:/data

Rebuild the container with docker-compose up -d –force-recreate to apply the changes. The registry will use Let’s Encrypt to obtain an SSL certificate for the specified domain. It may take a few minutes for the certificate to become available.

Other Ways to Deploy

Deploying with docker-compose, HTTP Basic Auth, and Let’s Encrypt is the simplest way to run a private container registry. However, there are other options available, especially if you want more advanced access controls.

Basic Auth usage does not extend beyond a handful of users. As an alternative, the server supports a delegated authentication routine that relies on an external token server. It is designed for scenarios where tight integration with organizational access control systems is required.

The registry server itself does not enforce token authentication. Projects like Docker_auth attempt to add this missing piece, providing a full-fledged authentication system that can be deployed alongside the key registry.

Hope you like this blog….
Mahesh Wabale
Latest posts by Mahesh Wabale (see all)

Leave a Comment