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

NAME

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

SYNOPSIS

11       singularity build [local options...] <IMAGE PATH> <BUILD SPEC>
12
13
14

DESCRIPTION

16       IMAGE PATH:
17
18
19       When Singularity builds the container, output can be one of a few
20       formats:
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
31       production
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
53       formats:
54
55
56                library://  an image library (default https://cloud.sylabs.io/library)
57                docker://   a Docker registry (default Docker Hub)
58                shub://     a Singularity registry (default Singularity Hub)
59
60
61
62

OPTIONS

64       --builder=" ⟨https://build.sylabs.io"⟩
65           remote Build Service URL, setting this implies --remote
66
67
68       -d, --detached[=false]
69           submit build job and print build ID (no real-time logs and requires
70       --remote)
71
72
73       --docker-login[=false]
74           login to a Docker Repository interactively
75
76
77       -F, --force[=false]
78           delete and overwrite an image if it currently exists
79
80
81       -h, --help[=false]
82           help for build
83
84
85       --json[=false]
86           interpret build definition as JSON
87
88
89       --library=" ⟨https://library.sylabs.io"⟩
90           container Library URL
91
92
93       --no-cleanup[=false]
94           do NOT clean up bundle after failed build, can be helpul for
95       debugging
96
97
98       --nohttps[=false]
99           do NOT use HTTPS, for communicating with local docker registry
100
101
102       -T, --notest[=false]
103           build without running tests in %test section
104
105
106       -r, --remote[=false]
107           build image remotely (does not require root)
108
109
110       -s, --sandbox[=false]
111           build image as sandbox format (chroot directory structure)
112
113
114       --section=[all]
115           only run specific section(s) of deffile (setup, post, files,
116       environment, test, labels, none)
117
118
119       --tmpdir=""
120           specify a temporary directory to use for build
121
122
123       -u, --update[=false]
124           run definition over existing container (skips header)
125
126
127

EXAMPLE

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

SEE ALSO

225       singularity(1)
226
227
228

HISTORY

230       29-May-2019 Auto generated by spf13/cobra
231
232
233
234Auto generated by spf13/cobra      May 2019                     singularity(1)
Impressum