1CONTAINERFILE(5) Container User Manuals CONTAINERFILE(5)
2
6 Containerfile(Dockerfile) - automate the steps of creating a container
7 image
8
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 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 Dockerfile is an alternate name for the same object. Containerfile and
28 Dockerfile support the same syntax.
29
33 INSTRUCTION arguments
34 For example:
37 FROM image
40
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
50 buildah bud .
51 podman build .
52 -- 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 buildah bud -t repository/tag .
62 podman build -t repository/tag .
63 -- 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 Container engines re-use intermediate images whenever possible. This
76 significantly
77 accelerates the build process.
78
82 FROM image
83 FROM image:tag
86 FROM image@digest
89 -- The FROM instruction sets the base image for subsequent instruc‐
92 tions. A
93 valid Containerfile must have either ARG or *FROM** as its first in‐
94 struction.
95 If FROM is not the first instruction in the file, it may only be pre‐
96 ceded by
97 one or more ARG instructions, which declare arguments that are used
98 in the next FROM line in the Containerfile.
99 The image can be any valid image. It is easy to start by pulling an
100 image from the public
101 repositories.
102 -- FROM must appear at least once in the Containerfile.
105 -- FROM The first FROM command must come before all other instructions
108 in
109 the Containerfile except ARG
110 -- FROM may appear multiple times within a single Containerfile in or‐
113 der to create
114 multiple images. Make a note of the last image ID output by the com‐
115 mit before
116 each new FROM command.
117 -- If no tag is given to the FROM instruction, container engines apply
120 the
121 latest tag. If the used tag does not exist, an error is returned.
122 -- If no digest is given to the FROM instruction, container engines ap‐
125 ply the
126 latest tag. If the used tag does not exist, an error is returned.
127 MAINTAINER
130 -- MAINTAINER sets the Author field for the generated images.
131 Useful for providing users with an email or url for support.
132 RUN
135 -- RUN has two forms:
136 # the command is run in a shell - /bin/sh -c
139 RUN <command>
140 # Executable form
142 RUN ["executable", "param1", "param2"]
143 RUN mounts
147 --mount=type=TYPE,TYPE-SPECIFIC-OPTION[,...]
150 Attach a filesystem mount to the container
153 Current supported mount TYPES are bind, cache, secret and tmpfs.
156 e.g.
159 mount=type=bind,source=/path/on/host,destination=/path/in/container
161 mount=type=tmpfs,tmpfs-size=512M,destination=/path/in/container
163 mount=type=secret,id=mysecret cat /run/secrets/mysecret
165 Common Options:
167 · src, source: mount source spec for bind and volume. Mandatory for bind. If `from` is specified, `src` is the subpath in the `from` field.
169 · dst, destination, target: mount destination spec.
171 · ro, read-only: true (default) or false.
173 Options specific to bind:
175 · bind-propagation: shared, slave, private, rshared, rslave, or rprivate(default). See also mount(2).
177 . bind-nonrecursive: do not setup a recursive bind mount. By default it is recursive.
179 · from: stage or image name for the root of the source. Defaults to the build context.
181 · rw, read-write: allows writes on the mount.
183 Options specific to tmpfs:
185 · tmpfs-size: Size of the tmpfs mount in bytes. Unlimited by default in Linux.
187 · tmpfs-mode: File mode of the tmpfs in octal. (e.g. 700 or 0700.) Defaults to 1777 in Linux.
189 · tmpcopyup: Path that is shadowed by the tmpfs mount is recursively copied up to the tmpfs itself.
191 Options specific to cache:
193 · id: Create a separate cache directory for a particular id.
195 · mode: File mode for new cache directory in octal. Default 0755.
197 · ro, readonly: read only cache if set.
199 · uid: uid for cache directory.
201 · gid: gid for cache directory.
203 · from: stage name for the root of the source. Defaults to host cache directory.
205 · rw, read-write: allows writes on the mount.
207 RUN Secrets
211 The RUN command has a feature to allow the passing of secret informa‐
214 tion into the image build. These secrets files can be used during the
215 RUN command but are not committed to the final image. The RUN command
216 supports the --mount option to identify the secret file. A secret file
217 from the host is mounted into the container while the image is being
218 built.
219 Container engines pass secret the secret file into the build using the
222 --secret flag.
223 --mount=type=secret,TYPE-SPECIFIC-OPTION[,...]
226 • id is the identifier for the secret passed into the buildah
229 bud --secret or podman build --secret. This identifier is as‐
230 sociated with the RUN --mount identifier to use in the Con‐
231 tainerfile.
232 • dst|target|destination rename the secret file to a specific
234 file in the Containerfile RUN command to use.
235 • type=secret tells the --mount command that it is mounting in a
237 secret file
238 # shows secret from default secret location:
240 RUN --mount=type=secret,id=mysecret cat /run/secrets/mysecret
241 # shows secret from custom secret location:
245 RUN --mount=type=secret,id=mysecret,dst=/foobar cat /foobar
246 The secret needs to be passed to the build using the --secret flag. The
252 final image built does not container the secret file:
253 buildah bud --no-cache --secret id=mysecret,src=mysecret.txt .
256 -- The RUN instruction executes any commands in a new layer on top of
260 the current
261 image and commits the results. The committed image is used for the
262 next step in
263 Containerfile.
264 -- Layering RUN instructions and generating commits conforms to the
267 core
268 concepts of container engines where commits are cheap and containers
269 can be created from
270 any point in the history of an image. This is similar to source con‐
271 trol. The
272 exec form makes it possible to avoid shell string munging. The exec
273 form makes
274 it possible to RUN commands using a base image that does not contain
275 /bin/sh.
276 Note that the exec form is parsed as a JSON array, which means that you
279 must
280 use double-quotes (") around words, not single-quotes (').
281 CMD
284 -- CMD has three forms:
285 # Executable form
288 CMD ["executable", "param1", "param2"]`
289 # Provide default arguments to ENTRYPOINT
291 CMD ["param1", "param2"]`
292 # the command is run in a shell - /bin/sh -c
294 CMD command param1 param2
295 -- There should be only one CMD in a Containerfile. If more than one
299 CMD is listed, only
300 the last CMD takes effect.
301 The main purpose of a CMD is to provide defaults for an executing
302 container.
303 These defaults may include an executable, or they can omit the exe‐
304 cutable. If
305 they omit the executable, an ENTRYPOINT must be specified.
306 When used in the shell or exec formats, the CMD instruction sets the
307 command to
308 be executed when running the image.
309 If you use the shell form of the CMD, the <command> executes in
310 /bin/sh -c:
311 Note that the exec form is parsed as a JSON array, which means that you
314 must
315 use double-quotes (") around words, not single-quotes (').
316 FROM ubuntu
319 CMD echo "This is a test." | wc -
320 -- If you run command without a shell, then you must express the com‐
324 mand as a
325 JSON array and give the full path to the executable. This array form
326 is the
327 preferred form of CMD. All additional parameters must be individually
328 expressed
329 as strings in the array:
330 FROM ubuntu
333 CMD ["/usr/bin/wc","--help"]
334 -- To make the container run the same executable every time, use ENTRY‐
338 POINT in
339 combination with CMD.
340 If the user specifies arguments to podman run or docker run, the
341 specified commands
342 override the default in CMD.
343 Do not confuse RUN with CMD. RUN runs a command and commits the re‐
344 sult.
345 CMD executes nothing at build time, but specifies the intended com‐
346 mand for
347 the image.
348 LABEL
351 -- LABEL <key>=<value> [<key>=<value> ...]or
352 LABEL <key>[ <value>]
355 LABEL <key>[ <value>]
356 ...
357 The LABEL instruction adds metadata to an image. A LABEL is a
361 key-value pair. To specify a LABEL without a value, simply use an
362 empty
363 string. To include spaces within a LABEL value, use quotes and
364 backslashes as you would in command-line parsing.
365 LABEL com.example.vendor="ACME Incorporated"
368 LABEL com.example.vendor "ACME Incorporated"
369 LABEL com.example.vendor.is-beta ""
370 LABEL com.example.vendor.is-beta=
371 LABEL com.example.vendor.is-beta=""
372 An image can have more than one label. To specify multiple labels, sep‐
376 arate
377 each key-value pair by a space.
378 Labels are additive including LABELs in FROM images. As the system
381 encounters and then applies a new label, new keys override any previ‐
382 ous
383 labels with identical keys.
384 To display an image's labels, use the buildah inspect command.
387 EXPOSE
390 -- EXPOSE <port> [<port>...]
391 The EXPOSE instruction informs the container engine that the con‐
392 tainer listens on the
393 specified network ports at runtime. The container engine uses this
394 information to
395 interconnect containers using links and to set up port redirection on
396 the host
397 system.
398 ENV
401 -- ENV <key> <value>
402 The ENV instruction sets the environment variable to
403 the value <value>. This value is passed to all future
404 RUN, ENTRYPOINT, and CMD instructions. This is
405 functionally equivalent to prefixing the command with <key>=<value>.
406 The
407 environment variables that are set with ENV persist when a container
408 is run
409 from the resulting image. Use podman inspect to inspect these values,
410 and
411 change them using podman run --env <key>=<value>.
412 Note that setting "ENV DEBIAN_FRONTEND=noninteractive" may cause
415 unintended consequences, because it will persist when the container
416 is run
417 interactively, as with the following command: podman run -t -i image
418 bash
419 ADD
422 -- ADD has two forms:
423 ADD <src> <dest>
426 # Required for paths with whitespace
428 ADD ["<src>",... "<dest>"]
429 The ADD instruction copies new files, directories
433 or remote file URLs to the filesystem of the container at path
434 <dest>.
435 Multiple <src> resources may be specified but if they are files or
436 directories
437 then they must be relative to the source directory that is being
438 built
439 (the context of the build). The <dest> is the absolute path, or path
440 relative
441 to WORKDIR, into which the source is copied inside the target con‐
442 tainer.
443 If the <src> argument is a local file in a recognized compression
444 format
445 (tar, gzip, bzip2, etc) then it is unpacked at the specified <dest>
446 in the
447 container's filesystem. Note that only local compressed files will
448 be unpacked,
449 i.e., the URL download and archive unpacking features cannot be used
450 together.
451 All new directories are created with mode 0755 and with the uid and
452 gid of 0.
453 COPY
456 -- COPY has two forms:
457 COPY <src> <dest>
460 # Required for paths with whitespace
462 COPY ["<src>",... "<dest>"]
463 The COPY instruction copies new files from <src> and
467 adds them to the filesystem of the container at path . The <src> must
468 be
469 the path to a file or directory relative to the source directory that
470 is
471 being built (the context of the build) or a remote file URL. The
472 <dest> is an
473 absolute path, or a path relative to WORKDIR, into which the source
474 will
475 be copied inside the target container. If you COPY an archive file it
476 will
477 land in the container exactly as it appears in the build context
478 without any
479 attempt to unpack it. All new files and directories are created with
480 mode 0755
481 and with the uid and gid of 0.
482 ENTRYPOINT
485 -- ENTRYPOINT has two forms:
486 # executable form
489 ENTRYPOINT ["executable", "param1", "param2"]`
490 # run command in a shell - /bin/sh -c
492 ENTRYPOINT command param1 param2
493 -- An ENTRYPOINT helps you configure a
497 container that can be run as an executable. When you specify an EN‐
498 TRYPOINT,
499 the whole container runs as if it was only that executable. The EN‐
500 TRYPOINT
501 instruction adds an entry command that is not overwritten when argu‐
502 ments are
503 passed to podman run. This is different from the behavior of CMD.
504 This allows
505 arguments to be passed to the entrypoint, for instance podman run
506 <image> -d
507 passes the -d argument to the ENTRYPOINT. Specify parameters either
508 in the
509 ENTRYPOINT JSON array (as in the preferred exec form above), or by
510 using a CMD
511 statement. Parameters in the ENTRYPOINT are not overwritten by the
512 podman run arguments. Parameters specified via CMD are overwritten by
513 podman run arguments. Specify a plain string for the ENTRYPOINT, and
514 it will execute in
515 /bin/sh -c, like a CMD instruction:
516 FROM ubuntu
519 ENTRYPOINT wc -l -
520 This means that the Containerfile's image always takes stdin as input
524 (that's
525 what "-" means), and prints the number of lines (that's what "-l"
526 means). To
527 make this optional but default, use a CMD:
528 FROM ubuntu
531 CMD ["-l", "-"]
532 ENTRYPOINT ["/usr/bin/wc"]
533 VOLUME
537 -- VOLUME ["/data"]
538 The VOLUME instruction creates a mount point with the specified name
539 and marks
540 it as holding externally-mounted volumes from the native host or from
541 other
542 containers.
543 USER
546 -- USER daemon
547 Sets the username or UID used for running subsequent commands.
548 The USER instruction can optionally be used to set the group or GID.
551 The
552 following examples are all valid:
553 USER [user | user:group | uid | uid:gid | user:gid | uid:group ]
554 Until the USER instruction is set, instructions will be run as root.
557 The USER
558 instruction can be used any number of times in a Containerfile, and
559 will only affect
560 subsequent commands.
561 WORKDIR
564 -- WORKDIR /path/to/workdir
565 The WORKDIR instruction sets the working directory for the RUN, CMD,
566 ENTRYPOINT, COPY and ADD Containerfile commands that follow it. It
567 can
568 be used multiple times in a single Containerfile. Relative paths are
569 defined
570 relative to the path of the previous WORKDIR instruction. For exam‐
571 ple:
572 WORKDIR /a
575 WORKDIR b
576 WORKDIR c
577 RUN pwd
578 In the above example, the output of the pwd command is a/b/c.
582 ARG
585 -- ARG [=]
586 The ARG instruction defines a variable that users can pass at build-
589 time to
590 the builder with the podman build and buildah build commands using
591 the
592 --build-arg <varname>=<value> flag. If a user specifies a build argu‐
593 ment that
594 was not defined in the Containerfile, the build outputs a warning.
595 Note that a second FROM in a Containerfile sets the values associated
598 with an
599 Arg variable to nil and they must be reset if they are to be used
600 later in
601 the Containerfile
602 [Warning] One or more build-args [foo] were not consumed
605 The Containerfile author can define a single variable by specifying ARG
609 once or many
610 variables by specifying ARG more than once. For example, a valid Con‐
611 tainerfile:
612 FROM busybox
615 ARG user1
616 ARG buildno
617 ...
618 A Containerfile author may optionally specify a default value for an
622 ARG instruction:
623 FROM busybox
626 ARG user1=someuser
627 ARG buildno=1
628 ...
629 If an ARG value has a default and if there is no value passed at build-
633 time, the
634 builder uses the default.
635 An ARG variable definition comes into effect from the line on which it
638 is
639 defined in the Containerfile not from the argument's use on the com‐
640 mand-line or
641 elsewhere. For example, consider this Containerfile:
642 1 FROM busybox
645 2 USER ${user:-some_user}
646 3 ARG user
647 4 USER $user
648 ...
649 A user builds this file by calling:
653 $ podman build --build-arg user=what_user Containerfile
656 The USER at line 2 evaluates to some_user as the user variable is de‐
660 fined on the
661 subsequent line 3. The USER at line 4 evaluates to what_user as user
662 is
663 defined and the what_user value was passed on the command line. Prior
664 to its definition by an
665 ARG instruction, any use of a variable results in an empty string.
666 Warning: It is not recommended to use build-time variables for
669 passing secrets like github keys, user credentials etc. Build-
670 time variable
671 values are visible to any user of the image with the podman
672 history command.
673 You can use an ARG or an ENV instruction to specify variables that are
677 available to the RUN instruction. Environment variables defined using
678 the
679 ENV instruction always override an ARG instruction of the same name.
680 Consider
681 this Containerfile with an ENV and ARG instruction.
682 1 FROM ubuntu
685 2 ARG CONT_IMG_VER
686 3 ENV CONT_IMG_VER=v1.0.0
687 4 RUN echo $CONT_IMG_VER
688 Then, assume this image is built with this command:
692 $ podman build --build-arg CONT_IMG_VER=v2.0.1 Containerfile
695 In this case, the RUN instruction uses v1.0.0 instead of the ARG set‐
699 ting
700 passed by the user:v2.0.1 This behavior is similar to a shell
701 script where a locally scoped variable overrides the variables passed
702 as
703 arguments or inherited from environment, from its point of defini‐
704 tion.
705 Using the example above but a different ENV specification you can cre‐
708 ate more
709 useful interactions between ARG and ENV instructions:
710 1 FROM ubuntu
713 2 ARG CONT_IMG_VER
714 3 ENV CONT_IMG_VER=${CONT_IMG_VER:-v1.0.0}
715 4 RUN echo $CONT_IMG_VER
716 Unlike an ARG instruction, ENV values are always persisted in the built
720 image. Consider a podman build without the --build-arg flag:
721 $ podman build Containerfile
724 Using this Containerfile example, CONT_IMG_VER is still persisted in
728 the image but
729 its value would be v1.0.0 as it is the default set in line 3 by the
730 ENV instruction.
731 The variable expansion technique in this example allows you to pass ar‐
734 guments
735 from the command line and persist them in the final image by leverag‐
736 ing the
737 ENV instruction. Variable expansion is only supported for a limited
738 set of
739 Containerfile instructions. ⟨#environment-replacement⟩
740 Container engines have a set of predefined ARG variables that you can
743 use without a
744 corresponding ARG instruction in the Containerfile.
745 • HTTP_PROXY
748 • http_proxy
750 • HTTPS_PROXY
752 • https_proxy
754 • FTP_PROXY
756 • ftp_proxy
758 • NO_PROXY
760 • no_proxy
762 • ALL_PROXY
764 • all_proxy
766 To use these, pass them on the command line using --build-arg flag, for
770 example:
771 $ podman build --build-arg HTTPS_PROXY=https://my-proxy.example.com .
774 ONBUILD
778 -- ONBUILD [INSTRUCTION]
779 The ONBUILD instruction adds a trigger instruction to an image. The
780 trigger is executed at a later time, when the image is used as the
781 base for
782 another build. Container engines execute the trigger in the context
783 of the downstream
784 build, as if the trigger existed immediately after the FROM instruc‐
785 tion in
786 the downstream Containerfile.
787 You can register any build instruction as a trigger. A trigger is use‐
790 ful if
791 you are defining an image to use as a base for building other images.
792 For
793 example, if you are defining an application build environment or a
794 daemon that
795 is customized with a user-specific configuration.
796 Consider an image intended as a reusable python application builder. It
799 must
800 add application source code to a particular directory, and might need
801 a build
802 script called after that. You can't just call ADD and RUN now, be‐
803 cause
804 you don't yet have access to the application source code, and it is
805 different
806 for each application build.
807 -- Providing application developers with a boilerplate Containerfile to
810 copy-paste
811 into their application is inefficient, error-prone, and
812 difficult to update because it mixes with application-specific code.
813 The solution is to use ONBUILD to register instructions in advance,
814 to
815 run later, during the next build stage.
816
819 buildah(1), podman(1), docker(1)
820
824 May 2014, Compiled by Zac Dover (zdover at redhat dot com) based on docker.com Dockerfile documentation.
825 Feb 2015, updated by Brian Goff (cpuguy83@gmail.com) for readability
826 Sept 2015, updated by Sally O'Malley (somalley@redhat.com)
827 Oct 2016, updated by Addam Hardy (addam.hardy@gmail.com)
828 Aug 2021, converted Dockerfile man page to Containerfile by Dan Walsh (dwalsh@redhat.com)
829 Aug 2021 CONTAINERFILE(5)