1. Installation¶

1.1.1. Run time¶

Systems used for running images need:

• Recent Linux kernel with CONFIG_USER_NS=y. We recommend version 4.4 or higher.
• C compiler and standard library
• POSIX shell and utilities

Some distributions need configuration changes to enable user namespaces. For example, Debian Stretch needs sysctl kernel.unprivileged_userns_clone=1, and RHEL and CentOS 7.4 need both a kernel command line option and a sysctl (that put you into “technology preview”).

1.1.2. Build time¶

Systems used for building images need the run-time prerequisites, plus:

• Bash 4.1+

and optionally:

• Docker 17.03+
• internet access or Docker configured for a local Docker hub
• root access using sudo

Older versions of Docker may work but are untested. We know that 1.7.1 does not work.

1.1.3. Test suite¶

In order to run the test suite on a run or build system (you can test each mode independently), you also need:

• Bash 4.1+
• Python 2.6+
• Bats 0.4.0
• wget

Note that without Docker on the build system, some of the test suite will be skipped.

Bats can be installed at the system level or embedded in the Charliecloud source code. If it’s in both places, the latter is used.

To embed Bats, either:

• Download Charliecloud using git clone --recursive, which will check out Bats as a submodule in test/bats.
• Unpack the Bats zip file or tarball in test/bats.

To check an embedded Bats:

$ test/bats/bin/bats --version
Bats 0.4.0

1.2.1. Debian¶

Charliecloud has been proposed for inclusion in Debian; see issue 95.

1.2.2. Gentoo¶

A native package for Gentoo is available.

To install:

$ emerge sys-cluster/charliecloud

If may necessary to accept keywords first, e.g.:

$ echo "=sys-cluster/charliecloud-0.2.3_pre20171121 ~amd64" >> /etc/portage/package.accept_keywords

A live ebuild is also available and can be keyworded via:

$ echo "~sys-cluster/charliecloud-9999 \*\*" >> /etc/portage/package.accept_keywords

1.2.3. RPM-based distributions¶

An RPM .spec file is provided in the Charliecloud source code. We are actively seeking distribution packagers to adapt this into official packages!

1.3.1. Download¶

See our GitHub project: https://github.com/hpc/charliecloud

The recommended download method is git clone --recursive.

1.3.2. Build¶

To build, simply:

$ make

To build the documentation, see doc-src/README.

1.3.3. Install (optional)¶

You can run Charliecloud from the source directory, and it’s recommended you at least run the test suite before installation to establish that your system will work.

To install (FHS-compliant):

$ make install PREFIX=/foo/bar

Note that PREFIX is required. It does not default to /usr/local like many packages.

1.4.1. Understand the security implications of Docker¶

Because Docker (a) makes installing random crap from the internet really easy and (b) is easy to deploy insecurely, you should take care. Some of the implications are below. This list should not be considered comprehensive nor a substitute for appropriate expertise; adhere to your moral and institutional responsibilities.

$ ifconfig    # note docker0 interface
$ brctl show  # note docker0 bridge
$ route -n

$ systemctl is-enabled docker
enabled
$ systemctl disable docker
$ systemctl is-enabled docker
disabled

1.4.2. Configuring for a proxy¶

By default, Docker does not work if you have a proxy, and it fails in two different ways.

The first problem is that Docker itself must be told to use a proxy. This manifests as:

$ sudo docker run hello-world
Unable to find image 'hello-world:latest' locally
Pulling repository hello-world
Get https://index.docker.io/v1/repositories/library/hello-world/images: dial tcp 54.152.161.54:443: connection refused

If you have a systemd system, the Docker documentation explains how to configure this. If you don’t have a systemd system, then /etc/default/docker might be the place to go?

The second problem is that Docker containers need to know about the proxy as well. This manifests as images failing to build because they can’t download stuff from the internet.

The fix is to set the proxy variables in your environment, e.g.:

export HTTP_PROXY=http://proxy.example.com:8088
export http_proxy=$HTTP_PROXY
export HTTPS_PROXY=$HTTP_PROXY
export https_proxy=$HTTP_PROXY
export ALL_PROXY=$HTTP_PROXY
export all_proxy=$HTTP_PROXY
export NO_PROXY='localhost,127.0.0.1,.example.com'
export no_proxy=$NO_PROXY

You also need to teach sudo to retain them. Add the following to /etc/sudoers:

Defaults env_keep+="HTTP_PROXY http_proxy HTTPS_PROXY https_proxy ALL_PROXY all_proxy NO_PROXY no_proxy"

Because different programs use different subsets of these variables, and to avoid a situation where some things work and others don’t, the Charliecloud test suite (see below) includes a test that fails if some but not all of the above variables are set.