Skip to content
Snippets Groups Projects
Commit f2c13502 authored by John-Paul Robinson's avatar John-Paul Robinson
Browse files

Update singularity_container.ipynb 

Correct some typos
Reduce wording in first example around neurodebian container description.
Try to improve some of the descriptions around running singularity as a command in a batch script.
parent 1990a407
Branches patch-1
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
singularity_container.ipynb
+ 8
− 10
View file @ f2c13502
%% Cell type:markdown id: tags:
# SIngularity Containers
%% Cell type:markdown id: tags:
## First container
Let's begin by pulling our first container from [Singularity-Hub](https://singularity-hub.org/).
This singularity image contains the tool [neurodebian](http://neuro.debian.net/).
NeuroDebian provides a large collection of popular neuroscience research software for the Debian operating system as well as Ubuntu and other derivatives.
The [neurodebian](http://neuro.debian.net/) singularity image contains a large collection of popular neuroscience research software for the Debian operating system as well as Ubuntu and other derivatives.
%% Cell type:code id: tags:
``` python
!singularity pull shub://neurodebian/neurodebian
```
%% Cell type:markdown id: tags:
Now that we have pulled the image you should be able to see that image in your directory by simply running a 'ls' command
%% Cell type:code id: tags:
``` python
!ls
```
%% Cell type:markdown id: tags:
Now, we'll try to execute a command from within the container.
__exec__ parameter allows you to achieve this functionality. Let's list the content of you /home/$USER directory
__exec__ parameter allows you to achieve this functionality. Let's list the content of your /home/$USER directory
%% Cell type:code id: tags:
``` python
!singularity exec neurodebian-neurodebian-master-latest.simg ls /home/$USER
```
%% Cell type:markdown id: tags:
Now, that we have the container pulled, we can use it for running the actual tool that we wanted to use, the reason for actually downloading the container in the first place: [dcm2nii](https://www.nitrc.org/projects/mricron)
Now that we have the container pulled onto the cluster, we can use it for running an actual neuro-imaging tool that we wanted to use: [dcm2nii](https://www.nitrc.org/projects/mricron)
%% Cell type:code id: tags:
``` python
!singularity exec -B /data neurodebian-neurodebian-master-latest.simg dcm2nii
```
%% Cell type:markdown id: tags:
## What is a container?
%% Cell type:markdown id: tags:
A container is a standard unit of software that packages up code and all its dependencies so the application runs quickly and reliably from one computing environment to another. A container image is a lightweight, standalone, executable package of software that includes everything needed to run an application: code, runtime, system tools, system libraries and settings.
Containers use the host system's kernel, and can access its hardware more directly. When you run a process in a container it runs on the host system, directly visible as a process on that system. Unlike a Virtual Machine, container is a virtualization at the software level, whereas VMs are virtualization at hardware level. If you are interested in finding out more differences between VM and a container, go to this [link](https://www.electronicdesign.com/dev-tools/what-s-difference-between-containers-and-virtual-machines)
%% Cell type:markdown id: tags:
## Why use a container?
Containers package together a program and all of its dependencies, so that if you have the container you can use it on any Linux system with the container system software installed. It doesn't matter whether the system runs Ubuntu, RedHat or CentOS Linux - if the container system is available then the program runs identically on each, inside its container. This is great for distributing complex software with a lot of dependencies, and ensuring you can reproduce experiments exactly. If you still have the container you know you can reproduce your work. Also since the container runs as a process on the host machine, it can be run very easily in a [SLURM job](https://docs.uabgrid.uab.edu/wiki/Slurm)
%% Cell type:markdown id: tags:
## Docker vs Singularity?
[Docker](https://www.docker.com/) is the most popular and widely used container system in the industry. But [Singularity](https://www.sylabs.io/singularity/) was built keeping HPC in mind, i.e a shared environment. Singularity is designed so that you can use it within SLURM jobs and it does not violate security constraints on the cluster. Though, since Docker is very popular and a lot of people were already using the Docker for their softwares, Singularity maintained a compatibility for Docker images. We'll be seeing this compatibility later in the notebook. Both Singularity and Docker maintain a hub where you can keep your docker remotely, and pull them from anywhere. Here is a link for both the hubs:
[Singularity-Hub](https://singularity-hub.org)
[Docker Hub](https://hub.docker.com/)
Singularity is already available on Cheaha. To check the available modules for Cheaha, run the cell below:
%% Cell type:code id: tags:
``` python
!module avail Singularity
```
%% Cell type:markdown id: tags:
As you might have already noticed that we already loaded a Singularity module while starting up this notebook. You can check the version of the Singularity loaded below:
%% Cell type:code id: tags:
``` python
!singularity --version
```
%% Cell type:markdown id: tags:
## Basic singularity command line functions:
To check the basic functions or command line options provided run help on the singularity
%% Cell type:code id: tags:
``` python
!singularity --help
```
%% Cell type:markdown id: tags:
To check more information about a particular parameter, use help in conjunction with that parameter
%% Cell type:code id: tags:
``` python
!singularity pull help
```
%% Cell type:markdown id: tags:
## Namespace resolution within the container:
%% Cell type:markdown id: tags:
Now, let's list the content of your /data/user/$USER directory by running it from within the container. We'll use __exec__ parameter for this.
%% Cell type:code id: tags:
``` python
!singularity exec neurodebian-neurodebian-master-latest.simg ls /data/user/$USER
```
%% Cell type:markdown id: tags:
Hmmm, an error. Remember your singularity container image doesn't know about the directories on your host machine. It by default (in most containers) binds your HOME and tmp directory.
Now, all our raw data is generally in our /data/user/$USER locations, so we really need to access that location if our container has to be useful.
Thankfully, you can explicitly tell singularity to bind a host directory to your container image. Singularity provides you with a parameter (-B) to bind path from your host machine to the container. Try the same command again, but with the bind parameter
%% Cell type:code id: tags:
``` python
!singularity exec -B /data/user/$USER neurodebian-neurodebian-master-latest.simg ls /data/user/$USER
```
%% Cell type:markdown id: tags:
Now like mentioned earlier during the security considerations of Singularity in a HPC environment, all the sigularity runs adhere to the user level permissions, from the host system. So I would get a permission denied issue if I try to list William's directory content.
Now like mentioned earlier during the security considerations of Singularity in a HPC environment, all the sigularity runs adhere to the user level permissions, from the host system. So I would get a permission denied error if I try to list directories to which I don't have access. In this example William's directory contents.
%% Cell type:code id: tags:
``` python
!singularity exec -B /data/user/wsmonroe neurodebian-neurodebian-master-latest.simg ls /data/user/wsmonroe
```
%% Cell type:markdown id: tags:
Now that we know how to bind paths from the host machine to the container image, I would be able to use __dcm2nii__ tool with my raw files available in my DATA_USER location.
Now that we know how to bind paths from the host machine to the container image, we will be able to use __dcm2nii__ tool with our raw files available in our DATA_USER location.
We'll take a look at how to use it within a job script in the next section.
%% Cell type:markdown id: tags:
## Job Script with containers
Using Singularity container with [SLURM job script](https://docs.uabgrid.uab.edu/wiki/Slurm) is very easy, as the containers run as a process on the host machine. You just need to load Singularity in your job script and run the singularity process. Here's an example job script below:
Using Singularity container with [SLURM job script](https://docs.uabgrid.uab.edu/wiki/Slurm) is very easy, as the containers run as a process on the host machine, just like any other command in a batch script. You just need to load Singularity in your job script and run the command via a singularity process. Here's an example job script below:
%% Cell type:markdown id: tags:
```
#!/bin/bash
#
#SBATCH --job-name=test
#SBATCH --job-name=test-singularity
#SBATCH --output=res.out
#SBATCH --error=res.err
#
# Number of tasks needed for this job. Generally, used with MPI jobs
#SBATCH --ntasks=1
#SBATCH --partition=express
#
# Time format = HH:MM:SS, DD-HH:MM:SS
#SBATCH --time=10:00
#
# Number of CPUs allocated to each task.
#SBATCH --cpus-per-task=1
#
# Mimimum memory required per allocated CPU in MegaBytes.
#SBATCH --mem-per-cpu=100
#
# Send mail to the email address when the job fails
#SBATCH --mail-type=FAIL
#SBATCH --mail-user=$USER@uab.edu
#Set your environment here
module load Singularity/2.5.2-GCC-5.4.0-2.26
#Run your commands here
#Run your singularity or any other commands here
singularity exec -B /data/user/$USER /data/user/$USER/rc-training-sessions/neurodebian-neurodebian-master-latest.simg dcm2nii PATH_TO_YOUR_DICOM_FILES
```
%% Cell type:markdown id: tags:
## Pulling a Docker Image
In this example we are going to be pulling a singularity image from [dockerhub](https://hub.docker.com/). This singularity image contains [google-cloud-sdk tools](https://cloud.google.com/sdk/).
The Cloud SDK is a set of tools for Cloud Platform. It contains gcloud, gsutil, and bq command-line tools, which you can use to access Google Compute Engine, Google Cloud Storage, Google BigQuery, and other products and services from the command-line. You can run these tools interactively or in your automated scripts.
%% Cell type:code id: tags:
``` python
!singularity pull docker://jess/gcloud
```
%% Cell type:code id: tags:
``` python
!singularity exec -B /data/user/$USER gcloud.simg gsutil
```
%% Cell type:markdown id: tags:
## Clean your directory:
%% Cell type:markdown id: tags:
To clean your directory of all the container images, you can run the command below
%% Cell type:code id: tags:
``` python
!rm *.simg
```
%% Cell type:markdown id: tags:
## Building a Singularity container recipe file
Though building a recipe file for Singularity containers is beyond the scope of this session, we have provided a few important links below which would tell you how to create a recipe file for Singularity containers as well as build the container using them.
When you want to create a container for production use on the cluster, you should build a container image from a definition file. Unfortunately, building containers from a definition file requires you to be a system administrator (root) on the machine you use for building. You will need to build Singularity containers on a machine that you control.
To install Singularity on your system, follow the steps outlined here:
http://singularity.lbl.gov/install-linux
http://singularity.lbl.gov/install-mac
http://singularity.lbl.gov/install-windows
Method of creating a Singularity recipe file:
http://singularity.lbl.gov/docs-recipes
Method of building from a singularity recipe file:
http://singularity.lbl.gov/docs-build-container#building-containers-from-singularity-recipe-files
%% Cell type:markdown id: tags:
## Acknowledgments / Useful Links:
https://github.com/singularityhub/singularityhub.github.io/wiki
https://portal.biohpc.swmed.edu/content/guides/singularity-containers-biohpc/
https://www.docker.com/
https://devblogs.nvidia.com/docker-compatibility-singularity-hpc/
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment