HPCCM makes creating and maintaining containers so much easier.
HPCCM with Docker and Podman
The past two articles in this newsletter have been about containers and HPC, and I would like to write one more article in that vein. In the HPC Containers Survey, HPC Container Maker (HPCCM) was mentioned a couple of times. I wrote about HPCCM in an article on best practices for containers and in another article about building containers, but I want to address the container spec files that are used to build container images with Docker and Podman.
HPCCM is one of those tools you didn’t know you needed, until you needed it. Building a container image is not difficult because, in the case of a Docker image, you can start with an existing image, install some packages or build code, and then save a running container to a new image.
If you want to get fancier and have a container image that builds an application, but you don’t want to save all of the build tools because the image would be HUGE, or if you want to build an image that, when invoked, has all kinds of entry points that can’t be used in complicated ways, then spec files can get long and complicated. On the other hand, you might want to build container images for Docker and Singularity, which means you would need to know both spec file formats. All of these issues can be addressed by HPCCM.
The tool is written in Python, which allows you to create a simple “recipe” for your container image and then turn that recipe into a container specification file for either Docker or Singularity/Apptainer. You can write just a few lines of Python and create hundreds of lines of directions in the specification file. Moreover, this recipe is much easier to maintain than a long specification file, and because it’s Python, you can use any Python code or tools as part of the recipe.
The recipe uses “building blocks” for capabilities such as compilers, libraries, and applications. The container options for building these components also contain some best practices. A very powerful feature of HPCCM is that it makes multistage spec files extremely easy to create. An example of a multistage build has an application in the container image, but not the build tools, leaving just the runtime. HPCCM allows you to install the tools, build the application, and then remove the build tools, except for the necessary runtime components.
In this article, I focus on creating a simple recipe for a development container image that contains a compiler set, as well as a Message Passing Interface (MPI) library. Moreover, I want to take the resulting Dockerfile that HPCCM creates and use Docker and Podman to build the final container image.
Development Container
One of the better ways to use a container is as a development environment for building applications. You can use whatever operating system (OS) you like as your base for the container image; add in whatever development tools you like, including compilers, libraries, and tools; and create a container image. You can then run that image, mount your home directory into the running container, giving you access to your source code, and start to create and edit the code and build and test your application: in other words, a development environment.
However, installing all the development tools you want into the container image can be somewhat of a pain. Your container spec file can grow very quickly, making editing it a bit challenging, to say the least. I’ll show you how to use HPCCM to make the creation and maintenance of the spec file easier.
One quick point to make is that unless you know how to run a container to allow X applications (GUI applications) run in the container and display on the host, then you probably won’t install GUI editors or other tools in the container. You will run those on the host, save the code, but build (compile) the code in the container. Although you can’t just compile with your integrated development environment (IDE) tool, you can just switch to the running container terminal window and build the code with Make, CMake, or another build tool.
Note that nothing stops you from installing GUI applications in the container, but in this article, I do not explain how to run them from inside a container. Otherwise, feel free to install your favorite ASCII-based editors such as Vi, Emacs, or something else.
For the sake of argument, I’ll start with Ubuntu 24.04 as the base OS. I want to install the GNU compiler chain for the latest versions of C, C++, and Fortran. Additionally, I want to install the latest released version of Open MPI. To be complete, I will also install Vi (Vim), because the base container doesn’t include it, and it is the text-based editor I use the most.
One more note about container “design” for development environments: You could install multiple libraries and use environment modules within the container to switch between them, but that’s not really the point of a simple development environment. The same is true for multiple compilers. Just make a container for a single combination of compiler and libraries. If you want more options, just create a container for the specific combinations you want. Remember, with HPCCM, you maintain a simple recipe (Python script) for the specific container.
I asked Scott McMillan, the HPCCM developer, if he had any tips on how to maintain the various recipes, and he had a good suggestion: You can take recipes for different but related containers and combine them into a single file so you can specify a compiler of library on the command line and create a container that matches the command-line interface (CLI) options. In his following example recipe, you can chose to build with Open MPI or MPICH:
Stage0 += baseimage(image='ubuntu:24.04')
Stage0 += gnu(version='14')
if USERARG.get('mpi') == 'mpich':
Stage0 += mpich()
else:
Stage0 += openmpi()
# end ifThen, you invoke HPCCM with the command:
$ hpccm --recipe recipe.py --userarg mpi=mpich --format Docker > Dockerfile
The sample recipe might not work as written; it is just a sample. You could also use USERARGs to call a single recipe to create a customized container. Don’t forget that an HPCCM recipe is just a Python script, so you could use all kinds of Python tools in the recipe.
dev1 – Base OS
I like to build up elements in steps starting with the smallest, the OS. In the following recipe, I create my base container with Ubuntu 24.04 and add Vim to the mix:
Stage0 += baseimage(image='ubuntu:24.04') Stage0 += apt_get(ospackages=['vim'])
Note that I used apt-get to install vim and that I specified the packages in a Python list. This allows you to specify several packages in a single command in the recipe.
Note that both apt-get and yum are available as building blocks in HPCCM for installing packages. If you need some other package manager, you can use the code for either an existing package manager to create your own or open an issue on the HPCCM GitHub site. You could also use the generic_build building block to compile what you need from scratch.
The HPCCM syntax is fairly easy to understand and is explained in the documentation. The syntax allows you to create a multistage build if you want (not covered here) with the use of “stages.” With building blocks, you add the components you want to the base object (Stage0), where a baseimage has been specified.
For the sake of argument, I create a Dockerfile spec file from this recipe,
$ hpccm --recipe dev1.py --format docker > Dockerfile
with the resulting Dockerfile:
FROM ubuntu:24.04 RUN apt-get update -y && \ DEBIAN_FRONTEND=noninteractive \ apt-get install -y --no-install-recommends vim && \ rm -rf /var/lib/apt/lists/*
The command to build the Docker container image is:
$ docker build -f Dockerfile -t ubuntu-24.04-dev1 .
After a bit, the container is done building and can be seen in the list of Docker container images:
$ docker images REPOSITORY TAG IMAGE ID CREATED SIZE ubuntu-24.04-dev1 latest 2358ab17d70c 13 minutes ago 149MB
Note that the image is only 149MB, which is pretty small compared with the multigigbyte installations on desktops and laptops.
To confirm that the container image works and that Vi is present, create an interactive container:
$ docker run --rm -it \ -v /home/laytonjb:/home/laytonjb \ --user $(id -u):$(id -g) \ --workdir=/home/laytonjb ubuntu-24.04-dev1 /bin/bash
I should clarify something about this command: The part of the command that reads --user $(id -u):$(id -g) takes the user and group identifiers (UID and GID) from your account and uses them in the container. This step helps a great deal with manipulating files. If you didn’t take this step, you would get a strange UID and GID on the files that were created. Believe me, taking this step makes life much simpler in the container world.
Note that I mount my home directory, /home/laytonjb, in the container as /home/laytonjb, which is what you want when creating a development environment, because all your source trees appear in the container if you mount the host directory into the container. Moreover, when the container starts, it changes directory to /home/laytonjb with the option --workdir=/home/laytonjb.
I check that Vi is in the container, indicating that the container was built successfully:
ubuntu@5e8f3323fb36:/home/laytonjb$ whereis vi vi: /usr/bin/vi ubuntu@5e8f3323fb36:/home/laytonjb$ pwd /home/laytonjb
This container image appears to be a good start toward creating a development environment.
dev2 – Add Compilers
The container image just built is ready for adding compilers or whatever tools you need to develop applications. You have several options, and with HPCCM, you can install common compiler suites including GNU, NVIDIA, and Flang compilers. You could also use the generic_build building block if you are building from source or using a package manager building block to install them. For this example, I install version 14 of the C, C++, and Fortran GNU compilers.
The HPCCM building block is simply named gnu. I add this to the recipe from the previous section with one small exception: Rather than start with the base Ubuntu 24.04, I start with the dev1 container image from the previous section because it has everything I want. The HPCCM recipe I used is:
Stage0 += baseimage(image='ubuntu-24.04-dev1') Stage0 += apt_get(ospackages=['vim']) compiler = gnu(version='14') Stage0 += compiler
I chose to add the latest GNU compilers to the container image, so I had to specify the version number (14).
The command to take the recipe file and convert it to a Dockerfile is:
$ hpccm --recipe dev2.py --format docker > Dockerfile
The resulting Dockerfile is shown in Listing 1. Now you can see where an HPCCM recipe is shorter than a Dockerfile.
Listing 1: dev2 Dockerfile
FROM ubuntu-24.04-dev1 RUN apt-get update -y && \ DEBIAN_FRONTEND=noninteractive \ apt-get install -y --no-install-recommends vim && \ rm -rf /var/lib/apt/lists/* # GNU compiler RUN apt-get update -y && \ DEBIAN_FRONTEND=noninteractive \ apt-get install -y --no-install-recommends g++-14 gcc-14 gfortran-14 && \ rm -rf /var/lib/apt/lists/* RUN update-alternatives \ --install /usr/bin/g++ g++ $(which g++-14) 30 && \ update-alternatives --install /usr/bin/gcc gcc $(which gcc-14) 30 && \ update-alternatives --install /usr/bin/gcov gcov $(which gcov-14) 30 && \ update-alternatives --install /usr/bin/gfortran gfortran $(which gfortran-14) 30
The container image built just fine:
$ docker images REPOSITORY TAG IMAGE ID CREATED SIZE ubuntu-24.04-dev2 latest 8f311b6fbb1e 9 seconds ago 1.82GB ubuntu-24.04-dev1 latest 2358ab17d70c 35 minutes ago 149MB
Notice the very large jump in the size of the container image.
To prove the container image was built correctly, run and check it. To run the container, I used the following command (virtually identical to the previous one):
$ docker run --rm -it \ -v /home/laytonjb:/home/laytonjb \ --user $(id -u):$(id -g) \ --workdir=/home/laytonjb ubuntu-24.04-dev2 /bin/bash
Once in the container, I checked whether the compilers were there, starting with GCC, then GFortran (the most important building block) and G++ (Listing 2).
Listing 2: Checking for Compilers
ubuntu@e45200a49bf1:/home/laytonjb$ gcc -v Using built-in specs. COLLECT_GCC=gcc COLLECT_LTO_WRAPPER=/usr/libexec/gcc/x86_64-linux-gnu/14/lto-wrapper OFFLOAD_TARGET_NAMES=nvptx-none:amdgcn-amdhsa OFFLOAD_TARGET_DEFAULT=1 Target: x86_64-linux-gnu Configured with: ../src/configure -v --with-pkgversion='Ubuntu 14-20240412-0ubuntu1' ... Thread model: posix Supported LTO compression algorithms: zlib zstd gcc version 14.0.1 20240412 (experimental) [master r14-9935-g67e1433a94f] (Ubuntu 14-20240412-0ubuntu1) ubuntu@e45200a49bf1:/home/laytonjb$ gfortran -v Using built-in specs. COLLECT_GCC=gfortran COLLECT_LTO_WRAPPER=/usr/libexec/gcc/x86_64-linux-gnu/14/lto-wrapper OFFLOAD_TARGET_NAMES=nvptx-none:amdgcn-amdhsa OFFLOAD_TARGET_DEFAULT=1 Target: x86_64-linux-gnu Configured with: ../src/configure -v --with-pkgversion='Ubuntu 14-20240412-0ubuntu1' ... Thread model: posix Supported LTO compression algorithms: zlib zstd gcc version 14.0.1 20240412 (experimental) [master r14-9935-g67e1433a94f] (Ubuntu 14-20240412-0ubuntu1) ubuntu@e45200a49bf1:/home/laytonjb$ g++ -v Using built-in specs. COLLECT_GCC=g++ COLLECT_LTO_WRAPPER=/usr/libexec/gcc/x86_64-linux-gnu/14/lto-wrapper OFFLOAD_TARGET_NAMES=nvptx-none:amdgcn-amdhsa OFFLOAD_TARGET_DEFAULT=1 Target: x86_64-linux-gnu Configured with: ../src/configure -v --with-pkgversion='Ubuntu 14-20240412-0ubuntu1' ... Thread model: posix Supported LTO compression algorithms: zlib zstd gcc version 14.0.1 20240412 (experimental) [master r14-9935-g67e1433a94f] (Ubuntu 14-20240412-0ubuntu1)
dev3 – Adding Open MPI
The last step is to install Open MPI with an HPCCM building block that adds it to the Dockerfile (or Singularity spec file):
Stage0 += baseimage(image='ubuntu:24.04') Stage0 += apt_get(ospackages=['vim']) compiler = gnu(version='14') Stage0 += compiler Stage0 += openmpi(cuda=False, environment=True, ldconfig=True, infiniband=False, prefix='/usr/local/openmpi', version='4.0.3')
For this containment image, I went back to the starting Ubuntu base image. I could have easily started with the dev2 container image I had just built.
For Open MPI, I specified a few things, starting with the version (4.0.3, not the latest one); then, I specified that I did not want to build in CUDA (the test system doesn’t have a discrete GPU) or InfiniBand support (it’s only TCP in the home lab) and that I wanted to install Open MPI in /usr/local/openmpi. I also specified environment=True, which specifies that LD_LIBRARY_PATH and PATH should be modified to include Open MPI. This step allows you NOT to have to specify the fully qualified path to the binaries, libraries, and include files. Finally, I set ldconfig=True, which specifies that the Open MPI library directory should be added to the dynamic liner cache, which can help with compiling and is something I like to include.
Now I can create the Dockerfile from the HPCCM recipe:
$ hpccm --recipe dev3.py --format docker > Dockerfile
The resulting Dockerfile is shown in Listing 3. The obvious benefit of a very short HPCCM recipe file versus this much longer Dockerfile is obvious.
Listing 3: dev3 Dockerfile
FROM ubuntu:24.04 RUN apt-get update -y && \ DEBIAN_FRONTEND=noninteractive \ apt-get install -y --no-install-recommends vim && \ rm -rf /var/lib/apt/lists/* # GNU compiler RUN apt-get update -y && \ DEBIAN_FRONTEND=noninteractive \ apt-get install -y --no-install-recommends \ g++-14 \ gcc-14 \ gfortran-14 && \ rm -rf /var/lib/apt/lists/* RUN update-alternatives --install /usr/bin/g++ g++ $(which g++-14) 30 && \ update-alternatives --install /usr/bin/gcc gcc $(which gcc-14) 30 && \ update-alternatives --install /usr/bin/gcov gcov $(which gcov-14) 30 && \ update-alternatives --install /usr/bin/gfortran gfortran $(which gfortran-14) 30 # OpenMPI version 4.0.3 RUN apt-get update -y && \ DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \ bzip2 \ file \ hwloc \ libnuma-dev \ make \ openssh-client \ perl \ tar \ wget && \ rm -rf /var/lib/apt/lists/* RUN mkdir -p /var/tmp && wget -q -nc --no-check-certificate -P /var/tmp https://www.open-mpi.org/software/ompi/v4.0/dow nloads/openmpi-4.0.3.tar.bz2 && \ mkdir -p /var/tmp && tar -x -f /var/tmp/openmpi-4.0.3.tar.bz2 -C /var/tmp -j && \ cd /var/tmp/openmpi-4.0.3 && ./configure --prefix=/usr/local/openmpi --disable-getpwuid --enable-orterun-prefix-b y-default --without-cuda --without-verbs && \ make -j$(nproc) && \ make -j$(nproc) install && \ echo "/usr/local/openmpi/lib" >> /etc/ld.so.conf.d/hpccm.conf && ldconfig && \ rm -rf /var/tmp/openmpi-4.0.3 /var/tmp/openmpi-4.0.3.tar.bz2 ENV PATH=/usr/local/openmpi/bin:$PATH
Next, I built the container with the command:
$ docker build -f Dockerfile -t ubuntu-24.04-dev3 .
After the build finished, I checked the container images:
$ docker images REPOSITORY TAG IMAGE ID CREATED SIZE ubuntu-24.04-dev3 latest c6c30ca1386d 3 minutes ago 1.91GB ubuntu-24.04-dev2 latest 8f311b6fbb1e 17 hours ago 1.82GB ubuntu-24.04-dev1 latest 2358ab17d70c 17 hours ago 149MB
Interestingly, adding Open MPI didn’t add that much to the size of the container image. The proof is in the pudding, so time run the container:
$ docker run --rm -it \ -v /home/laytonjb:/home/laytonjb \ --user $(id -u):$(id -g) \ --workdir=/home/laytonjb ubuntu-24.04-dev3 /bin/bash
After starting the container, I then check on Open MPI:
Listing 4: Checking Open MPI
ubuntu@4255aefc4a94:/home/laytonjb$ which mpirun /usr/local/openmpi/bin/mpirun ubuntu@4255aefc4a94:/home/laytonjb$ mpicc -v Using built-in specs. COLLECT_GCC=/usr/bin/gcc COLLECT_LTO_WRAPPER=/usr/libexec/gcc/x86_64-linux-gnu/14/lto-wrapper OFFLOAD_TARGET_NAMES=nvptx-none:amdgcn-amdhsa OFFLOAD_TARGET_DEFAULT=1 Target: x86_64-linux-gnu Configured with: ../src/configure -v --with-pkgversion='Ubuntu 14-20240412-0ubuntu1' ... Thread model: posix Supported LTO compression algorithms: zlib zstd gcc version 14.0.1 20240412 (experimental) [master r14-9935-g67e1433a94f] (Ubuntu 14-20240412-0ubuntu1)
Everything looks good: mpirun is there and mpicc points to gcc-14.0.1 (the host system is Ubuntu 22.04, for which gcc-14 does not exist, so you know it is pointing to the correct gcc).
Podman – dev1
I wanted to gain some more Podman experience after my last article, so I tried building a container image with Podman to match the ones I built with Docker. I started the experiments with dev1, which is just the base image with Vi. You’ll find that most of the Podman commands are almost identical to Docker.
For the Podman experiments, I used the exact same Dockerfiles I used for the Docker container images. I made no changes – and I shouldn’t have to according to the Podman documentation I've read so far.
The first step is to build the Podman container image from the dev1 Dockerfile:
$ podman build -f Dockerfile -t ubuntu-24.04-dev1 .
Note that the Podman container images are different from the Docker container images, so they will not conflict. The list of Podman images is:
$ podman images REPOSITORY TAG IMAGE ID CREATED SIZE localhost/ubuntu-24.04-dev1 latest 0797eec2258f 55 seconds ago 154 MB
Next, I run the container and check the OS release (Listing 5). Looks good to me! +1 for Podman.
Listing 5: Checking the OS Release
$ podman run --rm -it -v /home/laytonjb:/home/laytonjb \ --user $(id -u):$(id -g) \ --workdir=/home/laytonjb ubuntu-24.04-dev1 /bin/bash ubuntu@fa9e0b5b0895:/home/laytonjb$ cat /etc/os-release PRETTY_NAME="Ubuntu 24.04 LTS" NAME="Ubuntu" VERSION_ID="24.04" VERSION="24.04 LTS (Noble Numbat)" VERSION_CODENAME=noble ID=ubuntu ID_LIKE=debian HOME_URL="https://www.ubuntu.com/" SUPPORT_URL="https://help.ubuntu.com/" BUG_REPORT_URL="https://bugs.launchpad.net/ubuntu/" PRIVACY_POLICY_URL="https://www.ubuntu.com/legal/terms-and-policies/privacy-policy" UBUNTU_CODENAME=noble LOGO=ubuntu-logo
Podman – dev2
Next, I’ll build the dev2 container image that has the added compilers:
$ podman build -f Dockerfile -t ubuntu-24.04-dev2 .
Note that this command looks exactly like the Docker command. The Podman container image list is now:
$ podman images REPOSITORY TAG IMAGE ID CREATED SIZE localhost/ubuntu-24.04-dev2 latest 3604d85bbd50 About a minute ago 1.83 GB localhost/ubuntu-24.04-dev1 latest 0797eec2258f 8 minutes ago 154 MB
Running the container and checking the compilers produces the same output as for the Docker container. I have not included it here to reduce the length of the article. I built this container image exactly like the Docker container image with the dev1 starting image.
Podman -- dev3
The dev3 container image added Open MPI. I used the exact same Dockerfile as the Docker container image, but this time, Podman failed to build the container. I kept getting errors about not being able to change permissions on files when untarring the openmpi TAR file. My Google searching did not point to anything solid, but it may have something to do with SELinux. My first wart with Podman.
Summary
In this article I showed you simple ways to use HPCCM to build a development container image. The HPCCM recipes are simple but create powerful container spec files. The HPCCM recipe is just Python, which allows you to use Python for other code and use Python tools in your recipe.
Docker had no trouble with the Docker spec files. (I didn’t test Singularity or Apptainer in this article in the interest of length.) Podman worked just fine on the first two examples but couldn’t handle the last attempt when the MPI library was added.
If you read through the HPCCM documentation, you will see other really cool things you can do with HPCCM. For example, you can add multiarchitecture support in a recipe. You can use code version tagging for better reproducibility by using a specific commit or tags in GitHub. I also learned a bit more about the generic_build building block. It looks very powerful for building applications in your container image.
If you have not heard of HPCCM, give it a try. I have been using it for a few years and have found it very useful.