Chapter 2 Installing Oracle Container Runtime for Docker

This chapter describes the steps required to perform an installation of Oracle Container Runtime for Docker on an Oracle Linux 7 host.

Before you install and configure the Docker Engine on an Oracle Linux 7 system, make sure you are running an appropriate release of the Unbreakable Enterprise Kernel. Instructions to install UEK are detailed in Section 2.1, “Setting up Unbreakable Enterprise Kernel”.

If you are already running either UEK R4 or UEK R5, you can follow the instructions in Section 2.4, “Installing Oracle Container Runtime for Docker” to complete your installation.

2.1 Setting up Unbreakable Enterprise Kernel

Configure the system to use the Unbreakable Enterprise Kernel Release 5 (UEK R5) or later and boot the system with this kernel. If you are using an earlier Unbreakable Enterprise Kernel (UEK) release, or the Red Hat Compatible Kernel (RHCK), you must upgrade the kernel.

To install or update the UEK:
  1. If your system is registered with ULN, disable access to the ol7_x86_64_UEKR3 and ol7_x86_64_UEKR4 channels, and enable access to the ol7_x86_64_UEKR5 channel.

    Log into https://linux.oracle.com with your ULN user name and password and click on the Systems tab to select the system where you installing Oracle Container Runtime for Docker. Go to the Manage Subscriptions page and update the channel subscriptions for the system. Click on Save Subscriptions to save your changes.

  2. If you use the Oracle Linux yum server, disable the ol7_UEKR3 and ol7_UEKR4 repositories and enable the ol7_UEKR5 repository. You can do this easily using yum-config-manager:

    # yum-config-manager --disable ol7_UEKR3 ol7_UEKR4
    # yum-config-manager --enable ol7_UEKR5
  3. Run the following command to upgrade the system to the selected UEK release:

    # yum update
  4. Reboot the system, selecting the UEK kernel if this is not the default boot kernel.

    # systemctl reboot

2.2 Enabling Access to the Oracle Container Runtime for Docker Packages

To access to the Oracle Container Runtime for Docker packages, you must enable the appropriate ULN channel or yum repositories.

If your system is registered with ULN, enable the ol7_x86_64_addons channel. Use the ULN web interface to subscribe the system to the appropriate channel:

  1. Log in to https://linux.oracle.com with your ULN user name and password.

  2. On the Systems tab, click the link named for the system in the list of registered machines.

  3. On the System Details page, click Manage Subscriptions.

  4. On the System Summary page, select each required channel from the list of available channels and click the right arrow to move the channel to the list of subscribed channels.

    Subscribe the system to the ol7_x86_64_addons channel.

  5. Click Save Subscriptions.

If you use the Oracle Linux yum server, enable the ol7_addons channel. To enable a yum repository on your system, use the yum-config-manager command. For example, run:

# yum-config-manager --enable ol7_addons

2.3 Removing the docker Package

The latest Docker package is docker-engine, which conflicts with the older docker package. If you have the older docker package installed, you must remove it before you install Docker Engine. To check if you have the older docker package installed, run:

# rpm -qi docker

If the older docker package is installed, stop the docker service and remove the package. To stop the docker service:

# systemctl stop docker

Remove the docker package.

# yum remove docker

You can now install the docker-engine package.

2.4 Installing Oracle Container Runtime for Docker

To install the docker-engine and docker-cli packages.

# yum install docker-engine docker-cli

Start the docker service and configure it to start at boot time.

# systemctl enable --now docker

To check that the docker service is running, use the following command:

# systemctl status docker

You can also use the docker info command to display information about the configuration and version of the Docker Engine.

# docker info

For more information, see the docker(1) manual page.

2.5 Configuring a Proxy Server

To configure web proxy networking options, create the drop-in file /etc/systemd/system/docker.service.d/http-proxy.conf that contains the following lines:

[Service]
Environment="HTTP_PROXY=proxy_URL:port"
Environment="HTTPS_PROXY=proxy_URL:port"

Replace proxy_URL and port with the appropriate URLs and port numbers for your web proxy.

After adding or modifying a systemd drop-in file while the docker service is running, you need to tell systemd to reload the configuration for the service.

# systemctl daemon-reload

Restart the docker service for the configuration changes to take effect.

# systemctl restart docker

2.6 Configuring IPv6 Networking

With IPv6 enabled, Docker assigns the link-local IPv6 address fe80::1 to the bridge docker0.

For more information about configuring Docker networking, see:

https://docs.docker.com/engine/userguide/networking/

To configure IPv6 networking:
  1. Create or edit /etc/docker/daemon.json.

    If you are creating this file from scratch, it should look like this:

    {
      "ipv6": true
    }

    If this file already exists and contains other entries, be careful that adding a line for the ipv6 configuration variable conforms with typical JSON formatting.

    If you want Docker to assign global IPv6 addresses to containers, additionally specify the IPv6 subnet for the fixed-cidr-v6 option, for example:

    {
      "ipv6": true,
      "fixed-cidr-v6": "2001:db8:1::/64"
    }

    Similarly, you can also configure the default IPv6 gateway that should be used by Docker, using the default-gateway-v6 parameter in this configuration file.

    For more information on the format and options for this configuration file, see:

    https://docs.docker.com/engine/reference/commandline/dockerd/#daemon-configuration-file

  2. Check that the --ipv6, --fixed-cidr-v6 and default-gateway-v6 options are not being invoked as command line switches when starting the Docker engine daemon.

    You should check that these options do not appear in either the /etc/sysconfig/docker or /etc/sysconfig/docker-networking files. These files are deprecated and may be removed in future releases. If these files contain any other configuration parameters, consider whether you could move these into /etc/docker/daemon.json to future-proof your configuration.

    Also check that these options do not appear in any systemd drop-in files in /etc/systemd/system/docker.service.d/. While this is a supported configuration option, it is preferable to keep all Docker Engine configuration in the same place, where possible.

2.7 Configuring Docker Storage

The Docker Engine is configured to use overlay2 as the default storage driver to manage Docker containers. This provides a performance and scalability improvement on earlier releases that used the device mapper as the default storage driver, but the technology is new and should be tested properly before use in production environments. For more information on overlay2, see:

https://docs.docker.com/engine/userguide/storagedriver/overlayfs-driver/

Overlay file systems can corrupt when used in conjunction with any file system that does not have dtype support enabled.

Note

For Oracle Linux 7 Update 4 or earlier, the root partition is automatically formatted with -n ftype=0 (disabling dtype support), where XFS is selected as the file system.

The Docker Engine installer checks the filesystem for dtype support, and if this is not enabled, the default storage driver is set to use devicemapper. This check is only performed on a fresh installation of Docker Engine. The configuration of an existing Docker installation is unaffected during upgrade.

This allows Docker to function on a default Oracle Linux 7 system without any additional configuration required, immediately after install. However, using the devicemapper is not recommended for production environments. Performance and scalability can be compromised by this configuration. Therefore, it is important to consider using dedicated storage for Docker, and to change the storage driver to use either btrfs or overlay2.

Important

If you continue to use devicemapper as the storage driver, you should be aware that some Docker images, such as the image for Oracle Database, require that the base device size is set to 25GB or more. The default base device size for devicemapper is updated to 25GB, but this only meets a minimum requirement for some containers. Where additional capacity may be required, the base device size can be changed by setting the dm.basesize start option for a container or, globally, for the Docker Engine.

You can change this value globally, by adding it to the storage-opts configuration parameter in /etc/docker/daemon.json, for example:

{
...
"storage-opts" : [ "dm.basesize=50G" ],
...
}

The base device size is sparsely allocated, so an image may not initially use all of this space. You can check how much space is allocated to the Base Device Size by running the docker info command.

For more information on storage driver options, see:

https://docs.docker.com/engine/reference/commandline/dockerd/#storage-driver-options

Oracle recommends using Btrfs as a more stable and mature technology than overlayfs.

In most cases, it is advisable to create a dedicated file system to manage Docker containers. This file system can be mounted at /var/lib/docker at boot time, before the Docker service is started.

Any unused block device that is large enough to store several containers is suitable. The suggested minimum size is 1GB but you might require more space to implement complex Docker applications. If the system is a virtual machine, Oracle recommends that you create, partition, and format a new virtual disk. Alternatively, convert an existing ext3 or ext4 file system to Btrfs. For information on converting file systems, see the Oracle® Linux 7: Administrator's Guide.

If an LVM volume group has available space, you can create a new logical volume and format it as a Btrfs file system.

Important

XFS file systems must be created with the -n ftype=1 option enabled for use as an overlay. The root partition on Oracle Linux 7 is automatically formatted with -n ftype=0 where XFS is selected as the file system. Therefore, if you intend to use the overlay2 storage driver in this environment, you must format a separate device for this purpose.

2.7.1 Configuring Docker Storage Automatically

The docker-engine package includes a utility that can help you to configure storage correctly for a new Docker deployment. The docker-storage-config utility can format a new block device, set up the mount point and correctly configure the Docker Engine to run with the appropriate storage driver so that your storage configuration follows Oracle guidelines.

For usage instructions, run docker-storage-config with the -h option:

# docker-storage-config -h

The docker-storage-config utility requires that you provide the path to a valid block device to use for Docker storage. The script formats the device with a new file system. This can be a destructive operation. Any existing data on the device may be lost. Use the lsblk command to help you correctly identify block devices currently attached to the system.

To automatically set up your Docker storage, before installation, run docker-storage-config as root:

# docker-storage-config -s btrfs -d /dev/sdb1

Substitute /dev/sdb1 with the path to the block device that you attached as dedicated storage.

You can substitute btrfs with overlay2 if you would prefer to use this storage driver. If you do this, the block device is formatted with XFS and dtype support is enabled.

To overwrite an existing configuration, you can use the -f flag. If your Docker installation has already been used to set up images and containers, this option is destructive and may make these images and containers inaccessible to you, so the option should be used with caution.

2.7.2 Configuring Docker Storage Manually

This section discusses manually setting up a file system for Docker containers.

To manually prepare a dedicated file system to manage Docker containers:
  1. Configure the Docker Engine to use Btrfs as the storage driver to manage containers. Use yum to install the btrfs-progs package:

    # yum install btrfs-progs

    If the root file system is not configured as a Btrfs file system, create a Btrfs file system on a suitable device or partition such as /dev/sdb1 in this example:

    # mkfs.btrfs /dev/sdb1
  2. Configure the Docker Engine to use a block device formatted with XFS in conjunction with the overlay2 storage driver to manage containers. Format the block device with the XFS file system, for example to format a partition /dev/sdb1:

    # mkfs -t xfs -n ftype=1 /dev/sdb1

    It is essential that you use the -n ftype=1 option when you create the file system or you cannot use overlayfs. To check if a mounted XFS partition has been formatted correctly, run the following command and check the output to make sure that ftype=1:

    # xfs_info /dev/sdb1 | grep ftype
  3. Use the blkid command to display the UUID and TYPE for the new file system and make a note of this value, for example:

    # blkid /dev/sdb1
    /dev/sdb1: UUID="26fece06-e3e6-4cc9-bf54-3a353fdc5f82" TYPE="xfs" \
      PARTUUID="ee0d0d72-dc97-40d8-8cd9-39e29fbc660e" 

    The UUID for the file system on the device /dev/sdb1 in this example is the UUID value 26fece06-e3e6-4cc9-bf54-3a353fdc5f82. You can ignore the PARTUUID value, which is the UUID of the underlying partition. The TYPE of file system in this example is the TYPE value xfs.

  4. Create an entry in your /etc/fstab file to make sure the file system is mounted at boot. Open /etc/fstab in an editor and add a line similar to the following:

    UUID=UUID_value /var/lib/docker   fstype     defaults        0 0

    Replace UUID_value with the UUID value. Replace fstype with the file system TYPE.

    Note

    Previous versions of Docker required that dedicated storage used by Docker was mounted via a Systemd mount target and a Systemd drop-in file for the Docker service. This requirement was related to an issue where the storage was automatically unmounted when the Docker service was stopped. This issue no longer applies. If your storage is currently mounted using these methods, consider simplifying your environment by removing the Systemd drop-in and mount target and replacing this with an fstab entry.

    This entry defines a mount for the file system on /var/lib/docker. You might need to create this directory if you are performing a fresh installation:

    # mkdir /var/lib/docker

    You must mount the file system to start using it:

    # mount /var/lib/docker

2.7.3 Configuring a Docker Storage Driver

This section discusses setting up a storage driver for Docker.

To configure a Docker storage driver:
  1. Create or edit /etc/docker/daemon.json.

    If you are creating this file from scratch, it should look like this:

    {
      "storage-driver": "btrfs"
    }

    Replace btrfs with your preferred storage driver. If you are using an XFS, ext3 or ext4 file system, you might replace btrfs with overlay2.

    If this file already exists and contains other entries, be careful that adding a line for the storage-driver configuration variable conforms with typical JSON formatting.

    For more information on the format and options for this configuration file, see:

    https://docs.docker.com/engine/reference/commandline/dockerd/#daemon-configuration-file

  2. Check that the --storage-driver option is not being invoked as a command line switch when starting the Docker Engine daemon.

    You should check that this option does not appear in either the /etc/sysconfig/docker or /etc/sysconfig/docker-storage files. These files are deprecated and may be removed in future releases. If these files contain any other configuration parameters, move these into /etc/docker/daemon.json to future-proof your configuration.

    Also check that this option does not appear in any systemd drop-in files in /etc/systemd/system/docker.service.d/. While this is a supported configuration option, it is preferable to keep all Docker Engine configuration consolidated and in the same place, where possible.

  3. When you have started the Docker Engine and it is running, check that it is using the storage driver that you have configured:

    # docker info | grep Storage

    You can run the docker info command on its own to get a more detailed view of the configuration.

2.8 Excluding Docker Container Files from locate Output

If you have installed the mlocate package, it is recommended that you modify the PRUNEPATHS entry in /etc/updatedb.conf to prevent updatedb from indexing directories below /var/lib/docker, for example:

PRUNEPATHS="/media /tmp /var/lib/docker /var/spool /var/tmp"

This entry prevents locate from reporting files that belong to Docker containers.