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 registry (default Docker Hub) shub:// a Singularity registry (default Singularity Hub) oras:// a supporting OCI registry
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

    --builder string    remote Build Service URL, setting this implies --remote (default "https://build.sylabs.io")
-d, --detached          submit build job and print build ID (no real-time logs and requires --remote)
    --docker-login      login to a Docker Repository interactively
-f, --fakeroot          build using user namespace to fake root user (requires a privileged installation)
-F, --force             delete and overwrite an image if it currently exists
-h, --help              help for build
    --json              interpret build definition as JSON
    --library string    container Library URL (default "https://library.sylabs.io")
    --no-cleanup        do NOT clean up bundle after failed build, can be helpul for debugging
    --nohttps           do NOT use HTTPS, for communicating with local docker registry
-T, --notest            build without running tests in %test section
-r, --remote            build image remotely (does not require root)
-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])
    --tmpdir string     specify a temporary directory to use for build
-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 26-Jul-2019