1apptainer(1) apptainer(1)
2
6 apptainer-build - Build an Apptainer image
7
11 apptainer build [local options...]
12
16 IMAGE PATH:
17 When Apptainer builds the container, output can be one of a few for‐
20 mats:
21 default: The compressed Apptainer read only image format (default)
24 sandbox: This is a read-write container within a directory structure
25 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 BUILD SPEC:
36 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 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 Targets can also be remote and defined by a URI of the following for‐
53 mats:
54 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 Temporary files:
64 The location used for temporary directories defaults to '/tmp' but
67 can be overridden by the TMPDIR environment variable, and that can be
68 overridden by the APPTAINER_TMPDIR environment variable. The
69 temporary directory used during a build must be on a filesystem that
70 has enough space to hold the entire container image, uncompressed,
71 including any temporary files that are created and later removed
72 during the build. You may need to set APPTAINER_TMPDIR or TMPDIR when
73 building a large container on a system that has a small /tmp filesys‐
74 tem.
75
79 -B, --bind=[] a user-bind path specification. spec has the format
80 src[:dest[:opts]],where src and dest are outside and inside paths. If
81 dest is not given,it is set equal to src. Mount options ('opts') may be
82 specified as 'ro'(read-only) or 'rw' (read/write, which is the de‐
83 fault).Multiple bind paths can be given by a comma separated list.
84 --build-arg=[] defines variable=value to replace {{ variable }}
87 entries in build definition file
88 --build-arg-file="" specifies a file containing variable=value
91 lines to replace '{{ variable }}' with value in build definition files
92 --disable-cache[=false] do not use cache or create cache
95 --docker-host="" specify a custom Docker daemon host
98 --docker-login[=false] login to a Docker Repository interactively
101 -e, --encrypt[=false] build an image with an encrypted file system
104 -f, --fakeroot[=false] build with the appearance of running as
107 root (default when building from a definition file unprivileged)
108 --fix-perms[=false] ensure owner has rwX permissions on all con‐
111 tainer content for oci/docker sources
112 -F, --force[=false] overwrite an image file if it exists
115 -h, --help[=false] help for build
118 --json[=false] interpret build definition as JSON
121 --library="" container Library URL
124 --mount=[] a mount specification e.g. 'type=bind,source=/opt,des‐
127 tination=/hostopt'.
128 --no-cleanup[=false] do NOT clean up bundle after failed build,
131 can be helpful for debugging
132 --no-https[=false] use http instead of https for docker:// oras://
135 and library:///... URIs
136 -T, --notest[=false] build without running tests in %test section
139 --nv[=false] inject host Nvidia libraries during build for post
142 and test sections
143 --nvccli[=false] use nvidia-container-cli for GPU setup (experi‐
146 mental)
147 --passphrase[=false] prompt for an encryption passphrase
150 --pem-path="" enter an path to a PEM formatted RSA key for an en‐
153 crypted container
154 --rocm[=false] inject host Rocm libraries during build for post
157 and test sections
158 -s, --sandbox[=false] build image as sandbox format (chroot direc‐
161 tory structure)
162 --section=[all] only run specific section(s) of deffile (setup,
165 post, files, environment, test, labels, none)
166 -u, --update[=false] run definition over existing container (skips
169 header)
170 --userns[=false] build without using setuid even if available
173 --warn-unused-build-args[=false] shows warning instead of fatal
176 message when build args are not exact matched
177 --writable-tmpfs[=false] during the %test section, makes the file
180 system accessible as read-write with non persistent data (with overlay
181 support only)
182
186 DEF FILE BASE OS:
187 Library:
189 Bootstrap: library
190 From: debian:9
191 Docker:
193 Bootstrap: docker
194 From: tensorflow/tensorflow:latest
195 IncludeCmd: yes # Use the CMD as runscript instead of ENTRYPOINT
196 Singularity Hub:
198 Bootstrap: shub
199 From: singularityhub/centos
200 YUM/RHEL:
202 Bootstrap: yum
203 OSVersion: 7
204 MirrorURL: http://mirror.centos.org/centos-%{OSVERSION}/%{OSVERSION}/os/x86_64/
205 Include: yum
206 SUSE:
208 Bootstrap: zypper # on SLE system registration of build host is used
209 Include: zypper
210 openSUSE:
212 Bootstrap: zypper
213 MirrorURL: http://download.opensuse.org/distribution/openSUSE-stable/repo/oss
214 Include: zypper
215 Debian/Ubuntu:
217 Bootstrap: debootstrap
218 OSVersion: trusty
219 MirrorURL: http://us.archive.ubuntu.com/ubuntu/
220 Local Image:
222 Bootstrap: localimage
223 From: /home/dave/starter.img
224 Scratch:
226 Bootstrap: scratch # Populate the container with a minimal rootfs in %setup
227 DEFFILE SECTIONS:
229 The following sections are presented in the order of processing, with the exception
231 that labels and environment can also be manipulated in %post.
232 %pre
234 echo "This is a scriptlet that will be executed on the host, as root before"
235 echo "the container has been bootstrapped. This section is not commonly used."
236 %setup
238 echo "This is a scriptlet that will be executed on the host, as root, after"
239 echo "the container has been bootstrapped. To install things into the container"
240 echo "reference the file system location with $APPTAINER_ROOTFS."
241 %files
243 /path/on/host/file.txt /path/on/container/file.txt
244 relative_file.txt /path/on/container/relative_file.txt
245 %post
247 echo "This scriptlet section will be executed from within the container after"
248 echo "the bootstrap/base has been created and setup."
249 %environment
251 LUKE=goodguy
252 VADER=badguy
253 HAN=someguy
254 export HAN VADER LUKE
255 %test
257 echo "Define any test commands that should be executed after container has been"
258 echo "built. This scriptlet will be executed from within the running container"
259 echo "as the root user. Pay attention to the exit/return value of this scriptlet"
260 echo "as any non-zero exit code will be assumed as failure."
261 exit 0
262 %runscript
264 echo "Define actions for the container to be executed with the run command or"
265 echo "when container is executed."
266 %startscript
268 echo "Define actions for container to perform when started as an instance."
269 %labels
271 HELLO MOTO
272 KEY VALUE
273 %help
275 This is a text file to be displayed with the run-help command.
276 COMMANDS:
278 Build a sif file from an Apptainer recipe file:
280 $ apptainer build /tmp/debian0.sif /path/to/debian.def
281 Build a sif image from the Library:
283 $ apptainer build /tmp/debian1.sif library://debian:latest
284 Build a base sandbox from DockerHub, make changes to it, then build sif
286 $ apptainer build --sandbox /tmp/debian docker://debian:latest
287 $ apptainer exec --writable /tmp/debian apt-get install python
288 $ apptainer build /tmp/debian2.sif /tmp/debian
289
294 apptainer(1)
295
299 22-Nov-2023 Auto generated by spf13/cobra
300Auto generated by spf13/cobra Nov 2023 apptainer(1)