Skip to content

Charliecloud

Introduction

Containers are a way to package an environment along with an executable so that no additional installation or setup is required to run it on a different machine. Charliecloud is a container solution that is designed specifically for use on HPC clusters. If you have a software that depends on a different software environment than what is installed on our HPRC clusters, Charliecloud could be a solution to you.

The basic element of a container solution is an image. An image is a file that includes a self-contained environment with both installed executables and the system libraries they depend on. The container runtime mediates between the libraries in the image and the libraries on the host system. In the case of HPRC, the container runtime software options are Charliecloud and Singularity. They can both read many common container image file formats, including Docker.

This page describe how to run Charliecloud container on FASTER and ACES.

Why use Containers

  • Shareability: you can share your container image file with others by uploading it to a public repository, and download files shared by others.
  • Portability: you can use image files made for any computer with the same architecture (x84-64).
  • Reproducibility: cluster environments can change whenever the locally installed software gets updated. Container users are largely unaffected by this.

Why use Charliecloud

  • Ease of use: Charliecloud provides a simple and user-friendly approach to containerization, offering a command-line interface that is easy to learn and use.
  • Performance: Charliecloud is designed to be lightweight and minimally intrusive, with minimal overhead. Charliecloud uses Linux user namespaces to run conainers with no daemons or privileged operations, minimizing overhead.
  • Portability: Charliecloud containers are highly portable and do not rely on proprietary formats, allowing them to run on various systems without modifications. This allows for multi-site collaborations, allowing researchers to share and run containers on different HPC clusters or computing resources.

Charliecloud Tutorial

The topics covered in this documentation are minimal. Visit Charliecloud's documentation on github for a more complete tutorial.

Charliecloud at HPRC

Charliecloud is supported on FASTER and ACES clusters.

Charliecloud software

Charliecloud is provided through our module system. 

module load charliecloud

The version may vary.

Read this before using Charliecloud commands on HPRC clusters

Charliecloud is available on login nodes and compute nodes. It is recommended to perform charliecloud tasks for large images on a compute node because they may be too resource-intensive for login nodes.

  • For resource-heavy activities, access a compute node using the VNC app from the Interactive Apps menu in the Portal.
  • For resource-light activities, access a login node using the _cluster Shell access app from the Clusters menu in the Portal.

Getting a container image

Container images are found in both public and private repositories available on the internet.

Caution: dockerhub and many other container repos are public repositories; do not trust unverified sources!

Warning: downloading a large image file is resource-intensive and takes a long time.

Charliecloud image pull

ch-image pull can automatically download and convert those images to the charliecloud file format. Read more about ch-image pull.

Some Charliecloud commands such as ch-image pull require internet access. In order to access the internet from compute nodes, use the Web Proxy module.

module load WebProxy

Charliecloud stores data in a cache directory determined by the CH_IMAGE_STORAGE environment variable. By default, the cache will be in the directory /tmp/$USER.ch on a login node or $TMPDIR/ch on a compute node. These directories are in high-speed filesystems for performance, but they node-specific and for temporary use only. If you need a persistent cache, you can set the CH_IMAGE_STORAGE environment variable to a different location, but you should expect reduced performance.

Charliecloud image pull examples

Example container image located on dockerhub at https://hub.docker.com/_/hello-world . The downloaded image will be named hello-world and it will be placed in the CH_IMAGE_STORAGE cache.

Read more about ch-image pull.

Pull to login node, interactive

Using the _cluster Shell access app from the Clusters menu in the Portal.

[username@login]$ module load charliecloud
[username@login]$ ch-image pull hello-world

Pull to compute node, interactive

Using the VNC app from the Interactive Apps menu in the Portal.

[username@compute]$ module load charliecloud WebProxy
[username@compute]$ ch-image pull hello-world

Saving an image to a file

Charliecloud container images come in two main formats: directory, and single file. HPRC supports the squash filesystem format for single file images.

Directory images

  • The image name should end in /.
  • Directory images are writable.
  • Directory read/write operation are slow, so put directory images on the high-speed tmp filesystem.
  • Images in the cache are also directory images, but you refer to them by name without the trailing slash.

Squash-filesystem images

  • The image name should end in .sqfs.
  • Squashfs images are read-only.
  • Squashfs read operations are fast, so put squashfs images on the network /scratch filesystem.

Charliecloud image convert

ch-convert can convert images to between recognized charliecloud file formats. Read more about ch-convert.

Charliecloud image convert examples

Assuming image hello-world is in the local cache, as in the ch-image pull example, these examples creates a directory image located in /tmp and a squashfs located in /scratch

Cache to directory, on compute node, interactive

Using the VNC app from the Interactive Apps menu in the Portal.

[username@compute]$ module load charliecloud
[username@compute]$ ch-convert hello-world $TMPDIR/hello-world/

Directory to squashfs, on compute node, interactive

Using the VNC app from the Interactive Apps menu in the Portal.

[username@compute]$ module load charliecloud 
[username@compute]$ ch-convert $TMPDIR/hello-world/ $SCRATCH/hello-world.sqfs

Cache to squashfs, on login node, interactive

Using the _cluster Shell access app from the Clusters menu in the Portal.

[username@login]$ module load charliecloud 
[username@login]$ ch-convert hello-world $SCRATCH/hello-world.sqfs

Interact with container

When a container image file is in place at HPRC, it can be used to control your environment for doing computation tasks.

Executing commands

The ch-run command allows you to execute a custom command within a container by specifying the image file. Read more about ch-run.

ch-run [options] <image name> <command>

The image can be in the cache, or saved in a file or directory.

Executing commands examples

Single command

Assuming image hello-world is in the local cache, as in the ch-image pull example. 

[username@login]$ module load charliecloud 
[username@login]$ ch-run --no-passwd hello-world /hello

  • Note: the hello world image is minimal, so it does not support automatic mounting of usernames. Disable automatic mounting of usernames with the --no-passwd option.

  • Note: Charliecloud does not support the automatic use of ENTRYPOINT, so specify the hello world executable /hello manually.

Interactive shell

Assuming image almalinux:8 is in the local cache, as in the Charliecloud tutorial.

Thie example launches a bash terminal, checks what OS is installed, and exits the bash terminal. 

[username@login]$ module load charliecloud 
[username@login]$ ch-run almalinux:8 -- /bin/bash
> cat /etc/redhat-release
AlmaLinux release 8.7 (Stone Smilodon)
> exit
  • Note: the -- flag means "stop parsing charliecloud arguments". This is common practice for linux executables.

Working with files

To access your files outside the container, it is necessary to mount the file system using the -b option.

It is also helpful to set a starting directory using the -c option.

Read more about ch-run options.

Working with files examples

This example mounts the current working directory $PWD (outside the container) as /host_pwd (inside the container) and uses ls to verify that a file is present inside the container. 

[username@login]$ module load charliecloud
[username@login]$ touch example.txt
[username@login]$ ch-run almalinux:8 -b "$PWD:/host_pwd" -c "/host_pwd" -- ls example.txt
example.txt
  • Note: the -- flag means "stop parsing charliecloud arguments". This is common practice for linux executables.
Back to top