1singularity(1)                                                  singularity(1)
2
3
4

NAME

6       singularity-build - Build a Singularity image
7
8
9

SYNOPSIS

11       singularity build [local options...]
12
13
14

DESCRIPTION

16       IMAGE PATH:
17
18
19       When  Singularity builds the container, output can be one of a few for‐
20       mats:
21
22
23                default:    The compressed Singularity read only image format (default)
24                sandbox:    This is a read-write container within a directory structure
25
26
27
28       note: It is a common workflow to use the "sandbox" mode for development
29       of the
30         container,  and then build it as a default Singularity image for pro‐
31       duction
32         use. The default format is immutable.
33
34
35       BUILD SPEC:
36
37
38       The build spec target is a definition (def) file, local image,  or  URI
39       that can
40         be  used  to  create a Singularity container. Several different local
41       target
42         formats exist:
43
44
45                def file  : This is a recipe for building a container (examples below)
46                directory:  A directory structure containing a (ch)root file system
47                image:      A local image on your machine (will convert to sif if
48                            it is legacy format)
49
50
51
52       Targets can also be remote and defined by a URI of the  following  for‐
53       mats:
54
55
56                library://  an image library (default https://cloud.sylabs.io/library)
57                docker://   a Docker/OCI registry (default Docker Hub)
58                shub://     a Singularity registry (default Singularity Hub)
59                oras://     an OCI registry that holds SIF files using ORAS
60
61
62
63

OPTIONS

65       --arch="amd64"      architecture for remote build
66
67
68       -B,  --bind=[]      a user-bind path specification. spec has the format
69       src[:dest[:opts]],where src and dest are outside and inside  paths.  If
70       dest is not given,it is set equal to src. Mount options ('opts') may be
71       specified as 'ro'(read-only) or 'rw'  (read/write,  which  is  the  de‐
72       fault).Multiple bind paths can be given by a comma separated list. (not
73       supported with remote build)
74
75
76       --builder=""      remote Build Service URL, setting this implies  --re‐
77       mote
78
79
80       -d,  --detached[=false]       submit  build  job and print build ID (no
81       real-time logs and requires --remote)
82
83
84       --disable-cache[=false]      do not use cache or create cache
85
86
87       --docker-login[=false]      login to a Docker Repository interactively
88
89
90       -e, --encrypt[=false]      build an image with an encrypted file system
91
92
93       -f, --fakeroot[=false]      build using user  namespace  to  fake  root
94       user (requires a privileged installation)
95
96
97       --fix-perms[=false]       ensure  owner has rwX permissions on all con‐
98       tainer content for oci/docker sources
99
100
101       -F, --force[=false]      overwrite an image file if it exists
102
103
104       -h, --help[=false]      help for build
105
106
107       --json[=false]      interpret build definition as JSON
108
109
110       --library=""      container Library URL
111
112
113       --no-cleanup[=false]      do NOT clean up bundle  after  failed  build,
114       can be helpful for debugging
115
116
117       --nohttps[=false]       do  NOT  use HTTPS with the docker:// transport
118       (useful for local docker registries without a certificate)
119
120
121       -T, --notest[=false]      build without running tests in %test section
122
123
124       --nv[=false]      inject host Nvidia libraries during  build  for  post
125       and test sections (not supported with remote build)
126
127
128       --passphrase[=false]      prompt for an encryption passphrase
129
130
131       --pem-path=""       enter  an path to a PEM formated RSA key for an en‐
132       crypted container
133
134
135       -r, --remote[=false]      build image remotely (does not require root)
136
137
138       --rocm[=false]      inject host Rocm libraries during  build  for  post
139       and test sections (not supported with remote build)
140
141
142       -s, --sandbox[=false]      build image as sandbox format (chroot direc‐
143       tory structure)
144
145
146       --section=[all]      only run specific section(s)  of  deffile  (setup,
147       post, files, environment, test, labels, none)
148
149
150       -u, --update[=false]      run definition over existing container (skips
151       header)
152
153
154

EXAMPLE

156                DEF FILE BASE OS:
157
158                    Library:
159                        Bootstrap: library
160                        From: debian:9
161
162                    Docker:
163                        Bootstrap: docker
164                        From: tensorflow/tensorflow:latest
165                        IncludeCmd: yes # Use the CMD as runscript instead of ENTRYPOINT
166
167                    Singularity Hub:
168                        Bootstrap: shub
169                        From: singularityhub/centos
170
171                    YUM/RHEL:
172                        Bootstrap: yum
173                        OSVersion: 7
174                        MirrorURL: http://mirror.centos.org/centos-%{OSVERSION}/%{OSVERSION}/os/x86_64/
175                        Include: yum
176
177                    Debian/Ubuntu:
178                        Bootstrap: debootstrap
179                        OSVersion: trusty
180                        MirrorURL: http://us.archive.ubuntu.com/ubuntu/
181
182                    Local Image:
183                        Bootstrap: localimage
184                        From: /home/dave/starter.img
185
186                    Scratch:
187                        Bootstrap: scratch # Populate the container with a minimal rootfs in %setup
188
189                DEFFILE SECTIONS:
190
191                    %pre
192                        echo "This is a scriptlet that will be executed on the host, as root before"
193                        echo "the container has been bootstrapped. This section is not commonly used."
194
195                    %setup
196                        echo "This is a scriptlet that will be executed on the host, as root, after"
197                        echo "the container has been bootstrapped. To install things into the container"
198                        echo "reference the file system location with $SINGULARITY_ROOTFS."
199
200                    %post
201                        echo "This scriptlet section will be executed from within the container after"
202                        echo "the bootstrap/base has been created and setup."
203
204                    %test
205                        echo "Define any test commands that should be executed after container has been"
206                        echo "built. This scriptlet will be executed from within the running container"
207                        echo "as the root user. Pay attention to the exit/return value of this scriptlet"
208                        echo "as any non-zero exit code will be assumed as failure."
209                        exit 0
210
211                    %runscript
212                        echo "Define actions for the container to be executed with the run command or"
213                        echo "when container is executed."
214
215                    %startscript
216                        echo "Define actions for container to perform when started as an instance."
217
218                    %labels
219                        HELLO MOTO
220                        KEY VALUE
221
222                    %files
223                        /path/on/host/file.txt /path/on/container/file.txt
224                        relative_file.txt /path/on/container/relative_file.txt
225
226                    %environment
227                        LUKE=goodguy
228                        VADER=badguy
229                        HAN=someguy
230                        export HAN VADER LUKE
231
232                    %help
233                        This is a text file to be displayed with the run-help command.
234
235                COMMANDS:
236
237                    Build a sif file from a Singularity recipe file:
238                        $ singularity build /tmp/debian0.sif /path/to/debian.def
239
240                    Build a sif image from the Library:
241                        $ singularity build /tmp/debian1.sif library://debian:latest
242
243                    Build a base sandbox from DockerHub, make changes to it, then build sif
244                        $ singularity build --sandbox /tmp/debian docker://debian:latest
245                        $ singularity exec --writable /tmp/debian apt-get install python
246                        $ singularity build /tmp/debian2.sif /tmp/debian
247
248
249
250

SEE ALSO

252       singularity(1)
253
254
255

HISTORY

257       23-Jul-2022 Auto generated by spf13/cobra
258
259
260
261Auto generated by spf13/cobra      Jul 2022                     singularity(1)