singularity build¶
Build a Singularity image
Synopsis¶
IMAGE PATH:
When Singularity builds the container, output can be one of a few formats:
default: The compressed Singularity read only image format (default) sandbox: This is a read-write container within a directory structure
note: It is a common workflow to use the “sandbox” mode for development of the container, and then build it as a default Singularity image for production use. The default format is immutable.
BUILD SPEC:
The build spec target is a definition (def) file, local image, or URI that can be used to create a Singularity container. Several different local target formats exist:
def file : This is a recipe for building a container (examples below) directory: A directory structure containing a (ch)root file system image: A local image on your machine (will convert to sif if
it is legacy format)
Targets can also be remote and defined by a URI of the following formats:
library:// an image library (default https://cloud.sylabs.io/library) docker:// a Docker/OCI registry (default Docker Hub) shub:// a Singularity registry (default Singularity Hub) oras:// an OCI registry that holds SIF files using ORAS
singularity build [local options...] <IMAGE PATH> <BUILD SPEC>
Examples¶
DEF FILE BASE OS:
Library:
Bootstrap: library
From: debian:9
Docker:
Bootstrap: docker
From: tensorflow/tensorflow:latest
IncludeCmd: yes # Use the CMD as runscript instead of ENTRYPOINT
Singularity Hub:
Bootstrap: shub
From: singularityhub/centos
YUM/RHEL:
Bootstrap: yum
OSVersion: 7
MirrorURL: http://mirror.centos.org/centos-%{OSVERSION}/%{OSVERSION}/os/x86_64/
Include: yum
Debian/Ubuntu:
Bootstrap: debootstrap
OSVersion: trusty
MirrorURL: http://us.archive.ubuntu.com/ubuntu/
Local Image:
Bootstrap: localimage
From: /home/dave/starter.img
Scratch:
Bootstrap: scratch # Populate the container with a minimal rootfs in %setup
DEFFILE SECTIONS:
%pre
echo "This is a scriptlet that will be executed on the host, as root before"
echo "the container has been bootstrapped. This section is not commonly used."
%setup
echo "This is a scriptlet that will be executed on the host, as root, after"
echo "the container has been bootstrapped. To install things into the container"
echo "reference the file system location with $SINGULARITY_ROOTFS."
%post
echo "This scriptlet section will be executed from within the container after"
echo "the bootstrap/base has been created and setup."
%test
echo "Define any test commands that should be executed after container has been"
echo "built. This scriptlet will be executed from within the running container"
echo "as the root user. Pay attention to the exit/return value of this scriptlet"
echo "as any non-zero exit code will be assumed as failure."
exit 0
%runscript
echo "Define actions for the container to be executed with the run command or"
echo "when container is executed."
%startscript
echo "Define actions for container to perform when started as an instance."
%labels
HELLO MOTO
KEY VALUE
%files
/path/on/host/file.txt /path/on/container/file.txt
relative_file.txt /path/on/container/relative_file.txt
%environment
LUKE=goodguy
VADER=badguy
HAN=someguy
export HAN VADER LUKE
%help
This is a text file to be displayed with the run-help command.
COMMANDS:
Build a sif file from a Singularity recipe file:
$ singularity build /tmp/debian0.sif /path/to/debian.def
Build a sif image from the Library:
$ singularity build /tmp/debian1.sif library://debian:latest
Build a base sandbox from DockerHub, make changes to it, then build sif
$ singularity build --sandbox /tmp/debian docker://debian:latest
$ singularity exec --writable /tmp/debian apt-get install python
$ singularity build /tmp/debian2.sif /tmp/debian
Options¶
--arch string architecture for remote build (default "amd64")
-B, --bind strings a user-bind path specification. spec has the format src[:dest[:opts]],where src and dest are outside and inside paths. If dest is not given,it is set equal to src. Mount options ('opts') may be specified as 'ro'(read-only) or 'rw' (read/write, which is the default).Multiple bind paths can be given by a comma separated list. (not supported with remote build)
--builder string remote Build Service URL, setting this implies --remote
-d, --detached submit build job and print build ID (no real-time logs and requires --remote)
--disable-cache do not use cache or create cache
--docker-login login to a Docker Repository interactively
-e, --encrypt build an image with an encrypted file system
-f, --fakeroot build using user namespace to fake root user (requires a privileged installation)
--fix-perms ensure owner has rwX permissions on all container content for oci/docker sources
-F, --force overwrite an image file if it exists
-h, --help help for build
--json interpret build definition as JSON
--library string container Library URL
--no-cleanup do NOT clean up bundle after failed build, can be helpful for debugging
--nohttps do NOT use HTTPS with the docker:// transport (useful for local docker registries without a certificate)
-T, --notest build without running tests in %test section
--nv inject host Nvidia libraries during build for post and test sections (not supported with remote build)
--passphrase prompt for an encryption passphrase
--pem-path string enter an path to a PEM formated RSA key for an encrypted container
-r, --remote build image remotely (does not require root)
--rocm inject host Rocm libraries during build for post and test sections (not supported with remote build)
-s, --sandbox build image as sandbox format (chroot directory structure)
--section strings only run specific section(s) of deffile (setup, post, files, environment, test, labels, none) (default [all])
-u, --update run definition over existing container (skips header)
SEE ALSO¶
Linux container platform optimized for High Performance Computing (HPC) and Enterprise Performance Computing (EPC)
Auto generated by spf13/cobra on 2-Jul-2021