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: https://github.com/docker/distribution.
- 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 distribution||Package location|
|Fedora 23 or later||Distro repository|
|Ubuntu 16.04||Distro repository|
|RHEL 7.X||University of Campinas (Unicamp)|
|SLES 12 SPX||Distro 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 (ftp://ftp.unicamp.br/pub/linuxpatch/docker-ppc64/). Please note that these packages are provided on an as-is basis.
- Add the unicamp repository to your system with the following command:
# cat > /etc/yum.repos.d/unicamp-docker.repo <<EOF [unicamp-docker] name=Unicamp Repo for docker Packages baseurl=http://ftp.unicamp.br/pub/ppc64el/rhel/7_1/docker-ppc64el/ enabled=1 gpgcheck=0 EOF
- 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.
After downloading and installing the docker registry packages, you need to configure storage for the images.
- 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
- Create an HTTP access control file using the
htpasswdcommand. 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-toolspackage on RHEL based systems and
apache2-utilson Ubuntu based systems.
Create registry configuration file
This sections describes how to create the registry configuration file
- 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 ..........................................................................................++ [snip]
- Copy the certificate to all the docker hosts, place it under the
specific path as shown:
# mkdir -p /etc/docker/certs.d/registry.kube.com:5000/ # cp domain.crt /etc/docker/certs.d/registry.kube.com:5000/ca.crt
- 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/registry.kube.com.crt # update-ca-trust
- On Ubuntu run the following command:
# cp domain.crt /usr/local/share/ca-certificates/registry.kube.com.crt # update-ca-certificates
- On RHEL and Fedora run the following command:
- Restart the docker daemon:
# service docker restart
Start the registry server
Start the registry server using the following command line:
# REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt 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: https://docs.docker.com/registry/configuration/
The following is a sample configuration:
# cat /etc/registry/config.yml version: 0.1 storage: filesystem: rootdirectory: /data/registry_data delete: enabled: true http: addr: registry.kube.com:5000 host: https://registry.kube.com:5000 tls: certificate: /certs/domain.crt key: /certs/domain.key auth: htpasswd: 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 https://registry.kube.com:5000
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.