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 STOPSIGNAL
258 -- 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 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 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 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 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 ADD
308 -- ADD has two forms:
309 ADD <src> <dest>
312 # Required for paths with whitespace
314 ADD ["<src>",... "<dest>"]
315 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 COPY
342 -- COPY has two forms:
343 COPY <src> <dest>
346 # Required for paths with whitespace
348 COPY ["<src>",... "<dest>"]
349 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 ENTRYPOINT
371 -- ENTRYPOINT has two forms:
372 # executable form
375 ENTRYPOINT ["executable", "param1", "param2"]`
376 # run command in a shell - /bin/sh -c
378 ENTRYPOINT command param1 param2
379 -- 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 FROM ubuntu
407 ENTRYPOINT wc -l -
408 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 FROM ubuntu
419 CMD ["-l", "-"]
420 ENTRYPOINT ["/usr/bin/wc"]
421 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 USER
434 -- USER daemon
435 Sets the username or UID used for running subsequent commands.
436 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 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 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 WORKDIR /a
462 WORKDIR b
463 WORKDIR c
464 RUN pwd
465 In the above example, the output of the pwd command is a/b/c.
469 ARG
472 -- ARG [=]
473 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 [Warning] One or more build-args [foo] were not consumed
484 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 FROM busybox
494 ARG user1
495 ARG buildno
496 ...
497 A Dockerfile author may optionally specify a default value for an ARG
501 instruction:
502 FROM busybox
505 ARG user1=someuser
506 ARG buildno=1
507 ...
508 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 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 1 FROM busybox
524 2 USER ${user:-some_user}
525 3 ARG user
526 4 USER $user
527 ...
528 A user builds this file by calling:
532 $ docker build --build-arg user=what_user Dockerfile
535 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 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 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 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 Then, assume this image is built with this command:
571 $ docker build --build-arg CONT_IMG_VER=v2.0.1 Dockerfile
574 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 Using the example above but a different ENV specification you can cre‐
587 ate more
588 useful interactions between ARG and ENV instructions:
589 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 Unlike an ARG instruction, ENV values are always persisted in the built
599 image. Consider a docker build without the --build-arg flag:
600 $ docker build Dockerfile
603 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 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 Docker has a set of predefined ARG variables that you can use without a
622 corresponding ARG instruction in the Dockerfile.
623 • HTTP_PROXY
626 • http_proxy
628 • HTTPS_PROXY
630 • https_proxy
632 • FTP_PROXY
634 • ftp_proxy
636 • NO_PROXY
638 • no_proxy
640 To use these, pass them on the command line using --build-arg flag, for
644 example:
645 $ docker build --build-arg HTTPS_PROXY=https://my-proxy.example.com .
648 ONBUILD
652 -- ONBUILD [INSTRUCTION]
653 The ONBUILD instruction adds a trigger instruction to an image. The
654 trigger is executed at a later time, when the image is used as the
655 base for
656 another build. Docker executes the trigger in the context of the
657 downstream
658 build, as if the trigger existed immediately after the FROM instruc‐
659 tion in
660 the downstream Dockerfile.
661 You can register any build instruction as a trigger. A trigger is use‐
664 ful if
665 you are defining an image to use as a base for building other images.
666 For
667 example, if you are defining an application build environment or a
668 daemon that
669 is customized with a user-specific configuration.
670 Consider an image intended as a reusable python application builder. It
673 must
674 add application source code to a particular directory, and might need
675 a build
676 script called after that. You can't just call ADD and RUN now, be‐
677 cause
678 you don't yet have access to the application source code, and it is
679 different
680 for each application build.
681 -- Providing application developers with a boilerplate Dockerfile to
684 copy-paste
685 into their application is inefficient, error-prone, and
686 difficult to update because it mixes with application-specific code.
687 The solution is to use ONBUILD to register instructions in advance,
688 to
689 run later, during the next build stage.
690
694 *May 2014, Compiled by Zac Dover (zdover at redhat dot com) based on
695 docker.com Dockerfile documentation. *Feb 2015, updated by Brian Goff
696 (cpuguy83@gmail.com) for readability *Sept 2015, updated by Sally
697 O'Malley (somalley@redhat.com) *Oct 2016, updated by Addam Hardy (ad‐
698 dam.hardy@gmail.com)
699Docker Community MAY 2014 DOCKERFILE(5)