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 --network
211 RUN --network allows control over which networking environment the com‐
214 mand is run in.
215 Syntax: --network=<TYPE>
218 Network types
221 ┌──────────────────────────────────┬─────────────────────────────┐
224 │Type │ Description │
225 ├──────────────────────────────────┼─────────────────────────────┤
226 │default │ │
227 ├──────────────────────────────────┼─────────────────────────────┤
228 │⟨#run---networkdefault⟩ (default) │ Run in the default network. │
229 ├──────────────────────────────────┼─────────────────────────────┤
230 │none │ │
231 ├──────────────────────────────────┼─────────────────────────────┤
232 │⟨#run---networknone⟩ │ Run with no network access. │
233 ├──────────────────────────────────┼─────────────────────────────┤
234 │host │ │
235 ├──────────────────────────────────┼─────────────────────────────┤
236 │⟨#run---networkhost⟩ │ Run in the host's network │
237 │ │ environment. │
238 └──────────────────────────────────┴─────────────────────────────┘
239 RUN --network=default
241 Equivalent to not supplying a flag at all, the command is run in the
242 default network for the build.
243 RUN --network=none
246 The command is run with no network access (lo is still available, but
247 is isolated to this process).
248 Example: isolating external effects
251 FROM python:3.6
252 ADD mypackage.tgz wheels/
253 RUN --network=none pip install --find-links wheels mypackage
254 pip will only be able to install the packages provided in the tarfile,
258 which can be controlled by an earlier build stage.
259 RUN --network=host
262 The command is run in the host's network environment (similar to buil‐
263 dah build --network=host, but on a per-instruction basis)
264 RUN Secrets
267 The RUN command has a feature to allow the passing of secret informa‐
270 tion into the image build. These secrets files can be used during the
271 RUN command but are not committed to the final image. The RUN command
272 supports the --mount option to identify the secret file. A secret file
273 from the host is mounted into the container while the image is being
274 built.
275 Container engines pass secret the secret file into the build using the
278 --secret flag.
279 --mount=type=secret,TYPE-SPECIFIC-OPTION[,...]
282 • id is the identifier for the secret passed into the buildah
285 bud --secret or podman build --secret. This identifier is as‐
286 sociated with the RUN --mount identifier to use in the Con‐
287 tainerfile.
288 • dst|target|destination rename the secret file to a specific
290 file in the Containerfile RUN command to use.
291 • type=secret tells the --mount command that it is mounting in a
293 secret file
294 # shows secret from default secret location:
296 RUN --mount=type=secret,id=mysecret cat /run/secrets/mysecret
297 # shows secret from custom secret location:
301 RUN --mount=type=secret,id=mysecret,dst=/foobar cat /foobar
302 The secret needs to be passed to the build using the --secret flag. The
308 final image built does not container the secret file:
309 buildah bud --no-cache --secret id=mysecret,src=mysecret.txt .
312 -- The RUN instruction executes any commands in a new layer on top of
316 the current
317 image and commits the results. The committed image is used for the
318 next step in
319 Containerfile.
320 -- Layering RUN instructions and generating commits conforms to the
323 core
324 concepts of container engines where commits are cheap and containers
325 can be created from
326 any point in the history of an image. This is similar to source con‐
327 trol. The
328 exec form makes it possible to avoid shell string munging. The exec
329 form makes
330 it possible to RUN commands using a base image that does not contain
331 /bin/sh.
332 Note that the exec form is parsed as a JSON array, which means that you
335 must
336 use double-quotes (") around words, not single-quotes (').
337 CMD
340 -- CMD has three forms:
341 # Executable form
344 CMD ["executable", "param1", "param2"]`
345 # Provide default arguments to ENTRYPOINT
347 CMD ["param1", "param2"]`
348 # the command is run in a shell - /bin/sh -c
350 CMD command param1 param2
351 -- There should be only one CMD in a Containerfile. If more than one
355 CMD is listed, only
356 the last CMD takes effect.
357 The main purpose of a CMD is to provide defaults for an executing
358 container.
359 These defaults may include an executable, or they can omit the exe‐
360 cutable. If
361 they omit the executable, an ENTRYPOINT must be specified.
362 When used in the shell or exec formats, the CMD instruction sets the
363 command to
364 be executed when running the image.
365 If you use the shell form of the CMD, the <command> executes in
366 /bin/sh -c:
367 Note that the exec form is parsed as a JSON array, which means that you
370 must
371 use double-quotes (") around words, not single-quotes (').
372 FROM ubuntu
375 CMD echo "This is a test." | wc -
376 -- If you run command without a shell, then you must express the com‐
380 mand as a
381 JSON array and give the full path to the executable. This array form
382 is the
383 preferred form of CMD. All additional parameters must be individually
384 expressed
385 as strings in the array:
386 FROM ubuntu
389 CMD ["/usr/bin/wc","--help"]
390 -- To make the container run the same executable every time, use ENTRY‐
394 POINT in
395 combination with CMD.
396 If the user specifies arguments to podman run or docker run, the
397 specified commands
398 override the default in CMD.
399 Do not confuse RUN with CMD. RUN runs a command and commits the re‐
400 sult.
401 CMD executes nothing at build time, but specifies the intended com‐
402 mand for
403 the image.
404 LABEL
407 -- LABEL <key>=<value> [<key>=<value> ...]or
408 LABEL <key>[ <value>]
411 LABEL <key>[ <value>]
412 ...
413 The LABEL instruction adds metadata to an image. A LABEL is a
417 key-value pair. To specify a LABEL without a value, simply use an
418 empty
419 string. To include spaces within a LABEL value, use quotes and
420 backslashes as you would in command-line parsing.
421 LABEL com.example.vendor="ACME Incorporated"
424 LABEL com.example.vendor "ACME Incorporated"
425 LABEL com.example.vendor.is-beta ""
426 LABEL com.example.vendor.is-beta=
427 LABEL com.example.vendor.is-beta=""
428 An image can have more than one label. To specify multiple labels, sep‐
432 arate
433 each key-value pair by a space.
434 Labels are additive including LABELs in FROM images. As the system
437 encounters and then applies a new label, new keys override any previ‐
438 ous
439 labels with identical keys.
440 To display an image's labels, use the buildah inspect command.
443 EXPOSE
446 -- EXPOSE <port> [<port>...]
447 The EXPOSE instruction informs the container engine that the con‐
448 tainer listens on the
449 specified network ports at runtime. The container engine uses this
450 information to
451 interconnect containers using links and to set up port redirection on
452 the host
453 system.
454 ENV
457 -- ENV <key> <value>
458 The ENV instruction sets the environment variable to
459 the value <value>. This value is passed to all future
460 RUN, ENTRYPOINT, and CMD instructions. This is
461 functionally equivalent to prefixing the command with <key>=<value>.
462 The
463 environment variables that are set with ENV persist when a container
464 is run
465 from the resulting image. Use podman inspect to inspect these values,
466 and
467 change them using podman run --env <key>=<value>.
468 Note that setting "ENV DEBIAN_FRONTEND=noninteractive" may cause
471 unintended consequences, because it will persist when the container
472 is run
473 interactively, as with the following command: podman run -t -i image
474 bash
475 ADD
478 -- ADD has two forms:
479 ADD <src> <dest>
482 # Required for paths with whitespace
484 ADD ["<src>",... "<dest>"]
485 The ADD instruction copies new files, directories
489 or remote file URLs to the filesystem of the container at path
490 <dest>.
491 Multiple <src> resources may be specified but if they are files or
492 directories
493 then they must be relative to the source directory that is being
494 built
495 (the context of the build). The <dest> is the absolute path, or path
496 relative
497 to WORKDIR, into which the source is copied inside the target con‐
498 tainer.
499 If the <src> argument is a local file in a recognized compression
500 format
501 (tar, gzip, bzip2, etc) then it is unpacked at the specified <dest>
502 in the
503 container's filesystem. Note that only local compressed files will
504 be unpacked,
505 i.e., the URL download and archive unpacking features cannot be used
506 together.
507 All new directories are created with mode 0755 and with the uid and
508 gid of 0.
509 COPY
512 -- COPY has two forms:
513 COPY <src> <dest>
516 # Required for paths with whitespace
518 COPY ["<src>",... "<dest>"]
519 The COPY instruction copies new files from <src> and
523 adds them to the filesystem of the container at path . The <src> must
524 be
525 the path to a file or directory relative to the source directory that
526 is
527 being built (the context of the build) or a remote file URL. The
528 <dest> is an
529 absolute path, or a path relative to WORKDIR, into which the source
530 will
531 be copied inside the target container. If you COPY an archive file it
532 will
533 land in the container exactly as it appears in the build context
534 without any
535 attempt to unpack it. All new files and directories are created with
536 mode 0755
537 and with the uid and gid of 0.
538 ENTRYPOINT
541 -- ENTRYPOINT has two forms:
542 # executable form
545 ENTRYPOINT ["executable", "param1", "param2"]`
546 # run command in a shell - /bin/sh -c
548 ENTRYPOINT command param1 param2
549 -- An ENTRYPOINT helps you configure a
553 container that can be run as an executable. When you specify an EN‐
554 TRYPOINT,
555 the whole container runs as if it was only that executable. The EN‐
556 TRYPOINT
557 instruction adds an entry command that is not overwritten when argu‐
558 ments are
559 passed to podman run. This is different from the behavior of CMD.
560 This allows
561 arguments to be passed to the entrypoint, for instance podman run
562 <image> -d
563 passes the -d argument to the ENTRYPOINT. Specify parameters either
564 in the
565 ENTRYPOINT JSON array (as in the preferred exec form above), or by
566 using a CMD
567 statement. Parameters in the ENTRYPOINT are not overwritten by the
568 podman run arguments. Parameters specified via CMD are overwritten by
569 podman run arguments. Specify a plain string for the ENTRYPOINT, and
570 it will execute in
571 /bin/sh -c, like a CMD instruction:
572 FROM ubuntu
575 ENTRYPOINT wc -l -
576 This means that the Containerfile's image always takes stdin as input
580 (that's
581 what "-" means), and prints the number of lines (that's what "-l"
582 means). To
583 make this optional but default, use a CMD:
584 FROM ubuntu
587 CMD ["-l", "-"]
588 ENTRYPOINT ["/usr/bin/wc"]
589 VOLUME
593 -- VOLUME ["/data"]
594 The VOLUME instruction creates a mount point with the specified name
595 and marks
596 it as holding externally-mounted volumes from the native host or from
597 other
598 containers.
599 USER
602 -- USER daemon
603 Sets the username or UID used for running subsequent commands.
604 The USER instruction can optionally be used to set the group or GID.
607 The
608 following examples are all valid:
609 USER [user | user:group | uid | uid:gid | user:gid | uid:group ]
610 Until the USER instruction is set, instructions will be run as root.
613 The USER
614 instruction can be used any number of times in a Containerfile, and
615 will only affect
616 subsequent commands.
617 WORKDIR
620 -- WORKDIR /path/to/workdir
621 The WORKDIR instruction sets the working directory for the RUN, CMD,
622 ENTRYPOINT, COPY and ADD Containerfile commands that follow it. It
623 can
624 be used multiple times in a single Containerfile. Relative paths are
625 defined
626 relative to the path of the previous WORKDIR instruction. For exam‐
627 ple:
628 WORKDIR /a
631 WORKDIR b
632 WORKDIR c
633 RUN pwd
634 In the above example, the output of the pwd command is a/b/c.
638 ARG
641 -- ARG [=]
642 The ARG instruction defines a variable that users can pass at build-
645 time to
646 the builder with the podman build and buildah build commands using
647 the
648 --build-arg <varname>=<value> flag. If a user specifies a build argu‐
649 ment that
650 was not defined in the Containerfile, the build outputs a warning.
651 Note that a second FROM in a Containerfile sets the values associated
654 with an
655 Arg variable to nil and they must be reset if they are to be used
656 later in
657 the Containerfile
658 [Warning] One or more build-args [foo] were not consumed
661 The Containerfile author can define a single variable by specifying ARG
665 once or many
666 variables by specifying ARG more than once. For example, a valid Con‐
667 tainerfile:
668 FROM busybox
671 ARG user1
672 ARG buildno
673 ...
674 A Containerfile author may optionally specify a default value for an
678 ARG instruction:
679 FROM busybox
682 ARG user1=someuser
683 ARG buildno=1
684 ...
685 If an ARG value has a default and if there is no value passed at build-
689 time, the
690 builder uses the default.
691 An ARG variable definition comes into effect from the line on which it
694 is
695 defined in the Containerfile not from the argument's use on the com‐
696 mand-line or
697 elsewhere. For example, consider this Containerfile:
698 1 FROM busybox
701 2 USER ${user:-some_user}
702 3 ARG user
703 4 USER $user
704 ...
705 A user builds this file by calling:
709 $ podman build --build-arg user=what_user Containerfile
712 The USER at line 2 evaluates to some_user as the user variable is de‐
716 fined on the
717 subsequent line 3. The USER at line 4 evaluates to what_user as user
718 is
719 defined and the what_user value was passed on the command line. Prior
720 to its definition by an
721 ARG instruction, any use of a variable results in an empty string.
722 Warning: It is not recommended to use build-time variables for
725 passing secrets like github keys, user credentials etc. Build-
726 time variable
727 values are visible to any user of the image with the podman
728 history command.
729 You can use an ARG or an ENV instruction to specify variables that are
733 available to the RUN instruction. Environment variables defined using
734 the
735 ENV instruction always override an ARG instruction of the same name.
736 Consider
737 this Containerfile with an ENV and ARG instruction.
738 1 FROM ubuntu
741 2 ARG CONT_IMG_VER
742 3 ENV CONT_IMG_VER=v1.0.0
743 4 RUN echo $CONT_IMG_VER
744 Then, assume this image is built with this command:
748 $ podman build --build-arg CONT_IMG_VER=v2.0.1 Containerfile
751 In this case, the RUN instruction uses v1.0.0 instead of the ARG set‐
755 ting
756 passed by the user:v2.0.1 This behavior is similar to a shell
757 script where a locally scoped variable overrides the variables passed
758 as
759 arguments or inherited from environment, from its point of defini‐
760 tion.
761 Using the example above but a different ENV specification you can cre‐
764 ate more
765 useful interactions between ARG and ENV instructions:
766 1 FROM ubuntu
769 2 ARG CONT_IMG_VER
770 3 ENV CONT_IMG_VER=${CONT_IMG_VER:-v1.0.0}
771 4 RUN echo $CONT_IMG_VER
772 Unlike an ARG instruction, ENV values are always persisted in the built
776 image. Consider a podman build without the --build-arg flag:
777 $ podman build Containerfile
780 Using this Containerfile example, CONT_IMG_VER is still persisted in
784 the image but
785 its value would be v1.0.0 as it is the default set in line 3 by the
786 ENV instruction.
787 The variable expansion technique in this example allows you to pass ar‐
790 guments
791 from the command line and persist them in the final image by leverag‐
792 ing the
793 ENV instruction. Variable expansion is only supported for a limited
794 set of
795 Containerfile instructions. ⟨#environment-replacement⟩
796 Container engines have a set of predefined ARG variables that you can
799 use without a
800 corresponding ARG instruction in the Containerfile.
801 • HTTP_PROXY
804 • http_proxy
806 • HTTPS_PROXY
808 • https_proxy
810 • FTP_PROXY
812 • ftp_proxy
814 • NO_PROXY
816 • no_proxy
818 • ALL_PROXY
820 • all_proxy
822 To use these, pass them on the command line using --build-arg flag, for
826 example:
827 $ podman build --build-arg HTTPS_PROXY=https://my-proxy.example.com .
830 ONBUILD
834 -- ONBUILD [INSTRUCTION]
835 The ONBUILD instruction adds a trigger instruction to an image. The
836 trigger is executed at a later time, when the image is used as the
837 base for
838 another build. Container engines execute the trigger in the context
839 of the downstream
840 build, as if the trigger existed immediately after the FROM instruc‐
841 tion in
842 the downstream Containerfile.
843 You can register any build instruction as a trigger. A trigger is use‐
846 ful if
847 you are defining an image to use as a base for building other images.
848 For
849 example, if you are defining an application build environment or a
850 daemon that
851 is customized with a user-specific configuration.
852 Consider an image intended as a reusable python application builder. It
855 must
856 add application source code to a particular directory, and might need
857 a build
858 script called after that. You can't just call ADD and RUN now, be‐
859 cause
860 you don't yet have access to the application source code, and it is
861 different
862 for each application build.
863 -- Providing application developers with a boilerplate Containerfile to
866 copy-paste
867 into their application is inefficient, error-prone, and
868 difficult to update because it mixes with application-specific code.
869 The solution is to use ONBUILD to register instructions in advance,
870 to
871 run later, during the next build stage.
872
875 buildah(1), podman(1), docker(1)
876
880 May 2014, Compiled by Zac Dover (zdover at redhat dot com) based on docker.com Dockerfile documentation.
881 Feb 2015, updated by Brian Goff (cpuguy83@gmail.com) for readability
882 Sept 2015, updated by Sally O'Malley (somalley@redhat.com)
883 Oct 2016, updated by Addam Hardy (addam.hardy@gmail.com)
884 Aug 2021, converted Dockerfile man page to Containerfile by Dan Walsh (dwalsh@redhat.com)
885 Aug 2021 CONTAINERFILE(5)