Using Docker Registries

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 makes open source software available on the GitHub Container registry. See https://github.com/oracle/docker-images and https://docs.github.com/en/packages/guides/about-github-container-registry for more information.

Oracle also hosts its own Docker registry, the Oracle Container Registry, which contains both 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 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.

Users of Oracle Cloud Infrastructure can use the Registry service for an Oracle-managed Docker registry that can serve images to your internal compute instances and can be exposed as a public registry on the Internet if required. The Oracle Cloud Infrastructure Registry service includes fine grained policy controls to allow you to control registry access. For complete documentation around using this service, see https://docs.oracle.com/iaas/Content/Registry/Concepts/registryoverview.htm

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

Using Oracle Container Registry Notary for Content Trust

The Oracle Container Registry also includes a Notary service that can be used to validate signed images that are pulled from the registry. This service helps to improve security and can mitigate against inadvertently running a compromised image on your infrastructure.

Using the Notary service is straightforward and only requires that you set two environment variables for the user that runs any Docker commands.

Set the DOCKER_CONTENT_TRUST environment variable to enable content trust within Docker:
```
export DOCKER_CONTENT_TRUST=1
```
See Enabling or Disabling Docker Content Trust for more information.
Set the DOCKER_CONTENT_TRUST_SERVER to point to the Notary service. It is important that you specify the port number in the value that you provide for this variable:
```
export DOCKER_CONTENT_TRUST_SERVER="https://container-trust.oci.oraclecloud.com:443"
```
Pull an image from the container registry, as described in Pulling Images From the Oracle Container Registry to update the Notary metadata cache. If content trust is working correctly, the image pull will behave normally. If the Notary is unavailable, Docker falls back to its local cache of signature metadata and issues a warning:
```
WARN[0015] Error while downloading remote metadata, using cached timestamp 
    - this might not be the latest version available remotely
```
If you try to pull an image that is not trusted or not hosted on the Oracle Container Registry an error is displayed and the image cannot be pulled. For example, when pulling an image from docker.io with content trust enabled and the content trust server configured for the Oracle Container Registry Notary service, the following error is returned:
```
Error: remote trust data does not exist for nginx: container-trust.oci.oraclecloud.com:443 
does not have trust data for docker.io/library/nginx
```

A user can explicitly disable content trust when running a Docker command by specifying the --disable-content-trust option or can simply unset the environment variable. Equally, content trust can be forced, regardless of the environment variable setting by running a command with --disable-content-trust=false as an option.

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:

In a web browser, log into the Oracle Container Registry using your Oracle Account:

https://container-registry.oracle.com
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.
Use the web interface to browse or search for Oracle software images.
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.
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 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.
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                     
```

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

Using Third-Party Registries

There are several third-party registries that are available for use with Oracle Container Runtime for Docker, such as the Docker Hub and the GitHub Container Registry. Oracle makes images for some licensed commercial Oracle software products on some of these third-party registries.

GitHub Container Registry

GitHub is a popular open-source development platform and is one of Oracle's preferred repositories for open source software. GitHub Container Registry provides an industry standard registry that you can use to pull images for the containers that you need to run in your environment.

No authentication is required to pull an image from GitHub Container Registry. For example, to pull the slim Oracle Linux 8 image from the GitHub Container Registry, use:

docker pull ghcr.io/oracle/oraclelinux:8-slim

For more information on GitHub Container Registry, see https://docs.github.com/en/packages/guides/about-github-container-registry

Docker Hub

The Docker Hub is available at:

https://hub.docker.com

You are able to browse the Docker Hub, but to access many of 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.

The Docker Hub may require that you are logged in before you can pull any Docker Certified 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.

Since the Docker Hub is the default registry, you can pull an image by simply specifying its name and tag. For example, to pull the oraclelinux:7-slim image:

docker pull oraclelinux:7-slim

Trying to pull repository docker.io/library/oraclelinux ... 
7-slim: Pulling from docker.io/library/oraclelinux
a61503a3b32e: Pull complete 
Digest: sha256:bb7c3969d33b3c2695b11dd705e18ed604ce0f1e3317ef293e8f0d9d125dc90a
Status: Downloaded newer image for oraclelinux:7-slim
oraclelinux:7-slim

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.

Users of Oracle Cloud Infrastructure should consider using the Oracle-managed Registry service to cater to local Docker registry requirements. See https://docs.oracle.com/iaas/Content/Registry/Concepts/registryoverview.htm.

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.

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:

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:
```
sudo 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:
```
sudo 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 Oracle Linux 7: Managing File Systems.
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:
```
sudo 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.
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
```

Create the /var/lib/registry directory.

sudo mkdir /var/lib/registry

Mount all the file systems listed in /etc/fstab.
```
sudo mount -a                        
```

Verify that the file system is mounted.

df

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

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 Setting Container Registry Options.

To use the X.509 Certificate with Docker:

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                        
```
Create the /var/lib/registry/conf.d directory, into which you need to copy the certificate and private key.
```
sudo mkdir -p /var/lib/registry/conf.d                        
```

Copy the certificate and private key to the /var/lib/registry/conf.d directory.

sudo cp certfile /var/lib/registry/conf.d/domain.crt
sudo 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:

sudo cp /etc/pki/tls/certs/registry.example.com.crt /var/lib/registry/conf.d/domain.crt
sudo cp /etc/pki/tls/private/registry.example.com.key /var/lib/registry/conf.d/domain.key

Make sure the file permissions are correct for the private key:

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

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 option not processed within --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.

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:

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

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

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:

Create the /etc/docker/certs.d/registry_hostname:port directory.
```
sudo mkdir -p /etc/docker/certs.d/registry_hostname:port
```

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

Restart the docker service.

sudo systemctl restart docker.service

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:

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                        
```
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.
Push the image to the local registry. For example:
```
docker push localhost:5000/ol7image:v1
```

See Creating a Docker Image From an Existing Container and 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.