Set Up Intel® Clear Containers with Docker

ID 662710
Updated 12/29/2016
Version Latest



Download PDF


Note: This article refers to an out-of-date revision of Intel Clear Containers. It will soon be updated for Intel Clear Containers 2.1.

This article describes multiple ways to get started using Intel® Clear Containers on a variety of operating systems. It is written for an audience that is familiar with Linux* operating systems, basic command-line shell usage, and has some familiarity with Docker*. We'll do an installation walk-through that explains the steps as we take them.

This article is the second in a series of three. The first article introduces the concept of Intel Clear Containers technology and describes how it fits into the overall landscape of current container-based technologies.


You will need a host upon which to run Docker and Intel Clear Containers. As described below, the choice of OS is up to you, but the host you choose has some prerequisites:

  • Ideally, for realistic performance, you would want to use a physical host. If you do, then the following should be true as well:
    • It must be capable of using Intel® Virtualization Technology (Intel® VT) for IA-32, Intel® 64, and Intel® Architecture (Intel® VT-x).
    • Intel VT-x must be enabled in the system BIOS.
  • You can use a kernel-based virtual machine (KVM), with nested virtualization, to try out Intel Clear Containers. Note that the physical host you are running the KVM instance on should satisfy the above conditions as well. It might work on a less-functional system, but ... no guarantees.

Two Paths: Clear Linux* for Intel® Architecture or Your Own Distribution

You have your choice of operating system to install to your host. You can either use Intel Clear Containers in Clear Linux* for Intel® Architecture, or use another common Linux distribution of your choice. Intel Clear Containers do not behave or function differently on different operating systems, although the installation instructions differ. Detailed instructions exist for installing to CentOS* 7.2, Fedora* 24, and Ubuntu* 16.04.

Using the Clear Linux Project for Intel Architecture

Intel Clear Containers were developed by the team that develops the Clear Linux Project for Intel Architecture operating system distribution.

Intel Clear Containers are installed by default with Docker in the current version of Clear Linux. So, one way to get started with using Intel Clear Containers is to download and install Clear Linux. Instructions for installation on a physical host are available at

For installation to a virtual machine, use the instructions at

Software in Clear Linux is delivered in bundles; the Intel Clear Containers and Docker installation is contained in a bundle called containers-basic. Once you've installed your OS, it's very easy to add the bundle:

swupd bundle-add containers-basic

From there you could simply begin using Docker:

systemctl start docker-cor

This will start Docker with the correct runtime executable ('cor') as the execution engine, thus enabling Intel Clear Containers:

docker run -ti ubuntu (for example).

A complete production installation document, that includes directions for setting up user-level Docker control, is here for a physical host:

Using a Common Linux* Distribution

If you are not using the Clear Linux for Intel Architecture distribution as your base operating system, it is possible to install to many common distributions. You will find guides for installation to CentOS 7.2, Fedora 24, and Ubuntu 16.04 (either Server or Desktop versions of these distributions will work just fine) at

The essence of all of these installations follows the same basic flow:

  • Obtain the Intel Clear Containers runtime executable, called cc-oci-runtime. This is the Intel Clear Containers OCI-compatible runtime binary that is responsible for launching a qemu-lite process and integrating filesystem and network pieces.
  • Handle additional dependencies and configuration details that the base OS may be lacking.
  • Upgrade (or fresh-install) the local Docker installation to 1.12, which is the version that supports OCI and replaceable execution engines.
  • Configure the Docker daemon to use the Intel Clear Containers execution engine by default.

The repository instructions given are tailored to the specific distribution setups, but given this general workflow and some knowledge of your own particular distribution, just about any common distribution could be adapted to do the same without too much additional effort.

Installation Walk-Through: Ubuntu* 16.04 and Docker

This section will walk through the installation of Intel Clear Containers for Ubuntu 16.04, in detail. It will follow the instructions linked to above, so it might help to have the Ubuntu installation guide open as you read. It’s located at

I'll be giving some context and explanations to the instructions as we go along, though, which may be helpful if you are adapting to your own distribution.

Note for Proxy Users

If you require the use of a proxy server for connections to the Internet, you'll want to pay attention to specific items called out in the following discussion. For most of this, it is sufficient to set the following proxy variables in your running shell, replacing the all-caps values as needed. This should be a familiar format for most that have to use these services.

# export http_proxy=http://[USER:PASSWORD@]PROXYHOST:PORT/
# export https_proxy=http://[USER:PASSWORD@]PROXYHOST:PORT/
# export no_proxy=localhost,,*.MY.DOMAIN

Install the Intel Clear Containers Runtime

The first step is to obtain and install the Intel Clear Containers runtime, as described above. For Ubuntu, there is a package available, which can be downloaded and installed, but we have to resolve a simple dependency first.

sudo apt-get install libpixman-1-0

[Note: This seems like an odd dependency, and it is. However, there's certain pieces of the qemu-lite executable that can't easily be removed; this is a holdover dependency from the larger QEMU-KVM parent. It's very low-overhead and should be resolved in a later release of Intel Clear Containers.]

Now we'll add a repository service that has the runtime that we're after, as well as downloading the public key for that repository so that the Ubuntu packaging system can verify the integrity of the packages we download from it:

sudo sh -c "echo 'deb /' >> /etc/apt/sources.list.d/cc-oci-runtime.list"
sudo apt-key add Release.key
sudo apt-get update
sudo apt-get install -y cc-oci-runtime

Configure OS for Intel Clear Containers

As of this writing, Section 3 of the installation instructions suggests the installation of additional kernel drivers and a reboot of your host at this point in the procedure. This is to acquire the default storage driver, ‘aufs’, for Docker.

However, there is a more up-to-date alternative called ‘overlay2’, and therefore this step is unnecessary with the addition of one small configuration change, which is detailed below. For now, it is okay to simply skip Section 3 and the installation of the “Linux kernel extras” packages.

One more thing remains in this step. Clear Linux for Intel Architecture updates very frequently (as often as twice a day) to stay ahead of security exploits and to be as up-to-date as possible in the open source world. Due to the Ubuntu packaging system, it's pretty certain that the mini-OS that's included as part of this package is ahead of where Ubuntu thinks it is. We need to update the OS to use the current mini-OS:

cd /usr/share/clear-containers/
sudo rm clear-containers.img
sudo ln -s clear-*-containers.img clear-containers.img
sudo sed -ie 's!"image":.*$!"image": "/usr/share/clear-containers/clear-containers.img",!g' /usr/share/defaults/cc-oci-runtime/vm.json

Install Docker* 1.12

As of this writing, even though Ubuntu 16.04 makes Docker 1.12 available as default for the OS, the packaging of it assumes the use of the native runtime. Therefore, it is necessary to install separate pieces directly from rather than taking the operating system packaging.

Similarly to the above installation of the cc-oci-runtime, we're going to add a repository, add the key for the repo, and then perform installation from the repository.

sudo apt-get install apt-transport-https ca-certificates
sudo apt-key adv --keyserver hkp:// --recv-keys 58118E89F3A912897C070ADBF76221572C52609D
sudo sh -c "echo 'deb ubuntu-xenial main' >> /etc/apt/sources.list.d/docker.list"
sudo apt-get update
sudo apt-get purge lxc-docker

[Note for proxy users: the second command above will not work with just the usual proxy environment variables that we discussed above. You'll need to modify the command as shown here:

sudo apt-key adv --keyserver hkp:// --keyserver-options http-proxy=http://[USER:PASSWORD@]HOST:PORT/ --recv-keys 58118E89F3A912897C070ADBF76221572C52609D

Before we install, we should check the current versions available. As of this writing the most current version available is docker-engine=1.12.3-0~xenial.

Install the version specified in the instructions even if it is older! More current versions may or may not have been well-integrated with the OS distribution in question. Intel Clear Containers is under active development and improvement, so not all versions will work everywhere. (As stated earlier...the best place to ensure you've got an up-to-date and working Intel Clear Containers installation is in the Clear Linux for Intel Architecture Project distribution.)

You can look at the list of versions available with:

apt-cache policy docker-engine

There are newer versions that we shouldn't use. We'll have to specify the version the instructions tell us to:

sudo apt-get install docker-engine=1.12.1-0~xenial

Configure Docker Startup for use of Intel Clear Containers

Ubuntu 16.04 uses systemd for system initialization, therefore most of what's remaining is to make some alterations in systemd with regard to Docker startup. The following instructions will override the default startup and ensure use of the cc-oci-runtime.

sudo mkdir -p /etc/systemd/system/docker.service.d/

Edit a file in that directory (as root) called clr-containers.conf. Make it look like this:

ExecStart=/usr/bin/dockerd -D –s overlay2 --add-runtime cor=/usr/bin/cc-oci-runtime --default-runtime=cor

This is a systemd directive file for the docker service; it specifies the command-line options to the dockerd processes that will force it to use Intel Clear Containers instead of its native service.

Note also the addition of the ‘-s overlay2’ flag, which is not in the instructions (at time of this writing). This tells the Docker daemon to use the ‘overlay2’ storage driver in preference to ‘aufs’. This is the recommended storage driver to use for kernels of version 4.0 or greater.

Now we need to make sure systemd recognizes the change, and then restart the service:

sudo systemctl daemon-reload
sudo systemctl restart docker

Note that I've skipped some additional, optional configuration that's called out in the installation document. This additional configuration is to allow for large numbers of Intel Clear Containers to run on the same machine. Without performing this optional action, you will be limited on how many containers can run simultaneously. See section 6.1 of the instruction document if you want to remove this limitation.

Ready to Run

At this point you should be able to run Docker container startup normally:

sudo docker run -ti ubuntu

This will give you a command prompt on a simple Ubuntu container. You can log in separately and see the qemu-lite process running, like this (the container is running in the background window, the process display is in the foreground).


Now you have everything you need to take Intel Clear Containers for a test drive. For the most part, it will behave just like any other Docker installation. As shown, integration with Docker Hub and the huge library of container images present there is open to use by Intel Clear Containers.

This has been the second of a three-part series on Intel Clear Containers. In the final article, I'll dive into the technology a bit more, exploring some of the major engineering tradeoffs that have been made, and where development is likely headed in upcoming releases. I'll also discuss the use of Intel Clear Containers in various orchestration tools besides Docker.

Read the first article in the series: Intel® Clear Containers 1: The Container Landscape

About the Author

Jim Chamings is a Sr. Software Engineer at Intel Corporation, who focuses on enabling cloud technology for the Intel Developer Relations Division. Before that, he worked in the Intel Open Source Technology Center (OTC), on both Intel Clear Containers and the Clear Linux Project for Intel Architecture. He’d be happy to hear from you about this article at: