build is the “Swiss army knife” of container creation. You can use it to download and assemble existing containers from external resources like Singularity Hub and Docker Hub. You can use it to convert containers between the various formats supported by Singularity. And you can use it in conjunction with a Singularity recipe file to create a container from scratch and customized it to fit your needs.
build command accepts a target as input and produces a container as output.
The target defines the method that
build uses to create the container. It can be one of the following:
- URI beginning with shub:// to build from Singularity Hub
- URI beginning with docker:// to build from Docker Hub
- path to a existing container on your local machine
- path to a directory to build from a sandbox
- path to an archive in .tar or compressed .tar.gz format
- path to a Singularity recipe file
build can produce containers in three different formats. Formats types can be specified by passing the following options to build.
- compressed read-only squashfs file system suitable for production (default)
- writable ext3 file system suitable for interactive development (
- writable (ch)root directory called a sandbox for interactive development (
build can accept an existing container as a target and create a container in any of these three formats you can convert existing containers from one format to another.
The following diagram illustrates the targets that can be supplied to
build as inputs and the containers
build can produce as outputs. Green arrows represent operations that can be carried out without root privileges (though the container may not perform properly when run as root). Red arrows represent operations that must be carried out with root privileges.
Downloading a existing container from Singularity Hub
You can use the
build command to download a container from Singularity Hub.
$ singularity build lolcow.simg shub://GodloveD/lolcow
The first argument (
lolcow.simg) specifies a path and name for your container. The second argument (
shub://GodloveD/lolcow) gives the Singularity Hub URI from which to download.
But default the container will be converted to a compressed, read-only squashfs file. If you want your container in a different format use the
Downloading a existing container from Docker Hub
You can use
build to download layers from Docker Hub and assemble them into Singularity containers.
$ singularity build lolcow.simg docker://godlovedc/lolcow
The same information applies to containers built from Docker Hub and containers built from Singularity Hub.
--writable images and
If you wanted to create a writable ext3 image similar to those used by Singularity version < 2.4, you could do so with the
--writable option. You must create writable containers as root.
Extending the Singularity Hub example from above:
$ sudo singularity build --writable lolcow.img shub://GodloveD/lolcow
The resulting container is writable, but is still mounted as read-only when executed with commands such as
shell. To mount the container as read-write when using these commands add the
--writable option to them as well.
To ensure that you have the proper permissions to write to the container as you like, it is also a good idea to make changes as root. For example:
$ sudo singularity shell --writable lolcow.img
If you wanted to create a container within a writable directory (called a sandbox) you could do so with the
--sandbox option. It’s possible to create a sandbox without root privileges, but to ensure proper file permissions it is recommended to do so as root.
$ sudo singularity build --sandbox lolcow/ shub://GodloveD/lolcow
The resulting directory operates just like a container in an image file. You are permitted to make changes and write files within the directory, but those changes will not persist when you are finished using the container. To make your changes persistent, use the
--writable flag when you invoke your container.
Once again, it’s a good idea to do this as root to ensure you have permission to access the files and directories that you want to change.
$ sudo singularity shell --writable lolcow/
Converting containers from one format to another
If you already have a container saved locally, you can use it as a target to build a new container. This allows you convert containers from one format to another. For example if you had a squashfs container called
production.simg and wanted to convert it to a writable ext3 container called
development.img you could:
$ sudo singularity build --writable development.img production.simg
Similarly, to convert it to a writable directory (a sandbox):
$ singularity build --sandbox development/ production.simg
If you omit any options you can also convert your sandbox back to a read-only compressed squashfs image suitable for use in a production environment:
$ singularity build production2 development/
You can convert the three supported container formats using any combination.
Use care when converting writable ext3 images or sandbox directories to the default squashfs file format. If changes were made to the writable container before conversion, there is no record of those changes in the Singularity recipe file rendering your container non-reproducible. It is a best practice to build your immutable production containers directly from a Singularity recipe file instead.
Building containers from Singularity recipe files
Of course, Singularity recipe files can be used as the target when building a container. For detailed information on writing Singularity recipe files, please see the Container Recipes docs.
Let’s say you already have the following container recipe file called
Singularity, and you want to use it to build a container.
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
You can do so with the following command.
$ sudo singularity build lolcow.simg Singularity
The command requires
sudo just as installing software on your local machine requires root privileges.
You can build into the same container multiple times (though the results may be unpredictable and it is generally better to delete your container and start from scratch).
By default if you build into an existing container, the
build command will skip the steps involved in adding a new base. You can override this default with the
--force option requiring that a new base OS is bootstrapped into the existing container. This behavior does not delete the existing OS, it just adds the new OS on top of the existing one.
Use care with this option: you may get results that you did not expect.
If you only want to build a single section of your Singularity recipe file use the
--section option. For instance, if you have edited the
%environment section of a long Singularity recipe and don’t want to completely re-build the container, you could re-build only the
%environment section like so:
$ sudo singularity build --section environment image.simg Singularity
Under normal build conditions, the Singularity recipe file is saved into a container’s meta-data so that there is a record showing how the container was built. Using the
--section option may render this meta-data useless, so use care if you value reproducibility.
If you don’t want to run the
%test section during the container build, you can skip it with the
--notest option. For instance, maybe you are building a container intended to run in a production environment with GPUs. But perhaps your local build resource does not have GPUs. You want to include a
%test section that runs a short validation but you don’t want your build to exit with an error because it cannot find a GPU on your system.
$ sudo singularity build GPU.simg --notest Singularity
Checks are a new feature (in 2.4) that offer an easy way for an admin to define a security (or any other kind of check) to be run on demand for a Singularity image. They are defined (and run) via different tags.
CHECKS OPTIONS: -c|--checks enable checks -t|--tag specify a check tag (not default) -l|--low Specify low threshold (all checks, default) -m|--med Perform medium and high checks -h|--high Perform only checks at level high
When you add the
--checks option along with applicable tags to the
build command Singularity will run the desired checks on your container at build time. See
singularity check --help for available tags.
More Build topics
- If you want to customize the cache location (where Docker layers are downloaded on your system), specify Docker credentials, or any custom tweaks to your build environment, see build environment.
- If you want to make internally modular containers, check out the getting started guide here.
- If you want to build your containers on Singularity Hub, (because you don’t have root access on a Linux machine or want to host your container on the cloud) check out this guide.