1CONTAINERFILE(5)            Container User Manuals            CONTAINERFILE(5)
2
3
4

NAME

6       Containerfile(Dockerfile)  - automate the steps of creating a container
7       image
8
9
10

INTRODUCTION

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

SYNOPSIS

33       INSTRUCTION arguments
34
35
36       For example:
37
38
39       FROM image
40
41
42

DESCRIPTION

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

USAGE

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

FORMAT

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 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
103
104       -- FROM must appear at least once in the Containerfile.
105
106
107       --  FROM The first FROM command must come before all other instructions
108       in
109         the Containerfile except ARG
110
111
112       -- 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
118
119       -- 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
123
124       -- 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
128
129       MAINTAINER
130         -- MAINTAINER sets the Author field for the generated images.
131         Useful for providing users with an email or url for support.
132
133
134       RUN
135         -- RUN has two forms:
136
137
138                # the command is run in a shell - /bin/sh -c
139                RUN <command>
140
141                # Executable form
142                RUN ["executable", "param1", "param2"]
143
144
145
146       RUN mounts
147
148
149       --mount=type=TYPE,TYPE-SPECIFIC-OPTION[,...]
150
151
152       Attach a filesystem mount to the container
153
154
155       Current supported mount TYPES are bind, cache, secret and tmpfs.
156
157
158                 e.g.
159
160                 mount=type=bind,source=/path/on/host,destination=/path/in/container
161
162                 mount=type=tmpfs,tmpfs-size=512M,destination=/path/in/container
163
164                 mount=type=secret,id=mysecret cat /run/secrets/mysecret
165
166                 Common Options:
167
168                        · 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
170                        · dst, destination, target: mount destination spec.
171
172                        · ro, read-only: true or false (default).
173
174                 Options specific to bind:
175
176                        · bind-propagation: shared, slave, private, rshared, rslave, or rprivate(default). See also mount(2).
177
178                        . bind-nonrecursive: do not setup a recursive bind mount.  By default it is recursive.
179
180                        · from: stage or image name for the root of the source. Defaults to the build context.
181
182                 Options specific to tmpfs:
183
184                        · tmpfs-size: Size of the tmpfs mount in bytes. Unlimited by default in Linux.
185
186                        · tmpfs-mode: File mode of the tmpfs in octal. (e.g. 700 or 0700.) Defaults to 1777 in Linux.
187
188                        · tmpcopyup: Path that is shadowed by the tmpfs mount is recursively copied up to the tmpfs itself.
189
190              Options specific to cache:
191
192                        · id: Create a separate cache directory for a particular id.
193
194                        · mode: File mode for new cache directory in octal. Default 0755.
195
196                        · ro, readonly: read only cache if set.
197
198                        · uid: uid for cache directory.
199
200                        · gid: gid for cache directory.
201
202                        · from: stage name for the root of the source. Defaults to host cache directory.
203
204
205
206       RUN Secrets
207
208
209       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
216
217       Container  engines pass secret the secret file into the build using the
218       --secret flag.
219
220
221       --mount=type=secret,TYPE-SPECIFIC-OPTION[,...]
222
223
224id 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
229dst|target|destination  rename  the  secret file to a specific
230                file in the Containerfile RUN command to use.
231
232type=secret tells the --mount command that it is mounting in a
233                secret file
234
235                     # shows secret from default secret location:
236                     RUN --mount=type=secret,id=mysecret cat /run/secrets/mysecret
237
238
239
240                     # shows secret from custom secret location:
241                     RUN --mount=type=secret,id=mysecret,dst=/foobar cat /foobar
242
243
244
245
246
247       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
250
251               buildah bud --no-cache --secret id=mysecret,src=mysecret.txt .
252
253
254
255       -- 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
261
262       -- 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
273
274       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
278
279       CMD
280         -- CMD has three forms:
281
282
283                # Executable form
284                CMD ["executable", "param1", "param2"]`
285
286                # Provide default arguments to ENTRYPOINT
287                CMD ["param1", "param2"]`
288
289                # the command is run in a shell - /bin/sh -c
290                CMD command param1 param2
291
292
293
294       -- 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
308
309       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
313
314                FROM ubuntu
315                CMD echo "This is a test." | wc -
316
317
318
319       -- 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
327
328                FROM ubuntu
329                CMD ["/usr/bin/wc","--help"]
330
331
332
333       -- 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
345
346       LABEL
347         -- LABEL <key>=<value> [<key>=<value> ...]or
348
349
350                LABEL <key>[ <value>]
351                LABEL <key>[ <value>]
352                ...
353
354
355
356       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
362
363                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
369
370
371       An image can have more than one label. To specify multiple labels, sep‐
372       arate
373         each key-value pair by a space.
374
375
376       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
381
382       To display an image's labels, use the buildah inspect command.
383
384
385       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
395
396       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
409
410       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
416
417       ADD
418         -- ADD has two forms:
419
420
421                ADD <src> <dest>
422
423                # Required for paths with whitespace
424                ADD ["<src>",... "<dest>"]
425
426
427
428       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
450
451       COPY
452         -- COPY has two forms:
453
454
455                COPY <src> <dest>
456
457                # Required for paths with whitespace
458                COPY ["<src>",... "<dest>"]
459
460
461
462       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
479
480       ENTRYPOINT
481         -- ENTRYPOINT has two forms:
482
483
484                # executable form
485                ENTRYPOINT ["executable", "param1", "param2"]`
486
487                # run command in a shell - /bin/sh -c
488                ENTRYPOINT command param1 param2
489
490
491
492       -- 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
513
514                FROM ubuntu
515                ENTRYPOINT wc -l -
516
517
518
519       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
525
526                FROM ubuntu
527                CMD ["-l", "-"]
528                ENTRYPOINT ["/usr/bin/wc"]
529
530
531
532       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
540
541       USER
542         -- USER daemon
543         Sets the username or UID used for running subsequent commands.
544
545
546       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
551
552       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
558
559       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
569
570                WORKDIR /a
571                WORKDIR b
572                WORKDIR c
573                RUN pwd
574
575
576
577       In the above example, the output of the pwd command is a/b/c.
578
579
580       ARG
581          -- ARG [=]
582
583
584       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
592
593       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
599
600                [Warning] One or more build-args [foo] were not consumed
601
602
603
604       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
609
610                FROM busybox
611                ARG user1
612                ARG buildno
613                ...
614
615
616
617       A Containerfile author may optionally specify a default  value  for  an
618       ARG instruction:
619
620
621                FROM busybox
622                ARG user1=someuser
623                ARG buildno=1
624                ...
625
626
627
628       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
632
633       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
639
640                1 FROM busybox
641                2 USER ${user:-some_user}
642                3 ARG user
643                4 USER $user
644                ...
645
646
647
648       A user builds this file by calling:
649
650
651                $ podman build --build-arg user=what_user Containerfile
652
653
654
655       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
663
664              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
670
671
672       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
679
680                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
685
686
687       Then, assume this image is built with this command:
688
689
690                $ podman build --build-arg CONT_IMG_VER=v2.0.1 Containerfile
691
692
693
694       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
702
703       Using the example above but a different ENV specification you can  cre‐
704       ate more
705         useful interactions between ARG and ENV instructions:
706
707
708                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
713
714
715       Unlike an ARG instruction, ENV values are always persisted in the built
716         image. Consider a podman build without the --build-arg flag:
717
718
719                $ podman build Containerfile
720
721
722
723       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
728
729       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
737
738       Container engines have a set of predefined ARG variables that  you  can
739       use without a
740         corresponding ARG instruction in the Containerfile.
741
742
743HTTP_PROXY
744
745http_proxy
746
747HTTPS_PROXY
748
749https_proxy
750
751FTP_PROXY
752
753ftp_proxy
754
755NO_PROXY
756
757no_proxy
758
759ALL_PROXY
760
761all_proxy
762
763
764
765       To use these, pass them on the command line using --build-arg flag, for
766         example:
767
768
769                $ podman build --build-arg HTTPS_PROXY=https://my-proxy.example.com .
770
771
772
773       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
784
785       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
793
794       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
804
805       -- 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
813

SEE ALSO

815       buildah(1), podman(1), docker(1)
816
817
818

HISTORY

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
826
827
828
829                                   Aug 2021                   CONTAINERFILE(5)
Impressum