Foundational skills: Bash shell and Apptainer crash course

The Unix shell

If you need a refresher on the basics of the Unix shell, there are already great resources available, please see one of:

• “The Shell” at Linux Journey
• “Terminal basics” at sandbox.bio
• Introduction to Unix (at Andrew Robinson / LaTrobe University)

Apptainer

For an in-depth workshop, see Reproducible computational environments using containers: Introduction to Apptainer.

Here’s a crash course.

Setting your cache path - this is where Apptainer will download container images to:

export APPTAINER_CACHEDIR=$HOME/.apptainer/apptainer_cache

# Side note: Nextflow can use its own environment variable for the Apptainer cache
# export NXF_APPTAINER_CACHEDIR=$APPTAINER_CACHEDIR

Downloading a container image:

apptainer pull docker://ghcr.io/australian-protein-design-initiative/containers/bindcraft:05702c4_nv-cuda12

Downloading a container image to a (large) file anywhere:

apptainer pull bindcraft.sif docker://ghcr.io/australian-protein-design-initiative/containers/bindcraft:05702c4_nv-cuda12

… this will create a self-contained file called bindcraft.sif in your current directory. You can run things inside the container like:

apptainer exec bindcraft.sif python --version

We will continue to use the image in APPTAINER_CACHEDIR, instead: rm bindcraft.sif

---

Starting a shell session ‘inside’ a container:

apptainer shell docker://ghcr.io/australian-protein-design-initiative/containers/bindcraft:05702c4_nv-cuda12

This is useful for ‘exploring’ what’s inside the container. For example, while ‘inside’ the BindCraft container, try:

cd /app/BindCraft
ls settings_advanced/

Type exit or press Ctrl-D to return to your regular shell.

---

Rather than writing the image URL every time, docker://ghcr.io/australian-protein-design-initiative/containers/bindcraft:05702c4_nv-cuda12 every time, let’s set it as a shell variable - this makes the commands below easier to read:

export BINDCRAFT_IMAGE="docker://ghcr.io/australian-protein-design-initiative/containers/bindcraft:05702c4_nv-cuda12"

Running a command in a container:

apptainer exec $BINDCRAFT_IMAGE python --version

Mounting (‘binding’) a directory so it’s visible inside a container - eg -B ~/my_data:

apptainer exec -B ~/my_data $BINDCRAFT_IMAGE ls ~/my_data

Mounting (‘binding’) a directory at a different path inside a container - eg -B ~/my_data:/data:

apptainer exec -B ~/my_data:/data $BINDCRAFT_IMAGE ls ~/my_data

Try to pretend there is no container:

# Add this to your .bashrc or .zshrc to make it permanent
alias bindcraft='apptainer exec $BINDCRAFT_IMAGE'

bindcraft --help