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       --builder=""       remote Build Service URL, setting this implies --re‐
69       mote
70
71
72       -d, --detached[=false]      submit build job and  print  build  ID  (no
73       real-time logs and requires --remote)
74
75
76       --disable-cache[=false]      do not use cache or create cache
77
78
79       --docker-login[=false]      login to a Docker Repository interactively
80
81
82       -e, --encrypt[=false]      build an image with an encrypted file system
83
84
85       -f,  --fakeroot[=false]       build  using  user namespace to fake root
86       user (requires a privileged installation)
87
88
89       --fix-perms[=false]      ensure owner has rwX permissions on  all  con‐
90       tainer content for oci/docker sources
91
92
93       -F, --force[=false]      overwrite an image file if it exists
94
95
96       -h, --help[=false]      help for build
97
98
99       --json[=false]      interpret build definition as JSON
100
101
102       --library=""      container Library URL
103
104
105       --no-cleanup[=false]       do  NOT  clean up bundle after failed build,
106       can be helpful for debugging
107
108
109       --nohttps[=false]      do NOT use HTTPS with  the  docker://  transport
110       (useful for local docker registries without a certificate)
111
112
113       -T, --notest[=false]      build without running tests in %test section
114
115
116       --passphrase[=false]      prompt for an encryption passphrase
117
118
119       --pem-path=""       enter  an path to a PEM formated RSA key for an en‐
120       crypted container
121
122
123       -r, --remote[=false]      build image remotely (does not require root)
124
125
126       -s, --sandbox[=false]      build image as sandbox format (chroot direc‐
127       tory structure)
128
129
130       --section=[all]       only  run  specific section(s) of deffile (setup,
131       post, files, environment, test, labels, none)
132
133
134       -u, --update[=false]      run definition over existing container (skips
135       header)
136
137
138

EXAMPLE

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

SEE ALSO

236       singularity(1)
237
238
239

HISTORY

241       26-May-2021 Auto generated by spf13/cobra
242
243
244
245Auto generated by spf13/cobra      May 2021                     singularity(1)
Impressum