Set up a docker private registry with basic HTTP authentication support


Docker Registry is a server-side application that enables sharing of docker images. The public registry is hosted on the Docker hub. If accessing the public hosted registry is not an option due to company policy, firewall restrictions and so on, you can deploy a private registry. The registry code is open source and available under the Apache License. Note that the private registry doesn't have a web user interface like the public hosted registry. Private registry is an application providing the registry API for the docker engine to work with images.

This article will show you haw to set up a docker private registry (ver 2.x) with TLS and HTTP authentication on an OpenPower server running Red Hat Enterprise Linux (RHEL) 7.1 LE Linux distribution. With the exception of the instructions specifically related to registry package installation on RHEL, these instructions also work with most other Linux distributions (Ubuntu, Fedora, and so on.) running on OpenPower servers.


You can access the source code for the latest docker registry (version 2.x) at:

  • On RHEL and Fedora for Intel servers and PowerPC servers, the registry version 2.x package is named, docker-distribution.
  • On Ubuntu for Intel and PowerPC servers, the registry version 2.x package is named, docker-registry.

The following table lists the location of the relevant packages for PowerPC LE (ppc64le) platforms.

Linux distributionPackage location
Fedora 23 or laterDistro repository
Ubuntu 16.04Distro repository
RHEL 7.XUniversity of Campinas (Unicamp)
SLES 12 SPXDistro repository

Install docker private registry package on RHEL LE

Pre-compiled packages for docker and docker registry (ver 2.1) for RHEL 7.1 LE are available from the University of Campinas (unicamp) repository ( Please note that these packages are provided on an as-is basis.

  1. Add the unicamp repository to your system with the following command:
    # cat > /etc/yum.repos.d/unicamp-docker.repo <<EOF
    name=Unicamp Repo for docker Packages
  2. Install the package:
    # yum install -y docker-distribution

Note about installing docker private registry packages on other Linux distributions

  • On Fedora for OpenPower servers, the registry package, version 2.x is named docker-distribution.
  • On Ubuntu for OpenPower the registry package, version 2.x is named docker-registry.

Install the respective package for your distribution; the remaining instructions are the same regardless of distribution or server.


Configure storage

After downloading and installing the docker registry packages, you need to configure storage for the images.

  1. Create a directory to store the images. This can be created on any mount point on the designated server, backed by either local disk or external disk. In this example, /data/ is a separate partition on the disk which will be used for storing docker images.
    # mkdir /data/registry_data
  2. Create an HTTP access control file using the htpasswd command. The following command installs the httpd-tools package, which contains the htpasswd tool and creates a file, registry_passwd, for the user, regimguser. Replace the file name and user name per your requirements. The option, -B, is used for bcrypt encryption of passwords.
    # yum install -y httpd-tools 
    # htpasswd -Bc /etc/registry/registry_passwd regimguser

    Note that htpasswd is available as part of httpd-tools package on RHEL based systems and apache2-utils on Ubuntu based systems.

Create registry configuration file

This sections describes how to create the registry configuration file

  1. Create a certificate for securing the registry using TLS and copy it to all docker hosts. Ensure you use the registry FQDN as the CN when generating the certificates.
    # mkdir /certs/
    # openssl req  -newkey rsa:4096 -nodes -sha256 -keyout /certs/domain.key  -x509 -days 365 -out /certs/domain.crt
    Generating a 4096 bit RSA private key
  2. Copy the certificate to all the docker hosts, place it under the specific path as shown:
    # mkdir -p /etc/docker/certs.d/
    # cp domain.crt /etc/docker/certs.d/
  3. Trust the certificate at OS level and update the CA list. The instructions varies between different Linux distributions.
    • On RHEL and Fedora run the following command:
      # cp domain.crt /etc/pki/ca-trust/source/anchors/
      # update-ca-trust
    • On Ubuntu run the following command:
      # cp domain.crt /usr/local/share/ca-certificates/
      # update-ca-certificates
  4. Restart the docker daemon:
    # service docker restart

Start the registry server

Start the registry server using the following command line:

REGISTRY_HTTP_TLS_KEY=/certs/domain.key screen -dmS registry registry /etc/registry/config.yml

REGISTRY_HTTP_TLS_CERTIFICATE and REGISTRY_HTTP_TLS_KEY can also be specified as part of the registry configuration file. The default configuration file for the private registry can be found in /etc/registry/config.yml. Details on available configuration options can be found at:

The following is a sample configuration:

# cat /etc/registry/config.yml
version: 0.1
    rootdirectory: /data/registry_data
    enabled: true
      certificate: /certs/domain.crt
      key: /certs/domain.key
    realm: basic-realm
    path: /etc/registry/registry_passwd

Start the registry server by running the following command:

# screen -dmS registry registry /etc/registry/config.yml

Validate access to the registry server

From any docker host, validate that you can log into the registry server. Use the userid and password that was created with htpasswd tool.

# docker login

You are now all set to use docker private registry in your environment.


The IBM Linux Technology Center (LTC) is a team of IBM open source software developers who work in cooperation with the Linux open source development community. The LTC serves as a center of technical competency for Linux. Connect with us.

Follow us on TwitterJoin the communityRead my blog

Downloadable resources

Related topics


Sign in or register to add and subscribe to comments.

ArticleTitle=Set up a docker private registry with basic HTTP authentication support