BioHPC Cloud:
: User Guide

By default, only your home directory is bound inside container. If you need to access your data files under /workdir/$USER,  you can run the following command to bind. 

export APPTAINER_BINDPATH=/workdir/$USER

Examples

1. To run software in a Singularity container (including converting a Docker image to a Singularity image)

#Import a Docker image from Docker/Singularity hub.
singularity pull lolcow.sif library://godlovedc/funny/lolcow
singularity pull myUbuntu.sif docker://biohpc/ubuntudev

#Alternatively, a singularity image can be built from a local docker image file
singularity build myUbuntu.sif docker-archive://ubuntudev.tar

#Start singularity shell from an image file
singularity shell myUbuntu.sif

#Run software within singlarity container
singularity exec myUbuntu.sif python -V

#Using pipe with singularity container, 
echo "aaa" | singularity exec myUbuntu.sif sed "s/a/b/"

#Execute a built-in runscript of an image file
./lolcow.sif

• Singularity containers inherit all the host environmental variable except $PATH and $LD_LIBRARY_PATH (watch out for $PYTHONPATH). Use "singularity shell -e" if you do not want to inherit any host environmental variables;
• Within container, current directory and $HOME are mounted by default. Use --bind source(:destination) to mount other directories. Within container, you have the same user id. Use "exit" command to exit.
• Local docker image file should be created by "docker1 save MyDockerImage -o MyDockerImage.tar", not by "docker1 export Container". Make sure to run "docker1 claim" to change the ownership of the tar file from root to you. 
• Xwindows and ports all work the same way as host shell.

2. Build a singularity image

## A non-root user can build singularity images using --fakeroot option. On BioHPC servers, you need to run this command to acquire privilege to use --fakeroot option. You only need to run this command once on the same server. 

# a simple scenario: building a image from a def file

A example def file:

BootStrap: library
From: ubuntu:focal

%environment

%files

%post
    apt -y update
    apt -y upgrade
    apt-get -y install software-properties-common build-essential cmake wget nano
    add-apt-repository universe
    apt -y update

# build a sandbox and create a "writable" shell. The sand box helps you to test the installation commands to put into the .def file

singularity build --fakeroot --sandbox myUbuntu myUbuntu.def
singularity shell --fakeroot --writable myUbuntu
## install all needed modules in the sandbox. after your are done
singularity build --fakeroot myUbuntu.sif myUbuntu

#after you finalized the .def, file, use this command to build a .sif image file from from .def file. The .sif file is the file can be used for distributing and running software 

singularity build --fakeroot myUbuntu.sif myUbuntu.def

#Alternative to fakeroot,  you can using "--remote" option to build an image file through  a free cloud instance.  However, you cannot do sandbox with remote build. Before you do first remote build, you need to register a free account at https://cloud.sylabs.io/builder, get a token, and run  "singularity login" command once

singularity build --remote myUbuntu.sif myUbuntu.def

3. installing software to an exsing image (.sif) and save to a new sif file,  e.g. install curl

# I do not know why, save a sandbox to a sif file could take a very long time, and does not always work.

# I assume that the main purpose of sandbox is for testing, not for building. A more reliable way to modify an exisitng sif file to create a def file from the sif, as showing in the example below: 

create a def file mynew.def, starting from an existing sif file:

Bootstrap: localimage
From: pcl.sif

%post
    apt -y install curl

#create a new .sif file from the def