1CONTAINERFILE(5) Container User Manuals CONTAINERFILE(5)
2
3
4
6 Containerfile(Dockerfile) - automate the steps of creating a container
7 image
8
9
10
12 The Containerfile is a configuration file that automates the steps of
13 creating a container image. It is similar to a Makefile. Container en‐
14 gines (Podman, Buildah, Docker) read instructions from the Container‐
15 file to automate the steps otherwise performed manually to create an
16 image. To build an image, create a file called Containerfile.
17
18
19 The Containerfile describes the steps taken to assemble the image. When
20 the Containerfile has been created, call the buildah bud, podman build,
21 docker build command, using the path of context directory that contains
22 Containerfile as the argument. Podman and Buildah default to Container‐
23 file and will fall back to Dockerfile. Docker only will search for
24 Dockerfile in the context directory.
25
26
27 Dockerfile is an alternate name for the same object. Containerfile and
28 Dockerfile support the same syntax.
29
30
31
33 INSTRUCTION arguments
34
35
36 For example:
37
38
39 FROM image
40
41
42
44 A Containerfile is a file that automates the steps of creating a con‐
45 tainer image. A Containerfile is similar to a Makefile.
46
47
48
50 buildah bud .
51 podman build .
52
53
54
55 -- Runs the steps and commits them, building a final image.
56 The path to the source repository defines where to find the context
57 of the
58 build.
59
60
61 buildah bud -t repository/tag .
62 podman build -t repository/tag .
63
64
65
66 -- specifies a repository and tag at which to save the new image if the
67 build
68 succeeds. The container engine runs the steps one-by-one, committing
69 the result
70 to a new image if necessary, before finally outputting the ID of the
71 new
72 image.
73
74
75 Container engines re-use intermediate images whenever possible. This
76 significantly
77 accelerates the build process.
78
79
80
82 FROM image
83
84
85 FROM image:tag
86
87
88 FROM image@digest
89
90
91 -- The FROM instruction sets the base image for subsequent instruc‐
92 tions. A
93 valid Containerfile must have FROM as its first instruction. The im‐
94 age can be any
95 valid image. It is easy to start by pulling an image from the public
96 repositories.
97
98
99 -- FROM must appear at least once in the Containerfile.
100
101
102 -- FROM The first FROM command must come before all other instructions
103 in
104 the Containerfile except ARG
105
106
107 -- FROM may appear multiple times within a single Containerfile in or‐
108 der to create
109 multiple images. Make a note of the last image ID output by the com‐
110 mit before
111 each new FROM command.
112
113
114 -- If no tag is given to the FROM instruction, container engines apply
115 the
116 latest tag. If the used tag does not exist, an error is returned.
117
118
119 -- If no digest is given to the FROM instruction, container engines ap‐
120 ply the
121 latest tag. If the used tag does not exist, an error is returned.
122
123
124 MAINTAINER
125 -- MAINTAINER sets the Author field for the generated images.
126 Useful for providing users with an email or url for support.
127
128
129 RUN
130 -- RUN has two forms:
131
132
133 # the command is run in a shell - /bin/sh -c
134 RUN <command>
135
136 # Executable form
137 RUN ["executable", "param1", "param2"]
138
139
140
141 *RUN Secrets
142
143
144 The RUN command has a feature to allow the passing of secret informa‐
145 tion into the image build. These secrets files can be used during the
146 RUN command but are not committed to the final image. The RUN command
147 supports the --mount option to identify the secret file. A secret file
148 from the host is mounted into the container while the image is being
149 built.
150
151
152 Container engines pass secret the secret file into the build using the
153 --secret flag.
154
155
156 *RUN --mount options:
157
158
159 • id is the identifier to for the secret passed into the buildah
160 bud --secret or podman build --secret. This identifier is as‐
161 sociated with the RUN --mount identifier to use in the Con‐
162 tainerfile.
163
164 • dst|target|destination rename the secret file to a specific
165 file in the Containerfile RUN command to use.
166
167 • type=secret tells the --mount command that it is mounting in a
168 secret file
169
170 # shows secret from default secret location:
171 RUN --mount=type=secret,id=mysecret cat /run/secrets/mysecret
172
173
174
175 # shows secret from custom secret location:
176 RUN --mount=type=secret,id=mysecret,dst=/foobar cat /foobar
177
178
179
180
181
182 The secret needs to be passed to the build using the --secret flag. The
183 final image built does not container the secret file:
184
185
186 buildah bud --no-cache --secret id=mysecret,src=mysecret.txt .
187
188
189
190 -- The RUN instruction executes any commands in a new layer on top of
191 the current
192 image and commits the results. The committed image is used for the
193 next step in
194 Containerfile.
195
196
197 -- Layering RUN instructions and generating commits conforms to the
198 core
199 concepts of container engines where commits are cheap and containers
200 can be created from
201 any point in the history of an image. This is similar to source con‐
202 trol. The
203 exec form makes it possible to avoid shell string munging. The exec
204 form makes
205 it possible to RUN commands using a base image that does not contain
206 /bin/sh.
207
208
209 Note that the exec form is parsed as a JSON array, which means that you
210 must
211 use double-quotes (") around words not single-quotes (').
212
213
214 CMD
215 -- CMD has three forms:
216
217
218 # Executable form
219 CMD ["executable", "param1", "param2"]`
220
221 # Provide default arguments to ENTRYPOINT
222 CMD ["param1", "param2"]`
223
224 # the command is run in a shell - /bin/sh -c
225 CMD command param1 param2
226
227
228
229 -- There should be only one CMD in a Containerfile. If more than one
230 CMD is listed, only
231 the last CMD takes effect.
232 The main purpose of a CMD is to provide defaults for an executing
233 container.
234 These defaults may include an executable, or they can omit the exe‐
235 cutable. If
236 they omit the executable, an ENTRYPOINT must be specified.
237 When used in the shell or exec formats, the CMD instruction sets the
238 command to
239 be executed when running the image.
240 If you use the shell form of the CMD, the <command> executes in
241 /bin/sh -c:
242
243
244 Note that the exec form is parsed as a JSON array, which means that you
245 must
246 use double-quotes (") around words not single-quotes (').
247
248
249 FROM ubuntu
250 CMD echo "This is a test." | wc -
251
252
253
254 -- If you run command without a shell, then you must express the com‐
255 mand as a
256 JSON array and give the full path to the executable. This array form
257 is the
258 preferred form of CMD. All additional parameters must be individually
259 expressed
260 as strings in the array:
261
262
263 FROM ubuntu
264 CMD ["/usr/bin/wc","--help"]
265
266
267
268 -- To make the container run the same executable every time, use ENTRY‐
269 POINT in
270 combination with CMD.
271 If the user specifies arguments to podman run or docker run, the
272 specified commands
273 override the default in CMD.
274 Do not confuse RUN with CMD. RUN runs a command and commits the re‐
275 sult.
276 CMD executes nothing at build time, but specifies the intended com‐
277 mand for
278 the image.
279
280
281 LABEL
282 -- LABEL <key>=<value> [<key>=<value> ...]or
283
284
285 LABEL <key>[ <value>]
286 LABEL <key>[ <value>]
287 ...
288
289
290
291 The LABEL instruction adds metadata to an image. A LABEL is a
292 key-value pair. To specify a LABEL without a value, simply use an
293 empty
294 string. To include spaces within a LABEL value, use quotes and
295 backslashes as you would in command-line parsing.
296
297
298 LABEL com.example.vendor="ACME Incorporated"
299 LABEL com.example.vendor "ACME Incorporated"
300 LABEL com.example.vendor.is-beta ""
301 LABEL com.example.vendor.is-beta=
302 LABEL com.example.vendor.is-beta=""
303
304
305
306 An image can have more than one label. To specify multiple labels, sep‐
307 arate
308 each key-value pair by a space.
309
310
311 Labels are additive including LABELs in FROM images. As the system
312 encounters and then applies a new label, new keys override any previ‐
313 ous
314 labels with identical keys.
315
316
317 To display an image's labels, use the buildah inspect command.
318
319
320 EXPOSE
321 -- EXPOSE <port> [<port>...]
322 The EXPOSE instruction informs the container engine that the con‐
323 tainer listens on the
324 specified network ports at runtime. The container engine uses this
325 information to
326 interconnect containers using links and to set up port redirection on
327 the host
328 system.
329
330
331 ENV
332 -- ENV <key> <value>
333 The ENV instruction sets the environment variable to
334 the value <value>. This value is passed to all future
335 RUN, ENTRYPOINT, and CMD instructions. This is
336 functionally equivalent to prefixing the command with <key>=<value>.
337 The
338 environment variables that are set with ENV persist when a container
339 is run
340 from the resulting image. Use podman inspect to inspect these values,
341 and
342 change them using podman run --env <key>=<value>.
343
344
345 Note that setting "ENV DEBIAN_FRONTEND=noninteractive" may cause
346 unintended consequences, because it will persist when the container
347 is run
348 interactively, as with the following command: podman run -t -i image
349 bash
350
351
352 ADD
353 -- ADD has two forms:
354
355
356 ADD <src> <dest>
357
358 # Required for paths with whitespace
359 ADD ["<src>",... "<dest>"]
360
361
362
363 The ADD instruction copies new files, directories
364 or remote file URLs to the filesystem of the container at path
365 <dest>.
366 Multiple <src> resources may be specified but if they are files or
367 directories
368 then they must be relative to the source directory that is being
369 built
370 (the context of the build). The <dest> is the absolute path, or path
371 relative
372 to WORKDIR, into which the source is copied inside the target con‐
373 tainer.
374 If the <src> argument is a local file in a recognized compression
375 format
376 (tar, gzip, bzip2, etc) then it is unpacked at the specified <dest>
377 in the
378 container's filesystem. Note that only local compressed files will
379 be unpacked,
380 i.e., the URL download and archive unpacking features cannot be used
381 together.
382 All new directories are created with mode 0755 and with the uid and
383 gid of 0.
384
385
386 COPY
387 -- COPY has two forms:
388
389
390 COPY <src> <dest>
391
392 # Required for paths with whitespace
393 COPY ["<src>",... "<dest>"]
394
395
396
397 The COPY instruction copies new files from <src> and
398 adds them to the filesystem of the container at path . The <src> must
399 be
400 the path to a file or directory relative to the source directory that
401 is
402 being built (the context of the build) or a remote file URL. The
403 <dest> is an
404 absolute path, or a path relative to WORKDIR, into which the source
405 will
406 be copied inside the target container. If you COPY an archive file it
407 will
408 land in the container exactly as it appears in the build context
409 without any
410 attempt to unpack it. All new files and directories are created with
411 mode 0755
412 and with the uid and gid of 0.
413
414
415 ENTRYPOINT
416 -- ENTRYPOINT has two forms:
417
418
419 # executable form
420 ENTRYPOINT ["executable", "param1", "param2"]`
421
422 # run command in a shell - /bin/sh -c
423 ENTRYPOINT command param1 param2
424
425
426
427 -- An ENTRYPOINT helps you configure a
428 container that can be run as an executable. When you specify an EN‐
429 TRYPOINT,
430 the whole container runs as if it was only that executable. The EN‐
431 TRYPOINT
432 instruction adds an entry command that is not overwritten when argu‐
433 ments are
434 passed to podman run. This is different from the behavior of CMD.
435 This allows
436 arguments to be passed to the entrypoint, for instance podman run
437 <image> -d
438 passes the -d argument to the ENTRYPOINT. Specify parameters either
439 in the
440 ENTRYPOINT JSON array (as in the preferred exec form above), or by
441 using a CMD
442 statement. Parameters in the ENTRYPOINT are not overwritten by the
443 podman run arguments. Parameters specified via CMD are overwritten by
444 podman run arguments. Specify a plain string for the ENTRYPOINT, and
445 it will execute in
446 /bin/sh -c, like a CMD instruction:
447
448
449 FROM ubuntu
450 ENTRYPOINT wc -l -
451
452
453
454 This means that the Containerfile's image always takes stdin as input
455 (that's
456 what "-" means), and prints the number of lines (that's what "-l"
457 means). To
458 make this optional but default, use a CMD:
459
460
461 FROM ubuntu
462 CMD ["-l", "-"]
463 ENTRYPOINT ["/usr/bin/wc"]
464
465
466
467 VOLUME
468 -- VOLUME ["/data"]
469 The VOLUME instruction creates a mount point with the specified name
470 and marks
471 it as holding externally-mounted volumes from the native host or from
472 other
473 containers.
474
475
476 USER
477 -- USER daemon
478 Sets the username or UID used for running subsequent commands.
479
480
481 The USER instruction can optionally be used to set the group or GID.
482 The
483 following examples are all valid:
484 USER [user | user:group | uid | uid:gid | user:gid | uid:group ]
485
486
487 Until the USER instruction is set, instructions will be run as root.
488 The USER
489 instruction can be used any number of times in a Containerfile, and
490 will only affect
491 subsequent commands.
492
493
494 WORKDIR
495 -- WORKDIR /path/to/workdir
496 The WORKDIR instruction sets the working directory for the RUN, CMD,
497 ENTRYPOINT, COPY and ADD Containerfile commands that follow it. It
498 can
499 be used multiple times in a single Containerfile. Relative paths are
500 defined
501 relative to the path of the previous WORKDIR instruction. For exam‐
502 ple:
503
504
505 WORKDIR /a
506 WORKDIR b
507 WORKDIR c
508 RUN pwd
509
510
511
512 In the above example, the output of the pwd command is a/b/c.
513
514
515 ARG
516 -- ARG [=]
517
518
519 The ARG instruction defines a variable that users can pass at build-
520 time to
521 the builder with the podman build and buildah build commands using
522 the
523 --build-arg <varname>=<value> flag. If a user specifies a build argu‐
524 ment that
525 was not defined in the Containerfile, the build outputs a warning.
526
527
528 Note that a second FROM in a Containerfile sets the values associated
529 with an
530 Arg variable to nil and they must be reset if they are to be used
531 later in
532 the Containerfile
533
534
535 [Warning] One or more build-args [foo] were not consumed
536
537
538
539 The Containerfile author can define a single variable by specifying ARG
540 once or many
541 variables by specifying ARG more than once. For example, a valid Con‐
542 tainerfile:
543
544
545 FROM busybox
546 ARG user1
547 ARG buildno
548 ...
549
550
551
552 A Containerfile author may optionally specify a default value for an
553 ARG instruction:
554
555
556 FROM busybox
557 ARG user1=someuser
558 ARG buildno=1
559 ...
560
561
562
563 If an ARG value has a default and if there is no value passed at build-
564 time, the
565 builder uses the default.
566
567
568 An ARG variable definition comes into effect from the line on which it
569 is
570 defined in the Containerfile not from the argument's use on the com‐
571 mand-line or
572 elsewhere. For example, consider this Containerfile:
573
574
575 1 FROM busybox
576 2 USER ${user:-some_user}
577 3 ARG user
578 4 USER $user
579 ...
580
581
582
583 A user builds this file by calling:
584
585
586 $ podman build --build-arg user=what_user Containerfile
587
588
589
590 The USER at line 2 evaluates to some_user as the user variable is de‐
591 fined on the
592 subsequent line 3. The USER at line 4 evaluates to what_user as user
593 is
594 defined and the what_user value was passed on the command line. Prior
595 to its definition by an
596 ARG instruction, any use of a variable results in an empty string.
597
598
599 Warning: It is not recommended to use build-time variables for
600 passing secrets like github keys, user credentials etc. Build-
601 time variable
602 values are visible to any user of the image with the podman
603 history command.
604
605
606
607 You can use an ARG or an ENV instruction to specify variables that are
608 available to the RUN instruction. Environment variables defined using
609 the
610 ENV instruction always override an ARG instruction of the same name.
611 Consider
612 this Containerfile with an ENV and ARG instruction.
613
614
615 1 FROM ubuntu
616 2 ARG CONT_IMG_VER
617 3 ENV CONT_IMG_VER=v1.0.0
618 4 RUN echo $CONT_IMG_VER
619
620
621
622 Then, assume this image is built with this command:
623
624
625 $ podman build --build-arg CONT_IMG_VER=v2.0.1 Containerfile
626
627
628
629 In this case, the RUN instruction uses v1.0.0 instead of the ARG set‐
630 ting
631 passed by the user:v2.0.1 This behavior is similar to a shell
632 script where a locally scoped variable overrides the variables passed
633 as
634 arguments or inherited from environment, from its point of defini‐
635 tion.
636
637
638 Using the example above but a different ENV specification you can cre‐
639 ate more
640 useful interactions between ARG and ENV instructions:
641
642
643 1 FROM ubuntu
644 2 ARG CONT_IMG_VER
645 3 ENV CONT_IMG_VER=${CONT_IMG_VER:-v1.0.0}
646 4 RUN echo $CONT_IMG_VER
647
648
649
650 Unlike an ARG instruction, ENV values are always persisted in the built
651 image. Consider a podman build without the --build-arg flag:
652
653
654 $ podman build Containerfile
655
656
657
658 Using this Containerfile example, CONT_IMG_VER is still persisted in
659 the image but
660 its value would be v1.0.0 as it is the default set in line 3 by the
661 ENV instruction.
662
663
664 The variable expansion technique in this example allows you to pass ar‐
665 guments
666 from the command line and persist them in the final image by leverag‐
667 ing the
668 ENV instruction. Variable expansion is only supported for a limited
669 set of
670 Containerfile instructions. ⟨#environment-replacement⟩
671
672
673 Container engines have a set of predefined ARG variables that you can
674 use without a
675 corresponding ARG instruction in the Containerfile.
676
677
678 • HTTP_PROXY
679
680 • http_proxy
681
682 • HTTPS_PROXY
683
684 • https_proxy
685
686 • FTP_PROXY
687
688 • ftp_proxy
689
690 • NO_PROXY
691
692 • no_proxy
693
694 • ALL_PROXY
695
696 • all_proxy
697
698
699
700 To use these, pass them on the command line using --build-arg flag, for
701 example:
702
703
704 $ podman build --build-arg HTTPS_PROXY=https://my-proxy.example.com .
705
706
707
708 ONBUILD
709 -- ONBUILD [INSTRUCTION]
710 The ONBUILD instruction adds a trigger instruction to an image. The
711 trigger is executed at a later time, when the image is used as the
712 base for
713 another build. Container engines execute the trigger in the context
714 of the downstream
715 build, as if the trigger existed immediately after the FROM instruc‐
716 tion in
717 the downstream Containerfile.
718
719
720 You can register any build instruction as a trigger. A trigger is use‐
721 ful if
722 you are defining an image to use as a base for building other images.
723 For
724 example, if you are defining an application build environment or a
725 daemon that
726 is customized with a user-specific configuration.
727
728
729 Consider an image intended as a reusable python application builder. It
730 must
731 add application source code to a particular directory, and might need
732 a build
733 script called after that. You can't just call ADD and RUN now, be‐
734 cause
735 you don't yet have access to the application source code, and it is
736 different
737 for each application build.
738
739
740 -- Providing application developers with a boilerplate Containerfile to
741 copy-paste
742 into their application is inefficient, error-prone, and
743 difficult to update because it mixes with application-specific code.
744 The solution is to use ONBUILD to register instructions in advance,
745 to
746 run later, during the next build stage.
747
748
750 buildah(1), podman(1), docker(1)
751
752
753
755 May 2014, Compiled by Zac Dover (zdover at redhat dot com) based on docker.com Dockerfile documentation.
756 Feb 2015, updated by Brian Goff (cpuguy83@gmail.com) for readability
757 Sept 2015, updated by Sally O'Malley (somalley@redhat.com)
758 Oct 2016, updated by Addam Hardy (addam.hardy@gmail.com)
759 Aug 2021, converted Dockerfile man page to Containerfile by Dan Walsh (dwalsh@redhat.com)
760
761
762
763
764 Aug 2021 CONTAINERFILE(5)