Containers

If you want to install any special software (a newer version of R, libraries for spatial or bioinformatic data analysis, etc.), the best way to do this is through containers. Containers sound complicated but they’re actually fairly straightforward to use.

The container software used by the Argon system is called Apptainer (formerly Singularity), and this page will tell you how to use it.

IMPORTANT: Pulling and building containers is computer intensive, so log in to a compute node before running apptainer pull or apptainer build:

qlogin -q BIOSTAT -pe smp 1

Downloading a pre-built container

Docker is the most popular containerization software, but doesn’t integrate with HPC systems well. Thankfully, converting between Docker and Apptainer is simple, which means you can use pre-built Docker containers on the HPC. There are lots of pre-built containers; you can browse through them at Docker Hub. For example, if you just want the latest version of R:

apptainer pull docker://rocker/r-ver

If you want a specific version of R:

apptainer pull docker://rocker/r-ver:4.5.0

If you want one that comes with all the tidyverse packages installed:

apptainer pull docker://rocker/tidyverse

If you want one that comes with Bioconductor:

apptainer pull docker://bioconductor/r-ver

And so on.

This will create a (pretty big!) file called something like r-ver_latest.sif (depending on which container you pulled). This is known as an image file, and contains a miniature operating system with the latest version of R installed (plus any extras, as requested).

Running a program inside the container

Once you have the image you want, you can start an interactive session inside the container with:

apptainer shell r-ver_latest.sif

This is useful for debugging, as you can see what it looks like inside the container, open R, see what packages are available, etc. Once you’re done poking around inside the shell, either press ctrl+d or type exit.

When it’s time to run a script through the container:

apptainer exec r-ver_latest.sif Rscript sim.R

Note that everything after apptainer exec <image> is just an ordinary terminal command. We could (and did) run Rscript sim.R directly from the command line. The difference here is that the script is running inside the container, which means it has access to all the software installed there. You can tell because it will print the R version as something like 4.6.1, which matches the container, not the module.

Submitting container jobs over the cluster

You can probably tell where this is going, but:

qsub -cwd -j y -q BIOSTAT -t 1-10 -b y apptainer exec r-ver_latest.sif Rscript sim.R

The pattern remains the same as before: the command you wish to submit over the cluster goes at the end. Now this command means that we’ve submitted 10 jobs to run on 10 different nodes, each one opening a separate container to run our simulation.

If you look at the one of the log files (e.g., apptainer.o6279783.5), you’ll see that the R version matches that of the container, not the module.

Customizing your container

If your container needs additional software, the basic format to define a container is this:

Bootstrap: docker
From: rocker/r-ver:latest

%post
    # System dependencies
    apt-get update && apt-get install -y \
        curl \
        git \
        libcurl4-openssl-dev \
        libgit2-dev \
        libssl-dev \
        libuv1-dev \
        libxml2-dev \
        pkg-config

    # R packages
    Rscript -e 'install.packages(c(
        "data.table",
        "ggplot2",
        "R.utils"
        ), repos = "https://cloud.r-project.org"
    )'

    # Python packages
    python3 -m venv /opt/venv
    /opt/venv/bin/pip install docopt
    /opt/venv/bin/pip install snakemake

%environment
    export PATH=/opt/venv/bin:$PATH

Add or subtract from these system/R/Python packages as needed, then build the image with

apptainer build my-container.sif my-container.def

This can be done anywhere: if you prefer, you can build the container on a different machine and copy it over to the hpc — containers are designed to be portable. If you do build it on Argon, be sure to use a compute node (see warning at top of page).

Note: You are unlikely to ever use libcurl4-openssl-dev directly, but I recommend including the above system dependencies because a large number of R packages depend on them and you’ll encounter installation problems without them.

For more information and examples, see the files in this repository.