Chapter 6 Using Docker Registries

A Docker registry is a store of Docker images. A Docker image is a read-only template, which is used to create a Docker container. A Docker registry is used to store Docker images, which are used to deploy containers as required.

The default Docker registry is the Docker Hub and is available at:

https://hub.docker.com

Oracle has made some enterprise-ready images available on the Docker Hub.

Oracle also hosts its own Docker registry, the Oracle Container Registry, which contains licensed and open source Oracle software. The Oracle Container Registry is located at:

https://container-registry.oracle.com

You can configure multiple registries when pulling images. See Section 4.6, “Setting Container Registry Options” for more information on using multiple registries.

The Oracle Container Registry provides a web interface that allows an administrator to select the images for the software that your organization wants to use.

If you want to use licensed Oracle software images, you must first log into the Oracle Container Registry web interface and accept the Oracle Standard Terms and Restrictions for the software images.

Open source software images, and all of the software an image contains, is licensed under one or more open source license, provided in the container image. Your use of the container image is subject to the terms of those licenses.

You can use one of the Oracle Container Registry mirrors for faster download in your geographical region.

Enterprise environments may consider setting up a local Docker registry. This provides the opportunity to convert customized containers into images that can be committed into a local registry, to be used for future container deployment, reducing the amount of customized configuration that may need to be performed for mass deployments. A local registry can also cache and host images pulled from an upstream registry. This can reduce network overhead and latency when deploying matching containers across a spread of local systems.

6.1 Pulling Images from the Oracle Container Registry

This section discusses pulling an image from the Oracle Container Registry.

If you are pulling a licensed Oracle software image, you must first log into the Oracle Container Registry and accept the Oracle Standard Terms and Restrictions. For information on pulling licensed Oracle software from the Oracle Container Registry, see Section 6.2, “Pulling Licensed Software from the Oracle Container Registry”.

To pull an image from the Oracle Container Registry:

# docker pull container-registry.oracle.com/area/image[[:tag]] 

Substitute area with the repository location in the Oracle Container Registry, and image with the name of the software image. You may optionally specify a particular [[:tag] ] for the image. For example:

# docker pull container-registry.oracle.com/os/oraclelinux:7-slim

The area and image are nearly always specified in lower case. The command to pull an image is usually provided on the repository information page in the Oracle Container Registry web interface. Other useful information about the image and how it should be run may also be available on the same page.

6.2 Pulling Licensed Software from the Oracle Container Registry

The Oracle Container Registry contains images for licensed commercial Oracle software products. To pull images for licensed software on the Oracle Container Registry, you must have an Oracle Account. You can create an Oracle Account using:

https://profile.oracle.com/myprofile/account/create-account.jspx

Note

You do not need to log into the Oracle Container Registry or accept the Oracle Standard Terms and Restrictions to pull open source Oracle software images.

To pull a licensed software image from the Oracle Container Registry:
  1. In a web browser, log into the Oracle Container Registry using your Oracle Account:

    https://container-registry.oracle.com

  2. Use the web interface to accept the Oracle Standard Terms and Restrictions for the Oracle software images you want to pull. Your acceptance of these terms are stored in a database that links the software images to your Oracle Account. Your acceptance of the Oracle Standard Terms and Restrictions is valid only for the repositories for which you accept the terms. You may need to repeat this process if you attempt to pull software from alternate or newer repositories in the registry. This is subject to change without notice.

  3. Use the web interface to browse or search for Oracle software images.

  4. On the host system, use the docker login command to authenticate against the Oracle Container Registry, using the same Oracle Account you used to log into the web interface:

    # docker login container-registry.oracle.com

    You are prompted for the username and password for the Oracle Account.

  5. Pull the images your require using the docker pull command. For example:

    # docker pull container-registry.oracle.com/java/serverjre

    For more detailed information on pulling images from the Oracle Container Registry, see Section 6.1, “Pulling Images from the Oracle Container Registry”.

    If your Oracle Account credentials can be verified and the Oracle Standard Terms and Restrictions have been accepted, the image is pulled from the Oracle Container Registry and stored locally, ready to be used to deploy containers.

  6. After you have pulled images from the Oracle Container Registry, it is good practice to log out of the registry to prevent unauthorized access, and to remove any record of your credentials that Docker may store for future operations:

    # docker logout container-registry.oracle.com

6.3 Using the Oracle Container Registry Mirrors

The Oracle Container Registry has many mirror servers located around the world. You can use a registry mirror in your global region to improve download performance of container images.

To get a list of the available mirrors, and the command to pull the image from the mirror, see the information page for an image using the Oracle Container Registry web interface. The list of registry mirrors is available towards the end of the image information page, in the Tags table. The table heading includes a Download Mirror drop down to select a registry mirror. When you select a mirror, the Pull Command column changes to show the command to pull the image from the selected mirror.

Pull an image from an Oracle Container Registry mirror using the URL for that mirror. For example, to pull the Oracle Linux 7 image from the Sydney mirror, use:

# docker pull container-registry-sydney.oracle.com/os/oraclelinux:7-slim

To download licensed Oracle software images from a registry mirror, you must first accept the Oracle Standard Terms and Restrictions in the Oracle Container Registry web interface.

https://container-registry.oracle.com

To pull licensed Oracle software images, log in to the Oracle Container Registry mirror before you pull the image. For example:

# docker login container-registry-sydney.oracle.com
# docker pull container-registry-sydney.oracle.com/java/serverjre
# docker logout container-registry-sydney.oracle.com.oracle.com

6.4 Using the Docker Hub

The Docker Hub contains Docker images for licensed commercial Oracle software products that you may use in your enterprise. The Docker Hub is at:

https://hub.docker.com

You are able to browse the Docker Hub, but to access the images hosted there, you must log in with a valid Docker ID. If you do not have a Docker ID, you can register at:

https://hub.docker.com/signup

The Docker Hub provides a web interface that allows you to select the Docker Certified images that you want to install, and to agree to any terms and conditions that may apply, or to make payment if required.

When you have agreed to the terms and conditions that apply to an image, the image is stored in the My Content area, so that you can revisit it later.

Each image provides a description and set up instructions. You may need to log into Docker Hub before you are able to pull an image. Failure to do so generates an error notifying you that the image does not exist or that you have no pull access, for example:

# docker pull store/oracle/database-enterprise:12.2.0.1
Trying to pull repository docker.io/store/oracle/database-enterprise ... 
pull access denied for store/oracle/database-enterprise, repository does not exist or may 
require 'docker login': denied: requested access to the resource is denied

The Docker Hub requires that you are logged in before you can pull any images hosted in this registry. This makes sure the terms and conditions that apply to the image have been accepted, and that any payments have been settled. The following example illustrates how you can log into the Docker Hub, and pull an image:

# docker login
Login with your Docker ID to push and pull images from Docker Hub. If you don't have a Docker ID, 
head over to https://hub.docker.com to create one.
Username: username
Password: 
Login Succeeded
# docker pull store/oracle/database-enterprise:12.2.0.1
Trying to pull repository docker.io/store/oracle/database-enterprise ... 
12.2.0.1: Pulling from docker.io/store/oracle/database-enterprise
4ce27fe12c04: Pull complete 
9d3556e8e792: Pull complete 
fc60a1a28025: Pull complete 
0c32e4ed872e: Pull complete 
b465d9b6e399: Downloading  340.7MB/2.739GB

6.5 Setting up a Local Docker Registry

This section contains information about setting up a local Docker registry server, which can be used to host your own images, and can also be used as a mirror for the Oracle Container Registry.

The registry server is a Docker container application. The host must have an Internet connection to download the registry image, either from the Docker Hub or, if support is required, from the Oracle Container Registry.

6.5.1 Creating a Registry File System

The registry server requires at least 15GB of available disk space to store registry data. This is usually located at /var/lib/registry. It is good practice to create a separate file system for this. It is recommended you create a Btrfs formatted file system to allow you to easily scale your registry file system, and to leverage Btrfs features such as snapshotting. The instructions in this section provide details for setting up a Btrfs file system. The device could be a disk partition, an LVM volume, a loopback device, a multipath device, or a LUN.

If you want dedicated storage for the registry file system, create a file system and mount it at /var/lib/registry. This example uses Btrfs to format the file system.

To create a Btrfs file system for the registry:
  1. Create a Btrfs file system with the utilities available in the btrfs-progs package, which should be installed by default. Create a Btrfs file system on one or more block devices:

    # mkfs.btrfs [-L label] block_device ...

    where -L label is an optional label that can be used to mount the file system.

    For example, to create a file system on the partition /dev/sdc1:

    # mkfs.btrfs -L var-lib-registry /dev/sdc1

    The partition must already exist. Use a utility such as fdisk (MBR partitions) or gdisk (GPT partitions) to create one if needed.

    To create a file system on a logical volume named docker-registry in the ol volume group:

    # mkfs.btrfs -L var-lib-registry /dev/ol/docker-registry

    The logical volume must already exist. Use Logical Volume Manager (LVM) to create one if needed.

    For more information on using mkfs.btrfs, see the Oracle® Linux 7: Administrator's Guide.

  2. Obtain the UUID of the device containing the Btrfs file system.

    Use the blkid command to display the UUID of the device and make a note of this value, for example:

    # blkid /dev/sdc1 
    /dev/sdc1: LABEL="var-lib-registry" UUID="50041443-b7c7-4675-95a3-bf3a30b96c17" \
    UUID_SUB="09de3cb1-2f9b-4bd8-8881-87e591841c75" TYPE="btrfs"

    If the Btrfs file system is created across multiple devices, you can specify any of the devices to obtain the UUID. Alternatively you can use the btrfs filesystem show command to see the UUID. For a logical volume, specify the path to the logical volume as the device for example /dev/ol/docker-registry. Ignore any UUID_SUB value displayed.

  3. Edit the /etc/fstab file and add an entry to make sure the file system is mounted when the system boots.

    UUID=UUID_value /var/lib/registry  btrfs  defaults  0 0

    Replace UUID_value with the UUID that you found in the previous step. If you created a label for the Btrfs file system, you can also use the label instead of the UUID, for example:

    LABEL=label /var/lib/registry  btrfs  defaults  0 0
  4. Create the /var/lib/registry directory.

    # mkdir /var/lib/registry
  5. Mount all the file systems listed in /etc/fstab.

    # mount -a
  6. Verify that the file system is mounted.

    # df
    Filesystem     1K-blocks    Used Available Use% Mounted on
    ...
    /dev/sdc1            ...    ...  ...       1%   /var/lib/registry

6.5.2 Setting up Transport Layer Security for the Docker Registry

The registry host requires a valid X.509 certificate and private key to enable Transport Layer Security (TLS) with the registry, similar to using TLS for a web server. This section discusses adding the host's X.509 certificate and private key to Docker.

If the host already has an X.509 certificate, you can use that with Docker.

If the host does not have an X.509 certificate, you can create a self-signed, private certificate for testing purposes. For information on creating a self-signed certificate and private key, see Oracle® Linux: Managing Certificates and Public Key Infrastructure.

If you want to disable X.509 certificate validation for testing purposes, see Section 4.6, “Setting Container Registry Options”.

To use the X.509 Certificate with Docker:
  1. If the host's X.509 certificate was issued by an intermediate Certificate Authority (CA), you must combine the host's certificate with the intermediate CA's certificate to create a chained certificate so that Docker can verify the host's X.509 certificate. For example:

    # cat registry.example.com.crt intermediate-ca.pem > domain.crt
  2. Create the /var/lib/registry/conf.d directory, into which you need to copy the certificate and private key.

    # mkdir -p /var/lib/registry/conf.d
  3. Copy the certificate and private key to the /var/lib/registry/conf.d directory.

    # cp certfile /var/lib/registry/conf.d/domain.crt
    # cp keyfile /var/lib/registry/conf.d/domain.key

    where certfile is the full path to the host's X.509 certificate, and keyfile is the full path to the host's private key. For example:

    # cp /etc/pki/tls/certs/registry.example.com.crt \
    /var/lib/registry/conf.d/domain.crt
    # cp /etc/pki/tls/private/registry.example.com.key \
    /var/lib/registry/conf.d/domain.key
  4. Make sure the file permissions are correct for the private key:

    # chmod 600 /var/lib/registry/conf.d/domain.key 

6.5.3 Creating the Registry

This section discusses creating the registry server as a Docker container application. Perform these steps on the registry host.

Create the Docker registry container. For example:

# docker run -d -p 5000:5000 --name registry --restart=always \
    -v /var/lib/registry:/registry_data \
    -e REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY=/registry_data \
    -e REGISTRY_HTTP_TLS_KEY=/registry_data/conf.d/domain.key \
    -e REGISTRY_HTTP_TLS_CERTIFICATE=/registry_data/conf.d/domain.crt \
    -e REGISTRY_AUTH="" \
    container-registry.oracle.com/os/registry:latest

The registry image is pulled from the Oracle Container Registry and the Docker registry container is started.

The --restart=always option starts the registry container when Docker is started.

You can map an alternate port number for your docker registry, if required, by changing the 5000 in the command above to match the port number that you would prefer to use.

If you do not have an Oracle Account and if you do not require support, you can alternately use the publicly available Docker registry image at library/registry:latest.

6.5.4 Setting up the Registry Port

The registry server runs on port 5000 by default. If you run alternative services that use the same TCP port, such as the OpenStack Keystone service, you may need to change the configuration to avoid a port conflict. All systems that require access to your registry server must be able to communicate freely on this port, so adjust any firewall rules that may prevent this.

If you are running a firewall, make sure the TCP port that you want the Docker registry to listen on is accessible. If you are running firewalld, add the default rule for the docker-registry service:

# firewall-cmd --zone=public --permanent --add-service=docker-registry 

If you do not run the registry on the default port you can specify the port directly:

# firewall-cmd --zone=public --permanent --add-port=5001/tcp

6.5.5 Distributing X.509 Certificates

If the registry host uses a self-signed X.509 certificate, you must distribute the certificate to all hosts in your deployment that you intend to use the local Docker registry.

Perform the following steps on each host that needs to access the local registry. Substitute registry_hostname with the name of the registry host, and port with the port number you selected for your Docker registry server (5000 by default).

To distribute a self signed X.509 certificate:
  1. Create the /etc/docker/certs.d/registry_hostname:port directory.

    # mkdir -p /etc/docker/certs.d/registry_hostname:port
  2. Copy the X.509 certificate from the registry host using:

    # scp root@registry_hostname:/var/lib/registry/conf.d/domain.crt \
    /etc/docker/certs.d/registry_hostname:port/ca.crt
  3. Restart the docker service.

    # systemctl restart docker.service

6.5.6 Importing Images into a Registry

When you have set up a Docker registry server, you can import images into the registry so that they can be used to deploy containers. You may either pull images from a registry, such as the Oracle Container Registry, and then commit them to your local registry, or you may wish to create your own images based on upstream images.

To import images into a local Docker registry:
  1. Pull an image from a registry. For example, you can pull an image from the Oracle Container Registry:

    # docker pull container-registry.oracle.com/os/oraclelinux:latest
  2. Tag the image so that it points to the local registry. For example:

    # docker tag container-registry.oracle.com/os/oraclelinux:latest \
    localhost:5000/ol7image:v1 

    In this example, localhost is the hostname where the local registry is located and 5000 is the port number that the registry listens on. If you are working on a Docker Engine located on a different host to the registry, you must change the hostname to point to the correct host. Note the repository and tag name, ol7image:v1 in the example, must all be in lower case to be a valid tag.

  3. Push the image to the local registry. For example:

    # docker push localhost:5000/ol7image:v1

See Section 5.3, “Creating a Docker Image from an Existing Container” and Section 5.4, “Creating a Docker Image from a Dockerfile” for information on how you can create your own images. When you have committed a customized image, you can tag it and push it to your local registry as indicated in the steps above.