1apptainer(1) apptainer(1)
2
3
4
6 apptainer-build - Build an Apptainer image
7
8
9
11 apptainer build [local options...]
12
13
14
16 IMAGE PATH:
17
18
19 When Apptainer builds the container, output can be one of a few for‐
20 mats:
21
22
23 default: The compressed Apptainer 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 Apptainer image for produc‐
31 tion
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 an Apptainer 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 (no default)
57 docker:// a Docker/OCI registry (default Docker Hub)
58 shub:// an Apptainer registry (default Singularity Hub)
59 oras:// an OCI registry that holds SIF files using ORAS
60
61
62
63
65 -B, --bind=[] a user-bind path specification. spec has the format
66 src[:dest[:opts]],where src and dest are outside and inside paths. If
67 dest is not given,it is set equal to src. Mount options ('opts') may be
68 specified as 'ro'(read-only) or 'rw' (read/write, which is the de‐
69 fault).Multiple bind paths can be given by a comma separated list.
70
71
72 --disable-cache[=false] do not use cache or create cache
73
74
75 --docker-login[=false] login to a Docker Repository interactively
76
77
78 -e, --encrypt[=false] build an image with an encrypted file system
79
80
81 -f, --fakeroot[=false] build with the appearance of running as
82 root (default when building from a definition file unprivileged)
83
84
85 --fix-perms[=false] ensure owner has rwX permissions on all con‐
86 tainer content for oci/docker sources
87
88
89 -F, --force[=false] overwrite an image file if it exists
90
91
92 -h, --help[=false] help for build
93
94
95 --json[=false] interpret build definition as JSON
96
97
98 --library="" container Library URL
99
100
101 --mount=[] a mount specification e.g. 'type=bind,source=/opt,des‐
102 tination=/hostopt'.
103
104
105 --no-cleanup[=false] do NOT clean up bundle after failed build,
106 can be helpful for debugging
107
108
109 --no-https[=false] use http instead of https for docker:// oras://
110 and library:///... URIs
111
112
113 -T, --notest[=false] build without running tests in %test section
114
115
116 --nv[=false] inject host Nvidia libraries during build for post
117 and test sections
118
119
120 --nvccli[=false] use nvidia-container-cli for GPU setup (experi‐
121 mental)
122
123
124 --passphrase[=false] prompt for an encryption passphrase
125
126
127 --pem-path="" enter an path to a PEM formatted RSA key for an en‐
128 crypted container
129
130
131 --rocm[=false] inject host Rocm libraries during build for post
132 and test sections
133
134
135 -s, --sandbox[=false] build image as sandbox format (chroot direc‐
136 tory structure)
137
138
139 --section=[all] only run specific section(s) of deffile (setup,
140 post, files, environment, test, labels, none)
141
142
143 -u, --update[=false] run definition over existing container (skips
144 header)
145
146
147 --userns[=false] build without using setuid even if available
148
149
150 --writable-tmpfs[=false] during the %test section, makes the file
151 system accessible as read-write with non persistent data (with overlay
152 support only)
153
154
155
157 DEF FILE BASE OS:
158
159 Library:
160 Bootstrap: library
161 From: debian:9
162
163 Docker:
164 Bootstrap: docker
165 From: tensorflow/tensorflow:latest
166 IncludeCmd: yes # Use the CMD as runscript instead of ENTRYPOINT
167
168 Singularity Hub:
169 Bootstrap: shub
170 From: singularityhub/centos
171
172 YUM/RHEL:
173 Bootstrap: yum
174 OSVersion: 7
175 MirrorURL: http://mirror.centos.org/centos-%{OSVERSION}/%{OSVERSION}/os/x86_64/
176 Include: yum
177
178 SUSE:
179 Bootstrap: zypper # on SLE system registration of build host is used
180 Include: zypper
181
182 openSUSE:
183 Bootstrap: zypper
184 MirrorURL: http://download.opensuse.org/distribution/openSUSE-stable/repo/oss
185 Include: zypper
186
187 Debian/Ubuntu:
188 Bootstrap: debootstrap
189 OSVersion: trusty
190 MirrorURL: http://us.archive.ubuntu.com/ubuntu/
191
192 Local Image:
193 Bootstrap: localimage
194 From: /home/dave/starter.img
195
196 Scratch:
197 Bootstrap: scratch # Populate the container with a minimal rootfs in %setup
198
199 DEFFILE SECTIONS:
200
201 The following sections are presented in the order of processing, with the exception
202 that labels and environment can also be manipulated in %post.
203
204 %pre
205 echo "This is a scriptlet that will be executed on the host, as root before"
206 echo "the container has been bootstrapped. This section is not commonly used."
207
208 %setup
209 echo "This is a scriptlet that will be executed on the host, as root, after"
210 echo "the container has been bootstrapped. To install things into the container"
211 echo "reference the file system location with $APPTAINER_ROOTFS."
212
213 %files
214 /path/on/host/file.txt /path/on/container/file.txt
215 relative_file.txt /path/on/container/relative_file.txt
216
217 %post
218 echo "This scriptlet section will be executed from within the container after"
219 echo "the bootstrap/base has been created and setup."
220
221 %environment
222 LUKE=goodguy
223 VADER=badguy
224 HAN=someguy
225 export HAN VADER LUKE
226
227 %test
228 echo "Define any test commands that should be executed after container has been"
229 echo "built. This scriptlet will be executed from within the running container"
230 echo "as the root user. Pay attention to the exit/return value of this scriptlet"
231 echo "as any non-zero exit code will be assumed as failure."
232 exit 0
233
234 %runscript
235 echo "Define actions for the container to be executed with the run command or"
236 echo "when container is executed."
237
238 %startscript
239 echo "Define actions for container to perform when started as an instance."
240
241 %labels
242 HELLO MOTO
243 KEY VALUE
244
245 %help
246 This is a text file to be displayed with the run-help command.
247
248 COMMANDS:
249
250 Build a sif file from an Apptainer recipe file:
251 $ apptainer build /tmp/debian0.sif /path/to/debian.def
252
253 Build a sif image from the Library:
254 $ apptainer build /tmp/debian1.sif library://debian:latest
255
256 Build a base sandbox from DockerHub, make changes to it, then build sif
257 $ apptainer build --sandbox /tmp/debian docker://debian:latest
258 $ apptainer exec --writable /tmp/debian apt-get install python
259 $ apptainer build /tmp/debian2.sif /tmp/debian
260
261
262
263
265 apptainer(1)
266
267
268
270 29-Mar-2023 Auto generated by spf13/cobra
271
272
273
274Auto generated by spf13/cobra Mar 2023 apptainer(1)