diff --git a/definition-files/MPI/Singularity.ubuntu-18.04-OMPI-gcc b/definition-files/MPI/Singularity.ubuntu-18.04-OMPI-gcc index fbc78fc07958c4ade628e271ff6edd2062467952..d9dadb34d526cb2d0e5c5a375aa8cb41243a7311 100644 --- a/definition-files/MPI/Singularity.ubuntu-18.04-OMPI-gcc +++ b/definition-files/MPI/Singularity.ubuntu-18.04-OMPI-gcc @@ -2,7 +2,7 @@ Bootstrap: library From: mblaschek/imgw/ubuntu:18.04 %files - mpitest.c /opt + definition-files/MPI/mpitest.c /opt %environment export OMPI_DIR=/opt/ompi diff --git a/workshop/MPI/mpitest.c b/definition-files/MPI/mpitest.c similarity index 100% rename from workshop/MPI/mpitest.c rename to definition-files/MPI/mpitest.c diff --git a/workshop/HandsOn.md b/workshop/HandsOn.md index 1b9c358baa9f9ad0cc2fb66f403cdf72e670f8a1..59c6b4378a1640ba761e45ca378bc3f94ec8a948 100644 --- a/workshop/HandsOn.md +++ b/workshop/HandsOn.md @@ -5,6 +5,9 @@ In order to build a singularity container you require a **root** environment, su - Virtual Machine (all OS) - VMWare, KVM, VirtualBox - install a recent Linux and install singularity - Build Service - [Sylab Cloud](https://cloud.sylabs.io/home) - advanced +[__TOC__] + + ## IMGW Resources Singularity is installed on all IMGW servers and on VSC4 via module (`module load singularity`). Most other HPC environments have a version installed as well. @@ -20,8 +23,9 @@ and there are example **definition-files** that help to build containers by them We are using a VM to build our containers with root privileges. Steps: -- ssh to **jet01** -- ssh using **rocky##@192.168.122.230** +- Connect to JET: `ssh user@jet01.img.univie.ac.at` +- Connect to the VM: `ssh rocky##@192.168.122.230` +- clone this repo into your VMs HOME directory: `git clone https://gitlab.phaidra.org/imgw/singularity.git` Please note that you will recieve the username and the password in the course. @@ -37,24 +41,34 @@ has three essential subcommands: - **build**: Build your own container from scratch using a Singularity definition file; download and assemble any existing Singularity container; or convert your containers from one format to another (e.g., from Docker to Singularity). - **shell**: Spawn an interactive shell session in your container. - **exec**: Execute an arbitrary command within your container. +- **run**: Execute the runscript ### Definition File -Typically a Singularity Recipe or Definition files is made of: -- Bootstrap - start source -- Files - Files to copy into the container -- Post - install instructions -- Labels - Information for the User -- Environment - Runtime environment variables -- Run - Runtime instructions, script, executable -- Apps - Special executables defined as apps -- Setup - -- Test - Tests to check if the container runs optimal - +Typically a Singularity Recipe or Definition files is made of different [sections](https://sylabs.io/guides/3.3/user-guide/definition_files.html#sections): +- *Bootstrap* - start source +- *Files* - Files to copy into the container +- *Post* - install instructions +- *Labels* - Information for the User +- *Environment* - Runtime environment variables +- *Help* - Runtime help information +- *Run* - Runtime instructions, script, executable +- *Apps* - Special executables defined as apps +- *Setup* - DO not use. +- *Test* - Tests to check if the container runs optimal + +Please note that the *Bootstrap* can be changed for example, if you build the ubuntu container already, e.g. ubuntu.sif, then downloading that container image again might be not efficient. Therefore, replacing the Bootstrap is a nice option. +```bash +#Bootstrap: library +#From: mblaschek/imgw/ubuntu:18.04 +Bootstrap: localimage +From: ubuntu.sif +``` +Please have a look at the other options - [Other bootstrap agents @ sylab](https://sylabs.io/guides/3.3/user-guide/definition_files.html#other-bootstrap-agents) -e.g. [miniconda3](../definition-files/miniconda/Singularity.miniconda3-py39-4.9.2-ubuntu-18.04) +Let's take for example the [miniconda3](../definition-files/miniconda/Singularity.miniconda3-py39-4.9.2-ubuntu-18.04) Recipe and investigate what it does. -```singularity +```bash Bootstrap: library From: mblaschek/imgw/ubuntu:18.04 @@ -142,10 +156,131 @@ From: mblaschek/imgw/ubuntu:18.04 %test ``` +### Examples + +#### COW? +One of the most common examples to show how to create a singularity container is the lolcow: +```bash +# Using Sylab library +sudo singularity build lolcow.sif library://sylabs-jms/testing/lolcow +# Using Docker +sudo singularity build lolcow.sif docker://godlovedc/lolcow +``` +And then run it: +```bash +# Invoke the buildin runscript: +singularity run lolcow.sif +# using execute +singularity exec lolcow.sif sh -c "fortune | cowsay | lolcat" + ______________________________________ +/ Don't tell any big lies today. Small \ +\ ones can be just as effective. / + -------------------------------------- + \ ^__^ + \ (oo)\_______ + (__)\ )\/\ + ||----w | + || || +``` +As you can see it can be useful to have a runscript. Please have a look at the runscript: +```bash +Bootstrap: docker +From: ubuntu:16.04 + +%post + apt-get -y update + apt-get -y install fortune cowsay lolcat + +%environment + export LC_ALL=C + export PATH=/usr/games:$PATH + +%runscript + fortune | cowsay | lolcat +``` +But what if I do not know what the runscript is anymore? +```bash +# Try Help ? +singularity run-help lolcow.sif +No help sections were defined for this image +# Look inside: +singularity shell lolcow.sif +Singularity> cat /.singularity.d/runscript +#!/bin/sh +OCI_ENTRYPOINT='"/bin/sh" "-c" "fortune | cowsay | lolcat"' +OCI_CMD='' +# ENTRYPOINT only - run entrypoint plus args +if [ -z "$OCI_CMD" ] && [ -n "$OCI_ENTRYPOINT" ]; then + SINGULARITY_OCI_RUN="${OCI_ENTRYPOINT} $@" +fi +... +``` +Of course everything needs to be **in** the container. + + +#### Miniconda + +Let's build something that might actually be useful. +1. We are going to build the default *miniconda3* example from the *definition-files* +2. Then we are going to add some python packages that you might want to use and see if they are installed inside. + +```bash +# Build the default image +sudo singularity build miniconda3.sif definition-files/miniconda/Singularity.miniconda3-py39-4.9.2-ubuntu-18.04 +# Check that it can run: +singularity exec miniconda3.sif python3 --version +Python 3.9.1 +``` +Now please open the definition file using e.g. +```bash +# change to the git repository (clone with cmd above) +cd $HOME/singularity +# Copy +cp definition-files/miniconda/Singularity.miniconda3-py39-4.9.2-ubuntu-18.04 definition-files/miniconda/Singularity.miniconda3-py39-4.9.2-ubuntu-18.04-custom +# Edit +vim definition-files/miniconda/Singularity.miniconda3-py39-4.9.2-ubuntu-18.04-custom +# Build again +sudo singularity build miniconda3-custom.sif definition-files/miniconda/Singularity.miniconda3-py39-4.9.2-ubuntu-18.04-custom +# Test +singularity exec miniconda3-custom.sif python3 +``` + +#### MPI Example (Advanced) +Please only try to do this when you have time. Usually the building of OpenMPI takes some time, e.g. 5 min (VM). +There are three examples: +- Using Centos 8 and Intel MPI (untested) +- Using Ubuntu 18.04 and OpenMPI @ 4.0.5 +- Using Rocky Linux 8.4 and OpenMPI @ git + +##### Using Ubuntu +```bash +# Building +sudo singularity build ubuntu-OMPI.sif definition-files/MPI/Singularity.ubuntu-18.04-OMPI-gcc +# load the MPI from the VM or JET +module load mpi/openmpi-x86_64 +# Running using 4 Cores +mpirun -np 4 singularity exec ubuntu-OMPI.sif /opt/mpitest +module purge +``` + +##### Using Rocky +```bash +# Building +sudo singularity build rocky-OMPI.sif definition-files/rocky/Singularity.rocky-8.4-OMPI +# load the MPI from the VM or JET +module load mpi/openmpi-x86_64 +# Running using 4 Cores +mpirun -np 4 singularity exec rocky.sif /usr/bin/mpi_ring +module purge +``` +[Sylab MPI Documentation](https://sylabs.io/guides/3.3/user-guide/mpi.html) + + ### Singularity Variables +#### Cache, TMP +On Servers you might be limited (file size, quota, ...) by the definition of your `SINGULARITY_CACHEDIR` (`singularity cache clean`) or your `SINGULARITY_TMPDIR` directory. -`SINGULARITY_CACHEDIR` `SINGULARITY_TMPDIR` Limited space in home directories. Set to `$TMPDIR` to avoid quota limits. @@ -155,3 +290,13 @@ export SINGULARITY_CACHEDIR=$TMPDIR export SINGULARITY_TMPDIR=$TMPDIR ``` +#### Bind +In order to include host paths into your container use the `SINGULARITY_BIND` variable defined in the host system or provide the runtime command the option `-b paths` or `--bind paths` + +e.g. +```bash +# Binding /data on host to /mnt inside +singularity exec --bind /data:/mnt my_container.sif ls /mnt +``` + +