Sections

 

Building From Docker or Singularity Hub

    1. There are two dedicated nodes for building containers on the SCC. They are scc-i01 and scc-i02. Login to either node with ssh. 
      [rcs@scc1 ~] ssh scc-i01
    2. Run the following commands to create a directory on the local /scratch drive for building the container. This significantly reduces the time it takes for the build: 
      [rcs@scc-i01 ~] mkdir $TMPDIR/$USER
[rcs@scc-i01 ~] SING_DIR=$TMPDIR/$USER
    3. Fetch the container pull command from Docker Hub (shown below), Singularity Hub, or other registry. 
      [rcs@scc-i01 ~] singularity pull $SING_DIR/CONTAINER_NAME.sif docker://PATH/TO/DOCKER/CONTAINER
    4. Move the newly built container to your /projectnb space. 
      [rcs@scc-i01 ~] mv $SING_DIR/CONTAINER_NAME.sif /projectnb/PROJECT_NAME
    5. Delete the build directory when finished. 
      [rcs@scc-i01 ~] rm -rf $SING_DIR
    6. Exit the build node. 
      [rcs@scc-i01 ~] exit
[rcs@scc1 ~]

 

Building From Scratch

To build from a definitions (def) file on the SCC, you will need to do so from one of the dedicated build nodes to obtain --fakeroot privileges.

  1. Login to either build node (scc-i01 or scc-i02) with ssh. 
    [rcs@scc1 ~] ssh scc-i01
  2. Change to the build node /scratch space and create a directory to build the container locally. The $USER variable just substitutes your username automatically. 
    [rcs@scc-i01 ~] mkdir $TMPDIR/$USER
[rcs@scc-i01 ~] SING_DIR=$TMPDIR/$USER
[rcs@scc-i01 ~] cd $SING_DIR
  3. Build the container from the def file. 
    [rcs@scc-i01 $USER] singularity build --fakeroot CONTAINER_NAME.sif CONTAINER_NAME.def
  4. Move the newly built container to your /projectnb (or /rprojectnb) space. 
    [rcs@scc-i01 ~] mv $SING_DIR/CONTAINER_NAME.sif /projectnb/PROJECT_NAME
  5. Delete the build directory when finished. 
    [rcs@scc-i01 ~]  cd
[rcs@scc-i01 ~] rm -rf $SING_DIR
  6. Exit the build node. 
    [rcs@scc-i01 ~] exit
[rcs@scc1 ~]

To see full instructions on designing a def file see Sylab’s documentation.

Common Problems

The most common problem when building a container from a .def file is an error stating there is “no space left on device.” The usual cause of this, assuming you are building the container on the /scratchdrive as recommended, is that the /tmp filesystem has been filled. Singularity by default maps in the system /tmp filesystem into the build process for temporary files, but that has a small (~2 GB) capacity. To work around this, add the following to your .def file before the %post section:

%setup
    mkdir ${SINGULARITY_ROOTFS}/scratch

Next, create a directory for temporary files on /scratch, and use an environment variable to tell singularity to use that instead of /tmp. When running the build command use the -B /scratch flag to map that directory inside the container:

[rcs@scc-i01 ~] mkdir -p /scratch/$USER/sing_tmpdir
[rcs@scc-i01 ~] export SINGULARITYENV_TMPDIR=/scratch/$USER/sing_tmpdir
[rcs@scc-i01 ~] export SINGULARITY_TMPDIR=/scratch/$USER/sing_tmpdir
[rcs@scc-i01 ~] singularity build --fakeroot -B /scratch CONTAINER_NAME.sif CONTAINER_NAME.def

Modifying Containers

To modify your container, you will need to unpack the read-only image into a the writable sandbox. It is important that this is done on one of the dedicated build nodes to obtain --fakeroot privileges.

  1. Login to either build node (scc-i01 or scc-i02) with ssh. 
    [rcs@scc1 ~] ssh scc-i01
  2. Change to the build node /scratch space and create a directory to unpack the container locally. 
    [rcs@scc-i01 ~] mkdir $TMPDIR/$USER
[rcs@scc-i01 ~] SING_DIR=$TMPDIR/$USER
[rcs@scc-i01 ~] cd $SING_DIR
  3. Unpack the container into a writable sandbox. Don’t use the --fakeroot while unpacking. 
    [rcs@scc-i01 $USER] singularity build --sandbox CONTAINER_NAME_SANDBOX CONTAINER_NAME.sif
  4. Run the sandbox to make changes. 
    [rcs@scc-i01 $USER] singularity shell --fakeroot --writable CONTAINER_NAME_SANDBOX
Singularity>
  5. When done modifying, pack the sandbox back into a read-only container. 
    [rcs@scc-i01 $USER] singularity build --fakeroot MODIFIED_CONTAINER_NAME.sif CONTAINER_NAME_SANDBOX
  6. Move the modified read-only container back to your project space and delete the directory used. 
    [rcs@scc-i01 $USER] mv MODIFIED_CONTAINER_NAME.sif /projectnb/YOUR_PROJECT
[rcs@scc-i01 $USER]  cd
[rcs@scc-i01 ~] rm -rf $SING_DIR
[rcs@scc-i01 ~] exit
[rcs@scc1 ~]

See more on building Singularity sandbox containers in the Sylabs documentation.