1. Installation

This section describes how to build and install Charliecloud. For some distributions, this can be done using your package manager; otherwise, both normal users and admins can build and install it manually.

1.1. Dependencies

Charliecloud is a simple system with limited dependencies. If your system meets these prerequisites but Charliecloud doesn’t work, please report that as a bug.

Note that we do not rigorously track dependency versions. We update the versions stated below as we encounter problems, but they are not tight bounds and may be out of date.

1.1.1. Supported architectures

Charliecloud should work on any architecture supported by the Linux kernel, and we have run Charliecloud containers on x86-64, ARM, and Power. However, it is currently tested only on x86_64 and ARM.

Most container build software is also fairly portable; e.g., see Docker’s supported platforms.

1.1.2. Run time

Systems used for running images need:

  • Recent Linux kernel with user namespaces enabled. We recommend version 4.4 or higher.

  • C11 compiler and standard library

  • POSIX.1-2017 shell and utilities

The SquashFS workflow requires FUSE and Squashfuse. Note that distribution packages of Squashfuse often provide only the “high level” executables; the “low level” executables have better performance. These can be installed from source on any distribution.

Some distributions need configuration changes to enable user namespaces. For example:

  • Debian Stretch needs sysctl kernel.unprivileged_userns_clone=1.

  • RHEL/CentOS 7.4 and 7.5 need both a kernel command line option and a sysctl. Important note: Docker does not work with user namespaces, so skip step 4 of the Red Hat instructions, i.e., don’t add --userns-remap to the Docker configuration (see issue #97).

1.1.3. Build time

Systems used for building images need the run-time dependencies, plus something to actually build the images. Sub-sections list Charliecloud dependencies for each builder; see also the builders’ documentation.

All builders require internet access (e.g., for public Docker Hub) or configuration for a local image repository (e.g., a private Docker Hub).

Additional dependencies for specific components:

  • To create SquashFS image files: squashfs-tools

  • ch-build2dir: Bash 4.1+ Buildah (privileged or unprivileged)

Charliecloud can use the “rootless” mode of stock Buildah, which requires the setuid (i.e., privileged) helpers newuidmap and newgidmap.

For a fully unprivileged workflow, Charliecloud can also use a patched Buildah that does not require the setuid helpers. You need branch chown-error-tolerant-patch from our fork of Buildah. (We are working with Buildah upstream to merge our patches.)


To configure Buildah in rootless mode, which is what Charliecloud uses, make sure your config files are in ~/.config/containers and they are correct. Particularly if your system also has configuration in /etc/containers, problems can be very hard to diagnose. ch-grow (unprivileged)

This is our internal unprivileged image builder and requires: Docker (privileged)

Our wrapper scripts for Docker expect to run the docker command under sudo and need Docker 17.03+ and mktemp(1). Older versions of Docker may work but are untested. We know that 1.7.1 does not work.

1.1.4. Test suite

To run the test suite, you also need:

  • Bats 0.4.0

  • Bash 4.1+, for Bats and to make programming the tests tractable

  • Python 2.7 or 3.4+, for building some of the tests

  • Wget, to download stuff for some of the test images

  • root access via sudo (optional), to test filesystem permissions enforcement

Image building software tested, with varying levels of thoroughness:

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. Package manager install

Charliecloud is available in some distribution package repositories, and packages can be built for additional distributions. (Note, however, that system-wide installation is not required — Charliecloud works fine when built by any user and run from one’s home directory or similar.)

This section describes how to obtain packages for the distributions we know about, and where to go for support on them.

If you’d like to build one of the packages, or if you’re a package maintainer, see packaging/README and packaging/*/README for additional documentation.

Pull requests and other collaboration to improve the packaging situation are particularly welcome!

1.2.1. Debian

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

Distribution versions

proposed for Buster and Stretch backports


Lucas Nussbaum (lucas@debian.org) and Peter Wienemann (wienemann@physik.uni-bonn.de)

Bug reports to

Charliecloud’s GitHub issue tracker

Packaging source code

in Charliecloud: packaging/debian

1.2.2. Gentoo

A native package for Gentoo is available.

Package name



Oliver Freyermuth (o.freyermuth@googlemail.com)

Bug reports to

Gentoo Bugzilla

Packaging source code

Gentoo ebuild repository

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. openSUSE and SUSE

Charliecloud is included in openSUSE Tumbleweed. For SUSE Linux Enterprise users, it’s available via SUSE Package Hub.

Package name

charliecloud, charliecloud-doc and charliecloud-examples


Ana Guerrero Lopez (aguerrero@suse.com) and Christian Goll (cgoll@suse.com)

Bug reports to

openSUSE Bugzilla

Packaging source code

openSUSE Build Service

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


none yet


Oliver Freyermuth (o.freyermuth@googlemail.com)

Bug reports to

Charliecloud’s GitHub issue tracker

Packaging source code

in Charliecloud: packaging/redhat

1.2.5. NixOS

Charliecloud is available as a Nix package; see See Nixpkgs repository.

Distribution versions

Unstable channel


Bruno Bzeznik (Bruno@bzizou.net)

Bug reports to

Nixos’s GitHub issue tracker

Packaging source code

Nixpkgs repository <https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/virtualization/charliecloud/default.nix>`_.

1.3. Manual build and install

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 the contributor’s guide.

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

Docker is a convenient way to build Charliecloud images. While installing Docker is beyond the scope of this documentation, here are a few tips.

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. docker equals root

Anyone who can run the docker command or interact with the Docker daemon can trivially escalate to root. This is considered a feature.

For this reason, don’t create the docker group, as this will allow passwordless, unlogged escalation for anyone in the group. Images can contain bad stuff

Standard hygiene for “installing stuff from the internet” applies. Only work with images you trust. The official Docker Hub repositories can help. Containers run as root

By default, Docker runs container processes as root. In addition to being poor hygiene, this can be an escalation path, e.g. if you bind-mount host directories. Docker alters your network configuration

To see what it did:

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

If you don’t want the service starting automatically at boot, e.g.:

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

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 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 all_proxy=$HTTP_PROXY
export NO_PROXY='localhost,,.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.