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 or false (default).
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 Options specific to tmpfs:
183 · tmpfs-size: Size of the tmpfs mount in bytes. Unlimited by default in Linux.
185 · tmpfs-mode: File mode of the tmpfs in octal. (e.g. 700 or 0700.) Defaults to 1777 in Linux.
187 · tmpcopyup: Path that is shadowed by the tmpfs mount is recursively copied up to the tmpfs itself.
189 Options specific to cache:
191 · id: Create a separate cache directory for a particular id.
193 · mode: File mode for new cache directory in octal. Default 0755.
195 · ro, readonly: read only cache if set.
197 · uid: uid for cache directory.
199 · gid: gid for cache directory.
201 · from: stage name for the root of the source. Defaults to host cache directory.
203 RUN Secrets
207 The RUN command has a feature to allow the passing of secret informa‐
210 tion into the image build. These secrets files can be used during the
211 RUN command but are not committed to the final image. The RUN command
212 supports the --mount option to identify the secret file. A secret file
213 from the host is mounted into the container while the image is being
214 built.
215 Container engines pass secret the secret file into the build using the
218 --secret flag.
219 --mount=type=secret,TYPE-SPECIFIC-OPTION[,...]
222 • id is the identifier for the secret passed into the buildah
225 bud --secret or podman build --secret. This identifier is as‐
226 sociated with the RUN --mount identifier to use in the Con‐
227 tainerfile.
228 • dst|target|destination rename the secret file to a specific
230 file in the Containerfile RUN command to use.
231 • type=secret tells the --mount command that it is mounting in a
233 secret file
234 # shows secret from default secret location:
236 RUN --mount=type=secret,id=mysecret cat /run/secrets/mysecret
237 # shows secret from custom secret location:
241 RUN --mount=type=secret,id=mysecret,dst=/foobar cat /foobar
242 The secret needs to be passed to the build using the --secret flag. The
248 final image built does not container the secret file:
249 buildah bud --no-cache --secret id=mysecret,src=mysecret.txt .
252 -- The RUN instruction executes any commands in a new layer on top of
256 the current
257 image and commits the results. The committed image is used for the
258 next step in
259 Containerfile.
260 -- Layering RUN instructions and generating commits conforms to the
263 core
264 concepts of container engines where commits are cheap and containers
265 can be created from
266 any point in the history of an image. This is similar to source con‐
267 trol. The
268 exec form makes it possible to avoid shell string munging. The exec
269 form makes
270 it possible to RUN commands using a base image that does not contain
271 /bin/sh.
272 Note that the exec form is parsed as a JSON array, which means that you
275 must
276 use double-quotes (") around words, not single-quotes (').
277 CMD
280 -- CMD has three forms:
281 # Executable form
284 CMD ["executable", "param1", "param2"]`
285 # Provide default arguments to ENTRYPOINT
287 CMD ["param1", "param2"]`
288 # the command is run in a shell - /bin/sh -c
290 CMD command param1 param2
291 -- There should be only one CMD in a Containerfile. If more than one
295 CMD is listed, only
296 the last CMD takes effect.
297 The main purpose of a CMD is to provide defaults for an executing
298 container.
299 These defaults may include an executable, or they can omit the exe‐
300 cutable. If
301 they omit the executable, an ENTRYPOINT must be specified.
302 When used in the shell or exec formats, the CMD instruction sets the
303 command to
304 be executed when running the image.
305 If you use the shell form of the CMD, the <command> executes in
306 /bin/sh -c:
307 Note that the exec form is parsed as a JSON array, which means that you
310 must
311 use double-quotes (") around words, not single-quotes (').
312 FROM ubuntu
315 CMD echo "This is a test." | wc -
316 -- If you run command without a shell, then you must express the com‐
320 mand as a
321 JSON array and give the full path to the executable. This array form
322 is the
323 preferred form of CMD. All additional parameters must be individually
324 expressed
325 as strings in the array:
326 FROM ubuntu
329 CMD ["/usr/bin/wc","--help"]
330 -- To make the container run the same executable every time, use ENTRY‐
334 POINT in
335 combination with CMD.
336 If the user specifies arguments to podman run or docker run, the
337 specified commands
338 override the default in CMD.
339 Do not confuse RUN with CMD. RUN runs a command and commits the re‐
340 sult.
341 CMD executes nothing at build time, but specifies the intended com‐
342 mand for
343 the image.
344 LABEL
347 -- LABEL <key>=<value> [<key>=<value> ...]or
348 LABEL <key>[ <value>]
351 LABEL <key>[ <value>]
352 ...
353 The LABEL instruction adds metadata to an image. A LABEL is a
357 key-value pair. To specify a LABEL without a value, simply use an
358 empty
359 string. To include spaces within a LABEL value, use quotes and
360 backslashes as you would in command-line parsing.
361 LABEL com.example.vendor="ACME Incorporated"
364 LABEL com.example.vendor "ACME Incorporated"
365 LABEL com.example.vendor.is-beta ""
366 LABEL com.example.vendor.is-beta=
367 LABEL com.example.vendor.is-beta=""
368 An image can have more than one label. To specify multiple labels, sep‐
372 arate
373 each key-value pair by a space.
374 Labels are additive including LABELs in FROM images. As the system
377 encounters and then applies a new label, new keys override any previ‐
378 ous
379 labels with identical keys.
380 To display an image's labels, use the buildah inspect command.
383 EXPOSE
386 -- EXPOSE <port> [<port>...]
387 The EXPOSE instruction informs the container engine that the con‐
388 tainer listens on the
389 specified network ports at runtime. The container engine uses this
390 information to
391 interconnect containers using links and to set up port redirection on
392 the host
393 system.
394 ENV
397 -- ENV <key> <value>
398 The ENV instruction sets the environment variable to
399 the value <value>. This value is passed to all future
400 RUN, ENTRYPOINT, and CMD instructions. This is
401 functionally equivalent to prefixing the command with <key>=<value>.
402 The
403 environment variables that are set with ENV persist when a container
404 is run
405 from the resulting image. Use podman inspect to inspect these values,
406 and
407 change them using podman run --env <key>=<value>.
408 Note that setting "ENV DEBIAN_FRONTEND=noninteractive" may cause
411 unintended consequences, because it will persist when the container
412 is run
413 interactively, as with the following command: podman run -t -i image
414 bash
415 ADD
418 -- ADD has two forms:
419 ADD <src> <dest>
422 # Required for paths with whitespace
424 ADD ["<src>",... "<dest>"]
425 The ADD instruction copies new files, directories
429 or remote file URLs to the filesystem of the container at path
430 <dest>.
431 Multiple <src> resources may be specified but if they are files or
432 directories
433 then they must be relative to the source directory that is being
434 built
435 (the context of the build). The <dest> is the absolute path, or path
436 relative
437 to WORKDIR, into which the source is copied inside the target con‐
438 tainer.
439 If the <src> argument is a local file in a recognized compression
440 format
441 (tar, gzip, bzip2, etc) then it is unpacked at the specified <dest>
442 in the
443 container's filesystem. Note that only local compressed files will
444 be unpacked,
445 i.e., the URL download and archive unpacking features cannot be used
446 together.
447 All new directories are created with mode 0755 and with the uid and
448 gid of 0.
449 COPY
452 -- COPY has two forms:
453 COPY <src> <dest>
456 # Required for paths with whitespace
458 COPY ["<src>",... "<dest>"]
459 The COPY instruction copies new files from <src> and
463 adds them to the filesystem of the container at path . The <src> must
464 be
465 the path to a file or directory relative to the source directory that
466 is
467 being built (the context of the build) or a remote file URL. The
468 <dest> is an
469 absolute path, or a path relative to WORKDIR, into which the source
470 will
471 be copied inside the target container. If you COPY an archive file it
472 will
473 land in the container exactly as it appears in the build context
474 without any
475 attempt to unpack it. All new files and directories are created with
476 mode 0755
477 and with the uid and gid of 0.
478 ENTRYPOINT
481 -- ENTRYPOINT has two forms:
482 # executable form
485 ENTRYPOINT ["executable", "param1", "param2"]`
486 # run command in a shell - /bin/sh -c
488 ENTRYPOINT command param1 param2
489 -- An ENTRYPOINT helps you configure a
493 container that can be run as an executable. When you specify an EN‐
494 TRYPOINT,
495 the whole container runs as if it was only that executable. The EN‐
496 TRYPOINT
497 instruction adds an entry command that is not overwritten when argu‐
498 ments are
499 passed to podman run. This is different from the behavior of CMD.
500 This allows
501 arguments to be passed to the entrypoint, for instance podman run
502 <image> -d
503 passes the -d argument to the ENTRYPOINT. Specify parameters either
504 in the
505 ENTRYPOINT JSON array (as in the preferred exec form above), or by
506 using a CMD
507 statement. Parameters in the ENTRYPOINT are not overwritten by the
508 podman run arguments. Parameters specified via CMD are overwritten by
509 podman run arguments. Specify a plain string for the ENTRYPOINT, and
510 it will execute in
511 /bin/sh -c, like a CMD instruction:
512 FROM ubuntu
515 ENTRYPOINT wc -l -
516 This means that the Containerfile's image always takes stdin as input
520 (that's
521 what "-" means), and prints the number of lines (that's what "-l"
522 means). To
523 make this optional but default, use a CMD:
524 FROM ubuntu
527 CMD ["-l", "-"]
528 ENTRYPOINT ["/usr/bin/wc"]
529 VOLUME
533 -- VOLUME ["/data"]
534 The VOLUME instruction creates a mount point with the specified name
535 and marks
536 it as holding externally-mounted volumes from the native host or from
537 other
538 containers.
539 USER
542 -- USER daemon
543 Sets the username or UID used for running subsequent commands.
544 The USER instruction can optionally be used to set the group or GID.
547 The
548 following examples are all valid:
549 USER [user | user:group | uid | uid:gid | user:gid | uid:group ]
550 Until the USER instruction is set, instructions will be run as root.
553 The USER
554 instruction can be used any number of times in a Containerfile, and
555 will only affect
556 subsequent commands.
557 WORKDIR
560 -- WORKDIR /path/to/workdir
561 The WORKDIR instruction sets the working directory for the RUN, CMD,
562 ENTRYPOINT, COPY and ADD Containerfile commands that follow it. It
563 can
564 be used multiple times in a single Containerfile. Relative paths are
565 defined
566 relative to the path of the previous WORKDIR instruction. For exam‐
567 ple:
568 WORKDIR /a
571 WORKDIR b
572 WORKDIR c
573 RUN pwd
574 In the above example, the output of the pwd command is a/b/c.
578 ARG
581 -- ARG [=]
582 The ARG instruction defines a variable that users can pass at build-
585 time to
586 the builder with the podman build and buildah build commands using
587 the
588 --build-arg <varname>=<value> flag. If a user specifies a build argu‐
589 ment that
590 was not defined in the Containerfile, the build outputs a warning.
591 Note that a second FROM in a Containerfile sets the values associated
594 with an
595 Arg variable to nil and they must be reset if they are to be used
596 later in
597 the Containerfile
598 [Warning] One or more build-args [foo] were not consumed
601 The Containerfile author can define a single variable by specifying ARG
605 once or many
606 variables by specifying ARG more than once. For example, a valid Con‐
607 tainerfile:
608 FROM busybox
611 ARG user1
612 ARG buildno
613 ...
614 A Containerfile author may optionally specify a default value for an
618 ARG instruction:
619 FROM busybox
622 ARG user1=someuser
623 ARG buildno=1
624 ...
625 If an ARG value has a default and if there is no value passed at build-
629 time, the
630 builder uses the default.
631 An ARG variable definition comes into effect from the line on which it
634 is
635 defined in the Containerfile not from the argument's use on the com‐
636 mand-line or
637 elsewhere. For example, consider this Containerfile:
638 1 FROM busybox
641 2 USER ${user:-some_user}
642 3 ARG user
643 4 USER $user
644 ...
645 A user builds this file by calling:
649 $ podman build --build-arg user=what_user Containerfile
652 The USER at line 2 evaluates to some_user as the user variable is de‐
656 fined on the
657 subsequent line 3. The USER at line 4 evaluates to what_user as user
658 is
659 defined and the what_user value was passed on the command line. Prior
660 to its definition by an
661 ARG instruction, any use of a variable results in an empty string.
662 Warning: It is not recommended to use build-time variables for
665 passing secrets like github keys, user credentials etc. Build-
666 time variable
667 values are visible to any user of the image with the podman
668 history command.
669 You can use an ARG or an ENV instruction to specify variables that are
673 available to the RUN instruction. Environment variables defined using
674 the
675 ENV instruction always override an ARG instruction of the same name.
676 Consider
677 this Containerfile with an ENV and ARG instruction.
678 1 FROM ubuntu
681 2 ARG CONT_IMG_VER
682 3 ENV CONT_IMG_VER=v1.0.0
683 4 RUN echo $CONT_IMG_VER
684 Then, assume this image is built with this command:
688 $ podman build --build-arg CONT_IMG_VER=v2.0.1 Containerfile
691 In this case, the RUN instruction uses v1.0.0 instead of the ARG set‐
695 ting
696 passed by the user:v2.0.1 This behavior is similar to a shell
697 script where a locally scoped variable overrides the variables passed
698 as
699 arguments or inherited from environment, from its point of defini‐
700 tion.
701 Using the example above but a different ENV specification you can cre‐
704 ate more
705 useful interactions between ARG and ENV instructions:
706 1 FROM ubuntu
709 2 ARG CONT_IMG_VER
710 3 ENV CONT_IMG_VER=${CONT_IMG_VER:-v1.0.0}
711 4 RUN echo $CONT_IMG_VER
712 Unlike an ARG instruction, ENV values are always persisted in the built
716 image. Consider a podman build without the --build-arg flag:
717 $ podman build Containerfile
720 Using this Containerfile example, CONT_IMG_VER is still persisted in
724 the image but
725 its value would be v1.0.0 as it is the default set in line 3 by the
726 ENV instruction.
727 The variable expansion technique in this example allows you to pass ar‐
730 guments
731 from the command line and persist them in the final image by leverag‐
732 ing the
733 ENV instruction. Variable expansion is only supported for a limited
734 set of
735 Containerfile instructions. ⟨#environment-replacement⟩
736 Container engines have a set of predefined ARG variables that you can
739 use without a
740 corresponding ARG instruction in the Containerfile.
741 • HTTP_PROXY
744 • http_proxy
746 • HTTPS_PROXY
748 • https_proxy
750 • FTP_PROXY
752 • ftp_proxy
754 • NO_PROXY
756 • no_proxy
758 • ALL_PROXY
760 • all_proxy
762 To use these, pass them on the command line using --build-arg flag, for
766 example:
767 $ podman build --build-arg HTTPS_PROXY=https://my-proxy.example.com .
770 ONBUILD
774 -- ONBUILD [INSTRUCTION]
775 The ONBUILD instruction adds a trigger instruction to an image. The
776 trigger is executed at a later time, when the image is used as the
777 base for
778 another build. Container engines execute the trigger in the context
779 of the downstream
780 build, as if the trigger existed immediately after the FROM instruc‐
781 tion in
782 the downstream Containerfile.
783 You can register any build instruction as a trigger. A trigger is use‐
786 ful if
787 you are defining an image to use as a base for building other images.
788 For
789 example, if you are defining an application build environment or a
790 daemon that
791 is customized with a user-specific configuration.
792 Consider an image intended as a reusable python application builder. It
795 must
796 add application source code to a particular directory, and might need
797 a build
798 script called after that. You can't just call ADD and RUN now, be‐
799 cause
800 you don't yet have access to the application source code, and it is
801 different
802 for each application build.
803 -- Providing application developers with a boilerplate Containerfile to
806 copy-paste
807 into their application is inefficient, error-prone, and
808 difficult to update because it mixes with application-specific code.
809 The solution is to use ONBUILD to register instructions in advance,
810 to
811 run later, during the next build stage.
812
815 buildah(1), podman(1), docker(1)
816
820 May 2014, Compiled by Zac Dover (zdover at redhat dot com) based on docker.com Dockerfile documentation.
821 Feb 2015, updated by Brian Goff (cpuguy83@gmail.com) for readability
822 Sept 2015, updated by Sally O'Malley (somalley@redhat.com)
823 Oct 2016, updated by Addam Hardy (addam.hardy@gmail.com)
824 Aug 2021, converted Dockerfile man page to Containerfile by Dan Walsh (dwalsh@redhat.com)
825 Aug 2021 CONTAINERFILE(5)