NAME

       singularity-build - Build a Singularity image

SYNOPSIS

       singularity build [local options...]

DESCRIPTION

       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

OPTIONS

       --arch="amd64"      architecture for remote build

       --authfile=""       Docker-style  authentication  file  to  use  for  writing/reading  OCI
       registry credentials

       -B,   --bind=[]        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)

       --build-arg=[]      provide value to replace {{ variable }} entries  in  build  definition
       file, in variable=value format

       --build-arg-file=""       specifies  a file containing variable=value lines to replace '{{
       variable }}' with value in build definition files

       --builder=""      remote Build Service URL, setting this implies --remote

       -d, --detached[=false]      submit build job and print build ID  (no  real-time  logs  and
       requires --remote)

       --disable-cache[=false]      do not use cache or create cache

       --docker-host=""      specify a custom Docker daemon host

       --docker-login[=false]      login to a Docker Repository interactively

       -e, --encrypt[=false]      build an image with an encrypted file system

       -f,  --fakeroot[=false]       build  using  user  namespace  to fake root user (requires a
       privileged installation)

       --fix-perms[=false]      ensure owner has rwX permissions on  all  container  content  for
       oci/docker sources

       -F, --force[=false]      overwrite an image file if it exists

       -h, --help[=false]      help for build

       --json[=false]      interpret build definition as JSON

       --keep-layers[=false]      Keep layers when creating an OCI-SIF. Do not squash to a single
       layer.

       --library=""      container Library URL

       --mount=[]      a mount specification e.g. 'type=bind,source=/opt,destination=/hostopt'.

       --no-cleanup[=false]      do NOT clean up bundle after failed build, can  be  helpful  for
       debugging

       --no-https[=false]      use http instead of https for docker:// oras:// and library:///...
       URIs

       --no-oci[=false]      Launch container with native runtime

       --no-setgroups[=false]      disable setgroups when entering --fakeroot user namespace

       -T, --notest[=false]      build without running tests in %test section

       --nv[=false]      inject host Nvidia libraries during build for  post  and  test  sections
       (not supported with remote build)

       --nvccli[=false]      use nvidia-container-cli for GPU setup (experimental)

       --oci[=false]      Launch container with OCI runtime (experimental)

       --passphrase[=false]      prompt for an encryption passphrase

       --pem-path=""      enter an path to a PEM formatted RSA key for an encrypted container

       -r, --remote[=false]      build image remotely (does not require root)

       --rocm[=false]       inject  host  Rocm  libraries during build for post and test sections
       (not supported with remote build)

       -s, --sandbox[=false]      build image as sandbox format (chroot directory structure)

       --section=[all]       only  run  specific  section(s)  of  deffile  (setup,  post,  files,
       environment, test, labels, none)

       -u, --update[=false]      run definition over existing container (skips header)

       --writable-tmpfs[=false]       during  the %test section, makes the file system accessible
       as read-write with non persistent data (with overlay support only)

EXAMPLE

         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:

         The following sections are presented in the order of processing, with the exception
         that labels and environment can also be manipulated in %post.

             %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."

             %files
                 /path/on/host/file.txt /path/on/container/file.txt
                 relative_file.txt /path/on/container/relative_file.txt

             %post
                 echo "This scriptlet section will be executed from within the container after"
                 echo "the bootstrap/base has been created and setup."

             %environment
                 LUKE=goodguy
                 VADER=badguy
                 HAN=someguy
                 export HAN VADER LUKE

             %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

             %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

SEE ALSO

       singularity(1)

HISTORY

       1-Apr-2024 Auto generated by spf13/cobra