1DOCKERFILE(5) Docker User Manuals DOCKERFILE(5)
2
6 Dockerfile - automate the steps of creating a Docker image
7
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 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
25 INSTRUCTION arguments
26 For example:
29 FROM image
32
36 A Dockerfile is a file that automates the steps of creating a Docker
37 image. A Dockerfile is similar to a Makefile.
38
42 docker build .
43 -- 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 docker build -t repository/tag .
56 -- 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 Docker re-uses intermediate images whenever possible. This signifi‐
70 cantly
71 accelerates the docker build process.
72
76 FROM image
77 FROM image:tag
80 FROM image@digest
83 -- 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 -- FROM must be the first non-comment instruction in Dockerfile.
94 -- 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 -- 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 -- 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 MAINTAINER
112 -- MAINTAINER sets the Author field for the generated images.
113 Useful for providing users with an email or url for support.
114 RUN
117 -- RUN has two forms:
118 # the command is run in a shell - /bin/sh -c
121 RUN <command>
122 # Executable form
124 RUN ["executable", "param1", "param2"]
125 -- 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 -- 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 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 CMD
153 -- CMD has three forms:
154 # Executable form
157 CMD ["executable", "param1", "param2"]`
158 # Provide default arguments to ENTRYPOINT
160 CMD ["param1", "param2"]`
161 # the command is run in a shell - /bin/sh -c
163 CMD command param1 param2
164 -- 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 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 FROM ubuntu
188 CMD echo "This is a test." | wc -
189 -- 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 FROM ubuntu
202 CMD ["/usr/bin/wc","--help"]
203 -- 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 LABEL
219 -- LABEL <key>=<value> [<key>=<value> ...]or
220 LABEL <key>[ <value>]
223 LABEL <key>[ <value>]
224 ...
225 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 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 An image can have more than one label. To specify multiple labels, sep‐
244 arate
245 each key-value pair by a space.
246 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 To display an image's labels, use the docker inspect command.
255 EXPOSE
258 -- EXPOSE <port> [<port>...]
259 The EXPOSE instruction informs Docker that the container listens on
260 the
261 specified network ports at runtime. Docker uses this information to
262 interconnect containers using links and to set up port redirection on
263 the host
264 system.
265 ENV
268 -- ENV <key> <value>
269 The ENV instruction sets the environment variable to
270 the value <value>. This value is passed to all future
271 RUN, ENTRYPOINT, and CMD instructions. This is
272 functionally equivalent to prefixing the command with <key>=<value>.
273 The
274 environment variables that are set with ENV persist when a container
275 is run
276 from the resulting image. Use docker inspect to inspect these values,
277 and
278 change them using docker run --env <key>=<value>.
279 Note that setting "ENV DEBIAN_FRONTEND=noninteractive" may cause
282 unintended consequences, because it will persist when the container
283 is run
284 interactively, as with the following command: docker run -t -i image
285 bash
286 ADD
289 -- ADD has two forms:
290 ADD <src> <dest>
293 # Required for paths with whitespace
295 ADD ["<src>",... "<dest>"]
296 The ADD instruction copies new files, directories
300 or remote file URLs to the filesystem of the container at path
301 <dest>.
302 Multiple <src> resources may be specified but if they are files or
303 directories
304 then they must be relative to the source directory that is being
305 built
306 (the context of the build). The <dest> is the absolute path, or path
307 relative
308 to WORKDIR, into which the source is copied inside the target con‐
309 tainer.
310 If the <src> argument is a local file in a recognized compression
311 format
312 (tar, gzip, bzip2, etc) then it is unpacked at the specified <dest>
313 in the
314 container's filesystem. Note that only local compressed files will
315 be unpacked,
316 i.e., the URL download and archive unpacking features cannot be used
317 together.
318 All new directories are created with mode 0755 and with the uid and
319 gid of 0.
320 COPY
323 -- COPY has two forms:
324 COPY <src> <dest>
327 # Required for paths with whitespace
329 COPY ["<src>",... "<dest>"]
330 The COPY instruction copies new files from <src> and
334 adds them to the filesystem of the container at path . The <src> must
335 be
336 the path to a file or directory relative to the source directory that
337 is
338 being built (the context of the build) or a remote file URL. The
339 <dest> is an
340 absolute path, or a path relative to WORKDIR, into which the source
341 will
342 be copied inside the target container. If you COPY an archive file it
343 will
344 land in the container exactly as it appears in the build context
345 without any
346 attempt to unpack it. All new files and directories are created with
347 mode 0755
348 and with the uid and gid of 0.
349 ENTRYPOINT
352 -- ENTRYPOINT has two forms:
353 # executable form
356 ENTRYPOINT ["executable", "param1", "param2"]`
357 # run command in a shell - /bin/sh -c
359 ENTRYPOINT command param1 param2
360 -- An ENTRYPOINT helps you configure a
364 container that can be run as an executable. When you specify an EN‐
365 TRYPOINT,
366 the whole container runs as if it was only that executable. The EN‐
367 TRYPOINT
368 instruction adds an entry command that is not overwritten when argu‐
369 ments are
370 passed to docker run. This is different from the behavior of CMD.
371 This allows
372 arguments to be passed to the entrypoint, for instance docker run
373 <image> -d
374 passes the -d argument to the ENTRYPOINT. Specify parameters either
375 in the
376 ENTRYPOINT JSON array (as in the preferred exec form above), or by
377 using a CMD
378 statement. Parameters in the ENTRYPOINT are not overwritten by the
379 docker run
380 arguments. Parameters specified via CMD are overwritten by docker
381 run
382 arguments. Specify a plain string for the ENTRYPOINT, and it will
383 execute in
384 /bin/sh -c, like a CMD instruction:
385 FROM ubuntu
388 ENTRYPOINT wc -l -
389 This means that the Dockerfile's image always takes stdin as input
393 (that's
394 what "-" means), and prints the number of lines (that's what "-l"
395 means). To
396 make this optional but default, use a CMD:
397 FROM ubuntu
400 CMD ["-l", "-"]
401 ENTRYPOINT ["/usr/bin/wc"]
402 VOLUME
406 -- VOLUME ["/data"]
407 The VOLUME instruction creates a mount point with the specified name
408 and marks
409 it as holding externally-mounted volumes from the native host or from
410 other
411 containers.
412 USER
415 -- USER daemon
416 Sets the username or UID used for running subsequent commands.
417 The USER instruction can optionally be used to set the group or GID.
420 The
421 followings examples are all valid:
422 USER [user | user:group | uid | uid:gid | user:gid | uid:group ]
423 Until the USER instruction is set, instructions will be run as root.
426 The USER
427 instruction can be used any number of times in a Dockerfile, and will
428 only affect
429 subsequent commands.
430 WORKDIR
433 -- WORKDIR /path/to/workdir
434 The WORKDIR instruction sets the working directory for the RUN, CMD,
435 ENTRYPOINT, COPY and ADD Dockerfile commands that follow it. It can
436 be used multiple times in a single Dockerfile. Relative paths are de‐
437 fined
438 relative to the path of the previous WORKDIR instruction. For exam‐
439 ple:
440 WORKDIR /a
443 WORKDIR b
444 WORKDIR c
445 RUN pwd
446 In the above example, the output of the pwd command is a/b/c.
450 ARG
453 -- ARG [=]
454 The ARG instruction defines a variable that users can pass at
457 build-time to
458 the builder with the docker build command using the --build-arg
459 <varname>=<value> flag. If a user specifies a build argument that was
460 not
461 defined in the Dockerfile, the build outputs a warning.
462 [Warning] One or more build-args [foo] were not consumed
465 The Dockerfile author can define a single variable by specifying ARG
469 once or many
470 variables by specifying ARG more than once. For example, a valid
471 Dockerfile:
472 FROM busybox
475 ARG user1
476 ARG buildno
477 ...
478 A Dockerfile author may optionally specify a default value for an ARG
482 instruction:
483 FROM busybox
486 ARG user1=someuser
487 ARG buildno=1
488 ...
489 If an ARG value has a default and if there is no value passed at
493 build-time, the
494 builder uses the default.
495 An ARG variable definition comes into effect from the line on which it
498 is
499 defined in the Dockerfile not from the argument's use on the com‐
500 mand-line or
501 elsewhere. For example, consider this Dockerfile:
502 1 FROM busybox
505 2 USER ${user:-some_user}
506 3 ARG user
507 4 USER $user
508 ...
509 A user builds this file by calling:
513 $ docker build --build-arg user=what_user Dockerfile
516 The USER at line 2 evaluates to some_user as the user variable is de‐
520 fined on the
521 subsequent line 3. The USER at line 4 evaluates to what_user as user
522 is
523 defined and the what_user value was passed on the command line. Prior
524 to its definition by an
525 ARG instruction, any use of a variable results in an empty string.
526 Warning: It is not recommended to use build-time variables for
529 passing secrets like github keys, user credentials etc.
530 Build-time variable
531 values are visible to any user of the image with the docker
532 history command.
533 You can use an ARG or an ENV instruction to specify variables that are
537 available to the RUN instruction. Environment variables defined using
538 the
539 ENV instruction always override an ARG instruction of the same name.
540 Consider
541 this Dockerfile with an ENV and ARG instruction.
542 1 FROM ubuntu
545 2 ARG CONT_IMG_VER
546 3 ENV CONT_IMG_VER=v1.0.0
547 4 RUN echo $CONT_IMG_VER
548 Then, assume this image is built with this command:
552 $ docker build --build-arg CONT_IMG_VER=v2.0.1 Dockerfile
555 In this case, the RUN instruction uses v1.0.0 instead of the ARG set‐
559 ting
560 passed by the user:v2.0.1 This behavior is similar to a shell
561 script where a locally scoped variable overrides the variables passed
562 as
563 arguments or inherited from environment, from its point of defini‐
564 tion.
565 Using the example above but a different ENV specification you can cre‐
568 ate more
569 useful interactions between ARG and ENV instructions:
570 1 FROM ubuntu
573 2 ARG CONT_IMG_VER
574 3 ENV CONT_IMG_VER=${CONT_IMG_VER:-v1.0.0}
575 4 RUN echo $CONT_IMG_VER
576 Unlike an ARG instruction, ENV values are always persisted in the built
580 image. Consider a docker build without the --build-arg flag:
581 $ docker build Dockerfile
584 Using this Dockerfile example, CONT_IMG_VER is still persisted in the
588 image but
589 its value would be v1.0.0 as it is the default set in line 3 by the
590 ENV instruction.
591 The variable expansion technique in this example allows you to pass ar‐
594 guments
595 from the command line and persist them in the final image by leverag‐
596 ing the
597 ENV instruction. Variable expansion is only supported for a limited
598 set of
599 Dockerfile instructions. ⟨#environment-replacement⟩
600 Docker has a set of predefined ARG variables that you can use without a
603 corresponding ARG instruction in the Dockerfile.
604 • HTTP_PROXY
607 • http_proxy
609 • HTTPS_PROXY
611 • https_proxy
613 • FTP_PROXY
615 • ftp_proxy
617 • NO_PROXY
619 • no_proxy
621 To use these, simply pass them on the command line using the
625 --build-arg
626 <varname>=<value> flag.
627 ONBUILD
630 -- ONBUILD [INSTRUCTION]
631 The ONBUILD instruction adds a trigger instruction to an image. The
632 trigger is executed at a later time, when the image is used as the
633 base for
634 another build. Docker executes the trigger in the context of the
635 downstream
636 build, as if the trigger existed immediately after the FROM instruc‐
637 tion in
638 the downstream Dockerfile.
639 You can register any build instruction as a trigger. A trigger is use‐
642 ful if
643 you are defining an image to use as a base for building other images.
644 For
645 example, if you are defining an application build environment or a
646 daemon that
647 is customized with a user-specific configuration.
648 Consider an image intended as a reusable python application builder. It
651 must
652 add application source code to a particular directory, and might need
653 a build
654 script called after that. You can't just call ADD and RUN now, be‐
655 cause
656 you don't yet have access to the application source code, and it is
657 different
658 for each application build.
659 -- Providing application developers with a boilerplate Dockerfile to
662 copy-paste
663 into their application is inefficient, error-prone, and
664 difficult to update because it mixes with application-specific code.
665 The solution is to use ONBUILD to register instructions in advance,
666 to
667 run later, during the next build stage.
668
672 *May 2014, Compiled by Zac Dover (zdover at redhat dot com) based on
673 docker.com Dockerfile documentation. *Feb 2015, updated by Brian Goff
674 (cpuguy83@gmail.com) for readability *Sept 2015, updated by Sally
675 O'Malley (somalley@redhat.com) *Oct 2016, updated by Addam Hardy (ad‐
676 dam.hardy@gmail.com)
677Docker Community MAY 2014 DOCKERFILE(5)