1DOCKERFILE(5)(Docker)                                    DOCKERFILE(5)(Docker)
2
3
4
5Zac Dover May 2014
6
7

NAME

9       Dockerfile - automate the steps of creating a Docker image
10
11
12

INTRODUCTION

14       The Dockerfile is a configuration file that automates the steps of cre‐
15       ating a Docker image.  It  is  similar  to  a  Makefile.  Docker  reads
16       instructions  from  the Dockerfile to automate the steps otherwise per‐
17       formed manually to create an image. To build an image,  create  a  file
18       called Dockerfile.
19
20
21       The  Dockerfile  describes  the steps taken to assemble the image. When
22       the Dockerfile has been created, call the docker build  command,  using
23       the path of directory that contains Dockerfile as the argument.
24
25
26

SYNOPSIS

28       INSTRUCTION arguments
29
30
31       For example:
32
33
34       FROM image
35
36
37

DESCRIPTION

39       A  Dockerfile  is  a file that automates the steps of creating a Docker
40       image.  A Dockerfile is similar to a Makefile.
41
42
43

USAGE

45       docker build .
46
47
48       -- Runs the steps and commits them, building a final image.
49         The path to the source repository defines where to find  the  context
50       of the
51         build. The build is run by the Docker daemon, not the CLI. The whole
52         context must be transferred to the daemon. The Docker CLI reports
53         "Sending  build context to Docker daemon" when the context is sent to
54       the
55         daemon.
56
57
58                docker build -t repository/tag .
59
60
61
62       -- specifies a repository and tag at which to save the new image if the
63       build
64         succeeds. The Docker daemon runs the steps one-by-one, committing the
65       result
66         to a new image if necessary, before finally outputting the ID of  the
67       new
68         image.  The  Docker  daemon automatically cleans up the context it is
69       given.
70
71
72       Docker re-uses intermediate images  whenever  possible.  This  signifi‐
73       cantly
74         accelerates the docker build process.
75
76
77

FORMAT

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

HISTORY

675       *May 2014, Compiled by Zac Dover (zdover at redhat dot  com)  based  on
676       docker.com  Dockerfile documentation.  *Feb 2015, updated by Brian Goff
677       (cpuguy83@gmail.com) for  readability  *Sept  2015,  updated  by  Sally
678       O'Malley  (somalley@redhat.com)  *Oct  2016,  updated  by  Addam  Hardy
679       (addam.hardy@gmail.com)
680
681
682
683Manuals                              User                DOCKERFILE(5)(Docker)
Impressum