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
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 --disable-cache[=false] do not use cache or create cache
73 --docker-login[=false] login to a Docker Repository interactively
76 -e, --encrypt[=false] build an image with an encrypted file system
79 -f, --fakeroot[=false] build using user namespace to fake root
82 user (requires a privileged installation)
83 --fix-perms[=false] ensure owner has rwX permissions on all con‐
86 tainer content for oci/docker sources
87 -F, --force[=false] overwrite an image file if it exists
90 -h, --help[=false] help for build
93 --json[=false] interpret build definition as JSON
96 --library="" container Library URL
99 --mount=[] a mount specification e.g. 'type=bind,source=/opt,des‐
102 tination=/hostopt'.
103 --no-cleanup[=false] do NOT clean up bundle after failed build,
106 can be helpful for debugging
107 --no-https[=false] use http instead of https for docker:// oras://
110 and library:///... URIs
111 -T, --notest[=false] build without running tests in %test section
114 --nv[=false] inject host Nvidia libraries during build for post
117 and test sections
118 --nvccli[=false] use nvidia-container-cli for GPU setup (experi‐
121 mental)
122 --passphrase[=false] prompt for an encryption passphrase
125 --pem-path="" enter an path to a PEM formatted RSA key for an en‐
128 crypted container
129 --rocm[=false] inject host Rocm libraries during build for post
132 and test sections
133 -s, --sandbox[=false] build image as sandbox format (chroot direc‐
136 tory structure)
137 --section=[all] only run specific section(s) of deffile (setup,
140 post, files, environment, test, labels, none)
141 -u, --update[=false] run definition over existing container (skips
144 header)
145 --writable-tmpfs[=false] during the %test section, makes the file
148 system accessible as read-write with non persistent data (with overlay
149 support only)
150
154 DEF FILE BASE OS:
155 Library:
157 Bootstrap: library
158 From: debian:9
159 Docker:
161 Bootstrap: docker
162 From: tensorflow/tensorflow:latest
163 IncludeCmd: yes # Use the CMD as runscript instead of ENTRYPOINT
164 Singularity Hub:
166 Bootstrap: shub
167 From: singularityhub/centos
168 YUM/RHEL:
170 Bootstrap: yum
171 OSVersion: 7
172 MirrorURL: http://mirror.centos.org/centos-%{OSVERSION}/%{OSVERSION}/os/x86_64/
173 Include: yum
174 Debian/Ubuntu:
176 Bootstrap: debootstrap
177 OSVersion: trusty
178 MirrorURL: http://us.archive.ubuntu.com/ubuntu/
179 Local Image:
181 Bootstrap: localimage
182 From: /home/dave/starter.img
183 Scratch:
185 Bootstrap: scratch # Populate the container with a minimal rootfs in %setup
186 DEFFILE SECTIONS:
188 %pre
190 echo "This is a scriptlet that will be executed on the host, as root before"
191 echo "the container has been bootstrapped. This section is not commonly used."
192 %setup
194 echo "This is a scriptlet that will be executed on the host, as root, after"
195 echo "the container has been bootstrapped. To install things into the container"
196 echo "reference the file system location with $APPTAINER_ROOTFS."
197 %post
199 echo "This scriptlet section will be executed from within the container after"
200 echo "the bootstrap/base has been created and setup."
201 %test
203 echo "Define any test commands that should be executed after container has been"
204 echo "built. This scriptlet will be executed from within the running container"
205 echo "as the root user. Pay attention to the exit/return value of this scriptlet"
206 echo "as any non-zero exit code will be assumed as failure."
207 exit 0
208 %runscript
210 echo "Define actions for the container to be executed with the run command or"
211 echo "when container is executed."
212 %startscript
214 echo "Define actions for container to perform when started as an instance."
215 %labels
217 HELLO MOTO
218 KEY VALUE
219 %files
221 /path/on/host/file.txt /path/on/container/file.txt
222 relative_file.txt /path/on/container/relative_file.txt
223 %environment
225 LUKE=goodguy
226 VADER=badguy
227 HAN=someguy
228 export HAN VADER LUKE
229 %help
231 This is a text file to be displayed with the run-help command.
232 COMMANDS:
234 Build a sif file from an Apptainer recipe file:
236 $ apptainer build /tmp/debian0.sif /path/to/debian.def
237 Build a sif image from the Library:
239 $ apptainer build /tmp/debian1.sif library://debian:latest
240 Build a base sandbox from DockerHub, make changes to it, then build sif
242 $ apptainer build --sandbox /tmp/debian docker://debian:latest
243 $ apptainer exec --writable /tmp/debian apt-get install python
244 $ apptainer build /tmp/debian2.sif /tmp/debian
245
250 apptainer(1)
251
255 22-Jun-2022 Auto generated by spf13/cobra
256Auto generated by spf13/cobra Jun 2022 apptainer(1)