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 [AS <name>]
83 FROM image:tag [AS <name>]
86 FROM image@digest [AS <name>]
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 -- A name can be assigned to a build stage by adding AS name to the in‐
130 struction.
131 The name can be referenced later in the Containerfile using the FROM
132 or COPY --from= instructions.
133 MAINTAINER
136 -- MAINTAINER sets the Author field for the generated images.
137 Useful for providing users with an email or url for support.
138 RUN
141 -- RUN has two forms:
142 # the command is run in a shell - /bin/sh -c
145 RUN <command>
146 # Executable form
148 RUN ["executable", "param1", "param2"]
149 RUN mounts
153 --mount=type=TYPE,TYPE-SPECIFIC-OPTION[,...]
156 Attach a filesystem mount to the container
159 Current supported mount TYPES are bind, cache, secret and tmpfs.
162 e.g.
165 mount=type=bind,source=/path/on/host,destination=/path/in/container
167 mount=type=tmpfs,tmpfs-size=512M,destination=/path/in/container
169 mount=type=secret,id=mysecret cat /run/secrets/mysecret
171 Common Options:
173 · src, source: mount source spec for bind and volume. Mandatory for bind. If `from` is specified, `src` is the subpath in the `from` field.
175 · dst, destination, target: mount destination spec.
177 · ro, read-only: true (default) or false.
179 Options specific to bind:
181 · bind-propagation: shared, slave, private, rshared, rslave, or rprivate(default). See also mount(2).
183 . bind-nonrecursive: do not setup a recursive bind mount. By default it is recursive.
185 · from: stage or image name for the root of the source. Defaults to the build context.
187 · rw, read-write: allows writes on the mount.
189 Options specific to tmpfs:
191 · tmpfs-size: Size of the tmpfs mount in bytes. Unlimited by default in Linux.
193 · tmpfs-mode: File mode of the tmpfs in octal. (e.g. 700 or 0700.) Defaults to 1777 in Linux.
195 · tmpcopyup: Path that is shadowed by the tmpfs mount is recursively copied up to the tmpfs itself.
197 Options specific to cache:
199 · id: Create a separate cache directory for a particular id.
201 · mode: File mode for new cache directory in octal. Default 0755.
203 · ro, readonly: read only cache if set.
205 · uid: uid for cache directory.
207 · gid: gid for cache directory.
209 · from: stage name for the root of the source. Defaults to host cache directory.
211 · rw, read-write: allows writes on the mount.
213 RUN --network
217 RUN --network allows control over which networking environment the com‐
220 mand is run in.
221 Syntax: --network=<TYPE>
224 Network types
227 ┌──────────────────────────────────┬─────────────────────────────┐
230 │Type │ Description │
231 ├──────────────────────────────────┼─────────────────────────────┤
232 │default │ │
233 ├──────────────────────────────────┼─────────────────────────────┤
234 │⟨#run---networkdefault⟩ (default) │ Run in the default network. │
235 ├──────────────────────────────────┼─────────────────────────────┤
236 │none │ │
237 ├──────────────────────────────────┼─────────────────────────────┤
238 │⟨#run---networknone⟩ │ Run with no network access. │
239 ├──────────────────────────────────┼─────────────────────────────┤
240 │host │ │
241 ├──────────────────────────────────┼─────────────────────────────┤
242 │⟨#run---networkhost⟩ │ Run in the host's network │
243 │ │ environment. │
244 └──────────────────────────────────┴─────────────────────────────┘
245 RUN --network=default
247 Equivalent to not supplying a flag at all, the command is run in the
248 default network for the build.
249 RUN --network=none
252 The command is run with no network access (lo is still available, but
253 is isolated to this process).
254 Example: isolating external effects
257 FROM python:3.6
258 ADD mypackage.tgz wheels/
259 RUN --network=none pip install --find-links wheels mypackage
260 pip will only be able to install the packages provided in the tarfile,
264 which can be controlled by an earlier build stage.
265 RUN --network=host
268 The command is run in the host's network environment (similar to buil‐
269 dah build --network=host, but on a per-instruction basis)
270 RUN Secrets
273 The RUN command has a feature to allow the passing of secret informa‐
276 tion into the image build. These secrets files can be used during the
277 RUN command but are not committed to the final image. The RUN command
278 supports the --mount option to identify the secret file. A secret file
279 from the host is mounted into the container while the image is being
280 built.
281 Container engines pass secret the secret file into the build using the
284 --secret flag.
285 --mount=type=secret,TYPE-SPECIFIC-OPTION[,...]
288 • id is the identifier for the secret passed into the buildah
291 bud --secret or podman build --secret. This identifier is as‐
292 sociated with the RUN --mount identifier to use in the Con‐
293 tainerfile.
294 • dst|target|destination rename the secret file to a specific
296 file in the Containerfile RUN command to use.
297 • type=secret tells the --mount command that it is mounting in a
299 secret file
300 # shows secret from default secret location:
302 RUN --mount=type=secret,id=mysecret cat /run/secrets/mysecret
303 # shows secret from custom secret location:
307 RUN --mount=type=secret,id=mysecret,dst=/foobar cat /foobar
308 The secret needs to be passed to the build using the --secret flag. The
314 final image built does not container the secret file:
315 buildah bud --no-cache --secret id=mysecret,src=mysecret.txt .
318 -- The RUN instruction executes any commands in a new layer on top of
322 the current
323 image and commits the results. The committed image is used for the
324 next step in
325 Containerfile.
326 -- Layering RUN instructions and generating commits conforms to the
329 core
330 concepts of container engines where commits are cheap and containers
331 can be created from
332 any point in the history of an image. This is similar to source con‐
333 trol. The
334 exec form makes it possible to avoid shell string munging. The exec
335 form makes
336 it possible to RUN commands using a base image that does not contain
337 /bin/sh.
338 Note that the exec form is parsed as a JSON array, which means that you
341 must
342 use double-quotes (") around words, not single-quotes (').
343 CMD
346 -- CMD has three forms:
347 # Executable form
350 CMD ["executable", "param1", "param2"]`
351 # Provide default arguments to ENTRYPOINT
353 CMD ["param1", "param2"]`
354 # the command is run in a shell - /bin/sh -c
356 CMD command param1 param2
357 -- There should be only one CMD in a Containerfile. If more than one
361 CMD is listed, only
362 the last CMD takes effect.
363 The main purpose of a CMD is to provide defaults for an executing
364 container.
365 These defaults may include an executable, or they can omit the exe‐
366 cutable. If
367 they omit the executable, an ENTRYPOINT must be specified.
368 When used in the shell or exec formats, the CMD instruction sets the
369 command to
370 be executed when running the image.
371 If you use the shell form of the CMD, the <command> executes in
372 /bin/sh -c:
373 Note that the exec form is parsed as a JSON array, which means that you
376 must
377 use double-quotes (") around words, not single-quotes (').
378 FROM ubuntu
381 CMD echo "This is a test." | wc -
382 -- If you run command without a shell, then you must express the com‐
386 mand as a
387 JSON array and give the full path to the executable. This array form
388 is the
389 preferred form of CMD. All additional parameters must be individually
390 expressed
391 as strings in the array:
392 FROM ubuntu
395 CMD ["/usr/bin/wc","--help"]
396 -- To make the container run the same executable every time, use ENTRY‐
400 POINT in
401 combination with CMD.
402 If the user specifies arguments to podman run or docker run, the
403 specified commands
404 override the default in CMD.
405 Do not confuse RUN with CMD. RUN runs a command and commits the re‐
406 sult.
407 CMD executes nothing at build time, but specifies the intended com‐
408 mand for
409 the image.
410 LABEL
413 -- LABEL <key>=<value> [<key>=<value> ...]or
414 LABEL <key>[ <value>]
417 LABEL <key>[ <value>]
418 ...
419 The LABEL instruction adds metadata to an image. A LABEL is a
423 key-value pair. To specify a LABEL without a value, simply use an
424 empty
425 string. To include spaces within a LABEL value, use quotes and
426 backslashes as you would in command-line parsing.
427 LABEL com.example.vendor="ACME Incorporated"
430 LABEL com.example.vendor "ACME Incorporated"
431 LABEL com.example.vendor.is-beta ""
432 LABEL com.example.vendor.is-beta=
433 LABEL com.example.vendor.is-beta=""
434 An image can have more than one label. To specify multiple labels, sep‐
438 arate
439 each key-value pair by a space.
440 Labels are additive including LABELs in FROM images. As the system
443 encounters and then applies a new label, new keys override any previ‐
444 ous
445 labels with identical keys.
446 To display an image's labels, use the buildah inspect command.
449 EXPOSE
452 -- EXPOSE <port> [<port>...]
453 The EXPOSE instruction informs the container engine that the con‐
454 tainer listens on the
455 specified network ports at runtime. The container engine uses this
456 information to
457 interconnect containers using links and to set up port redirection on
458 the host
459 system.
460 ENV
463 -- ENV <key> <value>
464 The ENV instruction sets the environment variable to
465 the value <value>. This value is passed to all future
466 RUN, ENTRYPOINT, and CMD instructions. This is
467 functionally equivalent to prefixing the command with <key>=<value>.
468 The
469 environment variables that are set with ENV persist when a container
470 is run
471 from the resulting image. Use podman inspect to inspect these values,
472 and
473 change them using podman run --env <key>=<value>.
474 Note that setting "ENV DEBIAN_FRONTEND=noninteractive" may cause
477 unintended consequences, because it will persist when the container
478 is run
479 interactively, as with the following command: podman run -t -i image
480 bash
481 ADD
484 -- ADD has two forms:
485 ADD <src> <dest>
488 # Required for paths with whitespace
490 ADD ["<src>",... "<dest>"]
491 The ADD instruction copies new files, directories
495 or remote file URLs to the filesystem of the container at path
496 <dest>.
497 Multiple <src> resources may be specified but if they are files or
498 directories
499 then they must be relative to the source directory that is being
500 built
501 (the context of the build). The <dest> is the absolute path, or path
502 relative
503 to WORKDIR, into which the source is copied inside the target con‐
504 tainer.
505 If the <src> argument is a local file in a recognized compression
506 format
507 (tar, gzip, bzip2, etc) then it is unpacked at the specified <dest>
508 in the
509 container's filesystem. Note that only local compressed files will
510 be unpacked,
511 i.e., the URL download and archive unpacking features cannot be used
512 together.
513 All new directories are created with mode 0755 and with the uid and
514 gid of 0.
515 COPY
518 -- COPY has two forms:
519 COPY [--chown=<user>:<group>] [--chmod=<mode>] <src> <dest>
522 # Required for paths with whitespace
524 COPY [--chown=<user>:<group>] [--chmod=<mode>] ["<src>",... "<dest>"]
525 The COPY instruction copies new files from <src> and
529 adds them to the filesystem of the container at path . The <src> must
530 be
531 the path to a file or directory relative to the source directory that
532 is
533 being built (the context of the build) or a remote file URL. The
534 <dest> is an
535 absolute path, or a path relative to WORKDIR, into which the source
536 will
537 be copied inside the target container. If you COPY an archive file it
538 will
539 land in the container exactly as it appears in the build context
540 without any
541 attempt to unpack it. All new files and directories are created with
542 mode 0755
543 and with the uid and gid of 0.
544 --chown=<user>:<group> changes the ownership of new files and directo‐
547 ries.
548 Supports names, if defined in the containers /etc/passwd and
549 /etc/groups files, or using
550 uid and gid integers. The build will fail if a user or group name
551 can't be mapped in the container.
552 Numeric id's are set without looking them up in the container.
553 --chmod=<mode> changes the mode of new files and directories.
556 The optional flag --from=name can be used to copy files from a named
559 previous build stage. It
560 changes the context of <src> from the build context to the named
561 build stage.
562 ENTRYPOINT
565 -- ENTRYPOINT has two forms:
566 # executable form
569 ENTRYPOINT ["executable", "param1", "param2"]`
570 # run command in a shell - /bin/sh -c
572 ENTRYPOINT command param1 param2
573 -- An ENTRYPOINT helps you configure a
577 container that can be run as an executable. When you specify an EN‐
578 TRYPOINT,
579 the whole container runs as if it was only that executable. The EN‐
580 TRYPOINT
581 instruction adds an entry command that is not overwritten when argu‐
582 ments are
583 passed to podman run. This is different from the behavior of CMD.
584 This allows
585 arguments to be passed to the entrypoint, for instance podman run
586 <image> -d
587 passes the -d argument to the ENTRYPOINT. Specify parameters either
588 in the
589 ENTRYPOINT JSON array (as in the preferred exec form above), or by
590 using a CMD
591 statement. Parameters in the ENTRYPOINT are not overwritten by the
592 podman run arguments. Parameters specified via CMD are overwritten by
593 podman run arguments. Specify a plain string for the ENTRYPOINT, and
594 it will execute in
595 /bin/sh -c, like a CMD instruction:
596 FROM ubuntu
599 ENTRYPOINT wc -l -
600 This means that the Containerfile's image always takes stdin as input
604 (that's
605 what "-" means), and prints the number of lines (that's what "-l"
606 means). To
607 make this optional but default, use a CMD:
608 FROM ubuntu
611 CMD ["-l", "-"]
612 ENTRYPOINT ["/usr/bin/wc"]
613 VOLUME
617 -- VOLUME ["/data"]
618 The VOLUME instruction creates a mount point with the specified name
619 and marks
620 it as holding externally-mounted volumes from the native host or from
621 other
622 containers.
623 USER
626 -- USER daemon
627 Sets the username or UID used for running subsequent commands.
628 The USER instruction can optionally be used to set the group or GID.
631 The
632 following examples are all valid:
633 USER [user | user:group | uid | uid:gid | user:gid | uid:group ]
634 Until the USER instruction is set, instructions will be run as root.
637 The USER
638 instruction can be used any number of times in a Containerfile, and
639 will only affect
640 subsequent commands.
641 WORKDIR
644 -- WORKDIR /path/to/workdir
645 The WORKDIR instruction sets the working directory for the RUN, CMD,
646 ENTRYPOINT, COPY and ADD Containerfile commands that follow it. It
647 can
648 be used multiple times in a single Containerfile. Relative paths are
649 defined
650 relative to the path of the previous WORKDIR instruction. For exam‐
651 ple:
652 WORKDIR /a
655 WORKDIR b
656 WORKDIR c
657 RUN pwd
658 In the above example, the output of the pwd command is a/b/c.
662 ARG
665 -- ARG [=]
666 The ARG instruction defines a variable that users can pass at build-
669 time to
670 the builder with the podman build and buildah build commands using
671 the
672 --build-arg <varname>=<value> flag. If a user specifies a build argu‐
673 ment that
674 was not defined in the Containerfile, the build outputs a warning.
675 Note that a second FROM in a Containerfile sets the values associated
678 with an
679 Arg variable to nil and they must be reset if they are to be used
680 later in
681 the Containerfile
682 [Warning] One or more build-args [foo] were not consumed
685 The Containerfile author can define a single variable by specifying ARG
689 once or many
690 variables by specifying ARG more than once. For example, a valid Con‐
691 tainerfile:
692 FROM busybox
695 ARG user1
696 ARG buildno
697 ...
698 A Containerfile author may optionally specify a default value for an
702 ARG instruction:
703 FROM busybox
706 ARG user1=someuser
707 ARG buildno=1
708 ...
709 If an ARG value has a default and if there is no value passed at build-
713 time, the
714 builder uses the default.
715 An ARG variable definition comes into effect from the line on which it
718 is
719 defined in the Containerfile not from the argument's use on the com‐
720 mand-line or
721 elsewhere. For example, consider this Containerfile:
722 1 FROM busybox
725 2 USER ${user:-some_user}
726 3 ARG user
727 4 USER $user
728 ...
729 A user builds this file by calling:
733 $ podman build --build-arg user=what_user Containerfile
736 The USER at line 2 evaluates to some_user as the user variable is de‐
740 fined on the
741 subsequent line 3. The USER at line 4 evaluates to what_user as user
742 is
743 defined and the what_user value was passed on the command line. Prior
744 to its definition by an
745 ARG instruction, any use of a variable results in an empty string.
746 Warning: It is not recommended to use build-time variables for
749 passing secrets like github keys, user credentials etc. Build-
750 time variable
751 values are visible to any user of the image with the podman
752 history command.
753 You can use an ARG or an ENV instruction to specify variables that are
757 available to the RUN instruction. Environment variables defined using
758 the
759 ENV instruction always override an ARG instruction of the same name.
760 Consider
761 this Containerfile with an ENV and ARG instruction.
762 1 FROM ubuntu
765 2 ARG CONT_IMG_VER
766 3 ENV CONT_IMG_VER=v1.0.0
767 4 RUN echo $CONT_IMG_VER
768 Then, assume this image is built with this command:
772 $ podman build --build-arg CONT_IMG_VER=v2.0.1 Containerfile
775 In this case, the RUN instruction uses v1.0.0 instead of the ARG set‐
779 ting
780 passed by the user:v2.0.1 This behavior is similar to a shell
781 script where a locally scoped variable overrides the variables passed
782 as
783 arguments or inherited from environment, from its point of defini‐
784 tion.
785 Using the example above but a different ENV specification you can cre‐
788 ate more
789 useful interactions between ARG and ENV instructions:
790 1 FROM ubuntu
793 2 ARG CONT_IMG_VER
794 3 ENV CONT_IMG_VER=${CONT_IMG_VER:-v1.0.0}
795 4 RUN echo $CONT_IMG_VER
796 Unlike an ARG instruction, ENV values are always persisted in the built
800 image. Consider a podman build without the --build-arg flag:
801 $ podman build Containerfile
804 Using this Containerfile example, CONT_IMG_VER is still persisted in
808 the image but
809 its value would be v1.0.0 as it is the default set in line 3 by the
810 ENV instruction.
811 The variable expansion technique in this example allows you to pass ar‐
814 guments
815 from the command line and persist them in the final image by leverag‐
816 ing the
817 ENV instruction. Variable expansion is only supported for a limited
818 set of
819 Containerfile instructions. ⟨#environment-replacement⟩
820 Container engines have a set of predefined ARG variables that you can
823 use without a
824 corresponding ARG instruction in the Containerfile.
825 • HTTP_PROXY
828 • http_proxy
830 • HTTPS_PROXY
832 • https_proxy
834 • FTP_PROXY
836 • ftp_proxy
838 • NO_PROXY
840 • no_proxy
842 • ALL_PROXY
844 • all_proxy
846 To use these, pass them on the command line using --build-arg flag, for
850 example:
851 $ podman build --build-arg HTTPS_PROXY=https://my-proxy.example.com .
854 ONBUILD
858 -- ONBUILD [INSTRUCTION]
859 The ONBUILD instruction adds a trigger instruction to an image. The
860 trigger is executed at a later time, when the image is used as the
861 base for
862 another build. Container engines execute the trigger in the context
863 of the downstream
864 build, as if the trigger existed immediately after the FROM instruc‐
865 tion in
866 the downstream Containerfile.
867 You can register any build instruction as a trigger. A trigger is use‐
870 ful if
871 you are defining an image to use as a base for building other images.
872 For
873 example, if you are defining an application build environment or a
874 daemon that
875 is customized with a user-specific configuration.
876 Consider an image intended as a reusable python application builder. It
879 must
880 add application source code to a particular directory, and might need
881 a build
882 script called after that. You can't just call ADD and RUN now, be‐
883 cause
884 you don't yet have access to the application source code, and it is
885 different
886 for each application build.
887 -- Providing application developers with a boilerplate Containerfile to
890 copy-paste
891 into their application is inefficient, error-prone, and
892 difficult to update because it mixes with application-specific code.
893 The solution is to use ONBUILD to register instructions in advance,
894 to
895 run later, during the next build stage.
896
899 buildah(1), podman(1), docker(1)
900
904 May 2014, Compiled by Zac Dover (zdover at redhat dot com) based on docker.com Dockerfile documentation.
905 Feb 2015, updated by Brian Goff (cpuguy83@gmail.com) for readability
906 Sept 2015, updated by Sally O'Malley (somalley@redhat.com)
907 Oct 2016, updated by Addam Hardy (addam.hardy@gmail.com)
908 Aug 2021, converted Dockerfile man page to Containerfile by Dan Walsh (dwalsh@redhat.com)
909 Aug 2021 CONTAINERFILE(5)