1DOCKERFILE(5)                 Docker User Manuals                DOCKERFILE(5)
2
3
4

NAME

6       Dockerfile - automate the steps of creating a Docker image
7
8
9

INTRODUCTION

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

SYNOPSIS

25       INSTRUCTION arguments
26
27
28       For example:
29
30
31       FROM image
32
33
34

DESCRIPTION

36       A  Dockerfile  is  a file that automates the steps of creating a Docker
37       image.  A Dockerfile is similar to a Makefile.
38
39
40

USAGE

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

FORMAT

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

HISTORY

698       *May  2014,  Compiled  by Zac Dover (zdover at redhat dot com) based on
699       docker.com Dockerfile documentation.  *Feb 2015, updated by Brian  Goff
700       (cpuguy83@gmail.com)  for  readability  *Sept  2015,  updated  by Sally
701       O'Malley (somalley@redhat.com) *Oct 2016, updated by Addam  Hardy  (ad‐
702       dam.hardy@gmail.com)
703
704
705
706Docker Community                   MAY 2014                      DOCKERFILE(5)
Impressum