It’s common to want your container to “do a thing.” Singularity
run allows you to define a custom action to be taken when a container is either
run or executed directly by file name. Specifically, you might want it to execute a command, or run an executable that gives access to many different functions for the user.
First, how do we run a container? We can do that in one of two ways - the commands below are identical:
$ singularity run centos7.img $ ./centos7.img
In both cases, we are executing the container’s “runscript” (the executable
/singularity at the root of the image) that is either an actual file (version 2.2 and earlier) or a link to one (2.3 and later). For example, looking at a 2.3 image, I can see the runscript via the path to the link:
$ singularity exec centos7.img cat /singularity #!/bin/sh exec /bin/bash "$@"
or to the actual file in the container’s metadata folder,
$ singularity exec centos7.img cat /.singularity.d/runscript #!/bin/sh exec /bin/bash "$@"
Notice how the runscript has bash followed by
$@? This is good practice to include in a runscript, as any arguments passed by the user will be given to the container. Thus, I could send a command to the container for bash to run:
In this example the container has a very simple runscript defined.
$ singularity exec centos7.img cat /singularity #!/bin/sh echo motorbot $ singularity run centos7.img motorbot
Defining the Runscript
When you first create a container, the runscript is defined using the following order of operations:
- A user defined runscript in the
%runscriptsection of a bootstrap takes preference over all
- If the user has not defined a runscript and is importing a Docker container, the Docker
- If a user has not defined a runscript and adds
IncludeCmd: yesto the bootstrap file, the
CMDis used over the
- If the user has not defined a runscript and the Docker container doesn’t have an
ENTRYPOINT, we look for
CMD, even if the user hasn’t asked for it.
- If the user has not deifned a runscript, and there is no
CMD(or we aren’t importing Docker at all) then we default to
Here is how you would define the runscript section when you bootstrap an image:
Bootstrap: docker From: ubuntu:latest %runscript exec /usr/bin/python "$@"
and of course python should be installed as /usr/bin/python. The addition of
"$@" ensures that arguments are passed along from the user. If you want your container to run absolutely any command given to it, and you want to use run instead of exec, you could also just do:
Bootstrap: docker From: ubuntu:latest %runscript exec "$@"`
Generally, it is advised to provide a runscript that tells your user how to use the container, and gives access to the important executables. A user should be able to find your container, and execute it without an arguments, and get the equivalent of
--help. Depending on your language of choice, you can do this in multiple ways.