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 FROM as its first instruction. The im‐
94       age can be any
95         valid image. It is easy to start by pulling an image from the public
96         repositories.
97
98
99       -- FROM must appear at least once in the Containerfile.
100
101
102       -- FROM The first FROM command must come before all other  instructions
103       in
104         the Containerfile except ARG
105
106
107       --  FROM may appear multiple times within a single Containerfile in or‐
108       der to create
109         multiple images. Make a note of the last image ID output by the  com‐
110       mit before
111         each new FROM command.
112
113
114       --  If no tag is given to the FROM instruction, container engines apply
115       the
116         latest tag. If the used tag does not exist, an error is returned.
117
118
119       -- If no digest is given to the FROM instruction, container engines ap‐
120       ply the
121         latest tag. If the used tag does not exist, an error is returned.
122
123
124       MAINTAINER
125         -- MAINTAINER sets the Author field for the generated images.
126         Useful for providing users with an email or url for support.
127
128
129       RUN
130         -- RUN has two forms:
131
132
133                # the command is run in a shell - /bin/sh -c
134                RUN <command>
135
136                # Executable form
137                RUN ["executable", "param1", "param2"]
138
139
140
141       *RUN Secrets
142
143
144       The  RUN  command has a feature to allow the passing of secret informa‐
145       tion into the image build. These secrets files can be used  during  the
146       RUN  command  but are not committed to the final image. The RUN command
147       supports the --mount option to identify the secret file. A secret  file
148       from  the  host  is mounted into the container while the image is being
149       built.
150
151
152       Container engines pass secret the secret file into the build using  the
153       --secret flag.
154
155
156       *RUN --mount options:
157
158
159id is the identifier to for the secret passed into the buildah
160                bud --secret or podman build --secret. This identifier is  as‐
161                sociated  with  the  RUN --mount identifier to use in the Con‐
162                tainerfile.
163
164dst|target|destination rename the secret file  to  a  specific
165                file in the Containerfile RUN command to use.
166
167type=secret tells the --mount command that it is mounting in a
168                secret file
169
170                     # shows secret from default secret location:
171                     RUN --mount=type=secret,id=mysecret cat /run/secrets/mysecret
172
173
174
175                     # shows secret from custom secret location:
176                     RUN --mount=type=secret,id=mysecret,dst=/foobar cat /foobar
177
178
179
180
181
182       The secret needs to be passed to the build using the --secret flag. The
183       final image built does not container the secret file:
184
185
186               buildah bud --no-cache --secret id=mysecret,src=mysecret.txt .
187
188
189
190       --  The  RUN instruction executes any commands in a new layer on top of
191       the current
192         image and commits the results. The committed image is  used  for  the
193       next step in
194         Containerfile.
195
196
197       --  Layering  RUN  instructions  and generating commits conforms to the
198       core
199         concepts of container engines where commits are cheap and  containers
200       can be created from
201         any  point in the history of an image. This is similar to source con‐
202       trol.  The
203         exec form makes it possible to avoid shell string munging.  The  exec
204       form makes
205         it  possible to RUN commands using a base image that does not contain
206       /bin/sh.
207
208
209       Note that the exec form is parsed as a JSON array, which means that you
210       must
211         use double-quotes (") around words not single-quotes (').
212
213
214       CMD
215         -- CMD has three forms:
216
217
218                # Executable form
219                CMD ["executable", "param1", "param2"]`
220
221                # Provide default arguments to ENTRYPOINT
222                CMD ["param1", "param2"]`
223
224                # the command is run in a shell - /bin/sh -c
225                CMD command param1 param2
226
227
228
229       --  There  should  be only one CMD in a Containerfile. If more than one
230       CMD is listed, only
231         the last CMD takes effect.
232         The main purpose of a CMD is to provide  defaults  for  an  executing
233       container.
234         These  defaults  may include an executable, or they can omit the exe‐
235       cutable. If
236         they omit the executable, an ENTRYPOINT must be specified.
237         When used in the shell or exec formats, the CMD instruction sets  the
238       command to
239         be executed when running the image.
240         If  you  use  the  shell  form  of the CMD, the <command> executes in
241       /bin/sh -c:
242
243
244       Note that the exec form is parsed as a JSON array, which means that you
245       must
246         use double-quotes (") around words not single-quotes (').
247
248
249                FROM ubuntu
250                CMD echo "This is a test." | wc -
251
252
253
254       --  If  you run command without a shell, then you must express the com‐
255       mand as a
256         JSON array and give the full path to the executable. This array  form
257       is the
258         preferred form of CMD. All additional parameters must be individually
259       expressed
260         as strings in the array:
261
262
263                FROM ubuntu
264                CMD ["/usr/bin/wc","--help"]
265
266
267
268       -- To make the container run the same executable every time, use ENTRY‐
269       POINT in
270         combination with CMD.
271         If  the  user  specifies  arguments  to podman run or docker run, the
272       specified commands
273         override the default in CMD.
274         Do not confuse RUN with CMD. RUN runs a command and commits  the  re‐
275       sult.
276         CMD  executes  nothing at build time, but specifies the intended com‐
277       mand for
278         the image.
279
280
281       LABEL
282         -- LABEL <key>=<value> [<key>=<value> ...]or
283
284
285                LABEL <key>[ <value>]
286                LABEL <key>[ <value>]
287                ...
288
289
290
291       The LABEL instruction adds metadata to an image. A LABEL is a
292         key-value pair. To specify a LABEL without a  value,  simply  use  an
293       empty
294         string. To include spaces within a LABEL value, use quotes and
295         backslashes as you would in command-line parsing.
296
297
298                LABEL com.example.vendor="ACME Incorporated"
299                LABEL com.example.vendor "ACME Incorporated"
300                LABEL com.example.vendor.is-beta ""
301                LABEL com.example.vendor.is-beta=
302                LABEL com.example.vendor.is-beta=""
303
304
305
306       An image can have more than one label. To specify multiple labels, sep‐
307       arate
308         each key-value pair by a space.
309
310
311       Labels are additive including LABELs in FROM images. As the system
312         encounters and then applies a new label, new keys override any previ‐
313       ous
314         labels with identical keys.
315
316
317       To display an image's labels, use the buildah inspect command.
318
319
320       EXPOSE
321         -- EXPOSE <port> [<port>...]
322         The  EXPOSE  instruction  informs  the container engine that the con‐
323       tainer listens on the
324         specified network ports at runtime. The container  engine  uses  this
325       information to
326         interconnect containers using links and to set up port redirection on
327       the host
328         system.
329
330
331       ENV
332         -- ENV <key> <value>
333         The ENV instruction sets the environment variable  to
334         the value <value>. This value is passed to all future
335         RUN, ENTRYPOINT, and CMD instructions. This is
336         functionally equivalent to prefixing the command with  <key>=<value>.
337       The
338         environment  variables that are set with ENV persist when a container
339       is run
340         from the resulting image. Use podman inspect to inspect these values,
341       and
342         change them using podman run --env <key>=<value>.
343
344
345       Note that setting "ENV DEBIAN_FRONTEND=noninteractive" may cause
346         unintended  consequences,  because it will persist when the container
347       is run
348         interactively, as with the following command: podman run -t -i  image
349       bash
350
351
352       ADD
353         -- ADD has two forms:
354
355
356                ADD <src> <dest>
357
358                # Required for paths with whitespace
359                ADD ["<src>",... "<dest>"]
360
361
362
363       The ADD instruction copies new files, directories
364         or  remote  file  URLs  to  the  filesystem  of the container at path
365       <dest>.
366         Multiple <src> resources may be specified but if they  are  files  or
367       directories
368         then  they  must  be  relative  to the source directory that is being
369       built
370         (the context of the build). The <dest> is the absolute path, or  path
371       relative
372         to  WORKDIR,  into  which the source is copied inside the target con‐
373       tainer.
374         If the <src> argument is a local file  in  a  recognized  compression
375       format
376         (tar,  gzip,  bzip2, etc) then it is unpacked at the specified <dest>
377       in the
378         container's filesystem.  Note that only local compressed  files  will
379       be unpacked,
380         i.e.,  the URL download and archive unpacking features cannot be used
381       together.
382         All new directories are created with mode 0755 and with the  uid  and
383       gid of 0.
384
385
386       COPY
387         -- COPY has two forms:
388
389
390                COPY <src> <dest>
391
392                # Required for paths with whitespace
393                COPY ["<src>",... "<dest>"]
394
395
396
397       The COPY instruction copies new files from <src> and
398         adds them to the filesystem of the container at path . The <src> must
399       be
400         the path to a file or directory relative to the source directory that
401       is
402         being  built  (the  context  of  the build) or a remote file URL. The
403       <dest> is an
404         absolute path, or a path relative to WORKDIR, into which  the  source
405       will
406         be copied inside the target container. If you COPY an archive file it
407       will
408         land in the container exactly as it  appears  in  the  build  context
409       without any
410         attempt to unpack it.  All new files and directories are created with
411       mode 0755
412         and with the uid and gid of 0.
413
414
415       ENTRYPOINT
416         -- ENTRYPOINT has two forms:
417
418
419                # executable form
420                ENTRYPOINT ["executable", "param1", "param2"]`
421
422                # run command in a shell - /bin/sh -c
423                ENTRYPOINT command param1 param2
424
425
426
427       -- An ENTRYPOINT helps you configure a
428         container that can be run as an executable. When you specify  an  EN‐
429       TRYPOINT,
430         the  whole container runs as if it was only that executable.  The EN‐
431       TRYPOINT
432         instruction adds an entry command that is not overwritten when  argu‐
433       ments are
434         passed  to  podman  run.  This is different from the behavior of CMD.
435       This allows
436         arguments to be passed to the entrypoint,  for  instance  podman  run
437       <image> -d
438         passes  the -d argument to the ENTRYPOINT.  Specify parameters either
439       in the
440         ENTRYPOINT JSON array (as in the preferred exec form  above),  or  by
441       using a CMD
442         statement.   Parameters  in the ENTRYPOINT are not overwritten by the
443       podman run arguments.  Parameters specified via CMD are overwritten  by
444       podman  run  arguments.  Specify a plain string for the ENTRYPOINT, and
445       it will execute in
446         /bin/sh -c, like a CMD instruction:
447
448
449                FROM ubuntu
450                ENTRYPOINT wc -l -
451
452
453
454       This means that the Containerfile's image always takes stdin  as  input
455       (that's
456         what  "-"  means),  and  prints the number of lines (that's what "-l"
457       means). To
458         make this optional but default, use a CMD:
459
460
461                FROM ubuntu
462                CMD ["-l", "-"]
463                ENTRYPOINT ["/usr/bin/wc"]
464
465
466
467       VOLUME
468         -- VOLUME ["/data"]
469         The VOLUME instruction creates a mount point with the specified  name
470       and marks
471         it as holding externally-mounted volumes from the native host or from
472       other
473         containers.
474
475
476       USER
477         -- USER daemon
478         Sets the username or UID used for running subsequent commands.
479
480
481       The USER instruction can optionally be used to set the  group  or  GID.
482       The
483         following examples are all valid:
484         USER [user | user:group | uid | uid:gid | user:gid | uid:group ]
485
486
487       Until  the  USER  instruction is set, instructions will be run as root.
488       The USER
489         instruction can be used any number of times in a  Containerfile,  and
490       will only affect
491         subsequent commands.
492
493
494       WORKDIR
495         -- WORKDIR /path/to/workdir
496         The WORKDIR instruction sets the working directory for the RUN, CMD,
497         ENTRYPOINT,  COPY  and  ADD Containerfile commands that follow it. It
498       can
499         be used multiple times in a single Containerfile. Relative paths  are
500       defined
501         relative  to  the path of the previous WORKDIR instruction. For exam‐
502       ple:
503
504
505                WORKDIR /a
506                WORKDIR b
507                WORKDIR c
508                RUN pwd
509
510
511
512       In the above example, the output of the pwd command is a/b/c.
513
514
515       ARG
516          -- ARG [=]
517
518
519       The ARG instruction defines a variable that users can  pass  at  build-
520       time to
521         the  builder  with  the podman build and buildah build commands using
522       the
523         --build-arg <varname>=<value> flag. If a user specifies a build argu‐
524       ment that
525         was not defined in the Containerfile, the build outputs a warning.
526
527
528       Note  that  a second FROM in a Containerfile sets the values associated
529       with an
530         Arg variable to nil and they must be reset if they  are  to  be  used
531       later in
532         the Containerfile
533
534
535                [Warning] One or more build-args [foo] were not consumed
536
537
538
539       The Containerfile author can define a single variable by specifying ARG
540       once or many
541         variables by specifying ARG more than once. For example, a valid Con‐
542       tainerfile:
543
544
545                FROM busybox
546                ARG user1
547                ARG buildno
548                ...
549
550
551
552       A  Containerfile  author  may optionally specify a default value for an
553       ARG instruction:
554
555
556                FROM busybox
557                ARG user1=someuser
558                ARG buildno=1
559                ...
560
561
562
563       If an ARG value has a default and if there is no value passed at build-
564       time, the
565         builder uses the default.
566
567
568       An  ARG variable definition comes into effect from the line on which it
569       is
570         defined in the Containerfile not from the argument's use on the  com‐
571       mand-line or
572         elsewhere.  For example, consider this Containerfile:
573
574
575                1 FROM busybox
576                2 USER ${user:-some_user}
577                3 ARG user
578                4 USER $user
579                ...
580
581
582
583       A user builds this file by calling:
584
585
586                $ podman build --build-arg user=what_user Containerfile
587
588
589
590       The  USER  at line 2 evaluates to some_user as the user variable is de‐
591       fined on the
592         subsequent line 3. The USER at line 4 evaluates to what_user as  user
593       is
594         defined and the what_user value was passed on the command line. Prior
595       to its definition by an
596         ARG instruction, any use of a variable results in an empty string.
597
598
599              Warning: It is not recommended to use build-time variables for
600               passing secrets like github keys, user credentials etc.  Build-
601              time variable
602               values  are  visible  to  any user of the image with the podman
603              history command.
604
605
606
607       You can use an ARG or an ENV instruction to specify variables that are
608         available to the RUN instruction. Environment variables defined using
609       the
610         ENV  instruction always override an ARG instruction of the same name.
611       Consider
612         this Containerfile with an ENV and ARG instruction.
613
614
615                1 FROM ubuntu
616                2 ARG CONT_IMG_VER
617                3 ENV CONT_IMG_VER=v1.0.0
618                4 RUN echo $CONT_IMG_VER
619
620
621
622       Then, assume this image is built with this command:
623
624
625                $ podman build --build-arg CONT_IMG_VER=v2.0.1 Containerfile
626
627
628
629       In this case, the RUN instruction uses v1.0.0 instead of the  ARG  set‐
630       ting
631         passed by the user:v2.0.1 This behavior is similar to a shell
632         script where a locally scoped variable overrides the variables passed
633       as
634         arguments or inherited from environment, from its  point  of  defini‐
635       tion.
636
637
638       Using  the example above but a different ENV specification you can cre‐
639       ate more
640         useful interactions between ARG and ENV instructions:
641
642
643                1 FROM ubuntu
644                2 ARG CONT_IMG_VER
645                3 ENV CONT_IMG_VER=${CONT_IMG_VER:-v1.0.0}
646                4 RUN echo $CONT_IMG_VER
647
648
649
650       Unlike an ARG instruction, ENV values are always persisted in the built
651         image. Consider a podman build without the --build-arg flag:
652
653
654                $ podman build Containerfile
655
656
657
658       Using this Containerfile example, CONT_IMG_VER is  still  persisted  in
659       the image but
660         its  value  would be v1.0.0 as it is the default set in line 3 by the
661       ENV instruction.
662
663
664       The variable expansion technique in this example allows you to pass ar‐
665       guments
666         from the command line and persist them in the final image by leverag‐
667       ing the
668         ENV instruction. Variable expansion is only supported for  a  limited
669       set of
670         Containerfile instructions.  ⟨#environment-replacement⟩
671
672
673       Container  engines  have a set of predefined ARG variables that you can
674       use without a
675         corresponding ARG instruction in the Containerfile.
676
677
678HTTP_PROXY
679
680http_proxy
681
682HTTPS_PROXY
683
684https_proxy
685
686FTP_PROXY
687
688ftp_proxy
689
690NO_PROXY
691
692no_proxy
693
694ALL_PROXY
695
696all_proxy
697
698
699
700       To use these, pass them on the command line using --build-arg flag, for
701         example:
702
703
704                $ podman build --build-arg HTTPS_PROXY=https://my-proxy.example.com .
705
706
707
708       ONBUILD
709         -- ONBUILD [INSTRUCTION]
710         The ONBUILD instruction adds a trigger instruction to an image. The
711         trigger is executed at a later time, when the image is  used  as  the
712       base for
713         another  build.  Container engines execute the trigger in the context
714       of the downstream
715         build, as if the trigger existed immediately after the FROM  instruc‐
716       tion in
717         the downstream Containerfile.
718
719
720       You  can register any build instruction as a trigger. A trigger is use‐
721       ful if
722         you are defining an image to use as a base for building other images.
723       For
724         example,  if  you  are defining an application build environment or a
725       daemon that
726         is customized with a user-specific configuration.
727
728
729       Consider an image intended as a reusable python application builder. It
730       must
731         add application source code to a particular directory, and might need
732       a build
733         script called after that. You can't just call ADD and  RUN  now,  be‐
734       cause
735         you  don't  yet have access to the application source code, and it is
736       different
737         for each application build.
738
739
740       -- Providing application developers with a boilerplate Containerfile to
741       copy-paste
742         into their application is inefficient, error-prone, and
743         difficult to update because it mixes with application-specific code.
744         The  solution  is to use ONBUILD to register instructions in advance,
745       to
746         run later, during the next build stage.
747
748

SEE ALSO

750       buildah(1), podman(1), docker(1)
751
752
753

HISTORY

755              May 2014, Compiled by Zac Dover (zdover at redhat dot com) based on docker.com Dockerfile documentation.
756              Feb 2015, updated by Brian Goff (cpuguy83@gmail.com) for readability
757              Sept 2015, updated by Sally O'Malley (somalley@redhat.com)
758              Oct 2016, updated by Addam Hardy (addam.hardy@gmail.com)
759              Aug 2021, converted Dockerfile man page to Containerfile by Dan Walsh (dwalsh@redhat.com)
760
761
762
763
764                                   Aug 2021                   CONTAINERFILE(5)
Impressum