1DOCKERFILE(5)(Docker) DOCKERFILE(5)(Docker)
2Zac Dover May 2014
6
9 Dockerfile - automate the steps of creating a Docker image
10
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 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
28 INSTRUCTION arguments
29 For example:
32 FROM image
35
39 A Dockerfile is a file that automates the steps of creating a Docker
40 image. A Dockerfile is similar to a Makefile.
41
45 docker build .
46 -- 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 docker build -t repository/tag .
59 -- 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 Docker re-uses intermediate images whenever possible. This signifi‐
73 cantly
74 accelerates the docker build process.
75
79 FROM image
80 FROM image:tag
83 FROM image@digest
86 -- 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 -- FROM must be the first non-comment instruction in Dockerfile.
97 -- 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 -- 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 -- 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 MAINTAINER
115 -- MAINTAINER sets the Author field for the generated images.
116 Useful for providing users with an email or url for support.
117 RUN
120 -- RUN has two forms:
121 # the command is run in a shell - /bin/sh -c
124 RUN <command>
125 # Executable form
127 RUN ["executable", "param1", "param2"]
128 -- 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 -- 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 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 CMD
156 -- CMD has three forms:
157 # Executable form
160 CMD ["executable", "param1", "param2"]`
161 # Provide default arguments to ENTRYPOINT
163 CMD ["param1", "param2"]`
164 # the command is run in a shell - /bin/sh -c
166 CMD command param1 param2
167 -- 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 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 FROM ubuntu
191 CMD echo "This is a test." | wc -
192 -- 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 FROM ubuntu
205 CMD ["/usr/bin/wc","--help"]
206 -- 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 LABEL
222 -- LABEL <key>=<value> [<key>=<value> ...]or
223 LABEL <key>[ <value>]
226 LABEL <key>[ <value>]
227 ...
228 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 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 An image can have more than one label. To specify multiple labels, sep‐
247 arate
248 each key-value pair by a space.
249 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 To display an image's labels, use the docker inspect command.
258 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 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 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 ADD
292 -- ADD has two forms:
293 ADD <src> <dest>
296 # Required for paths with whitespace
298 ADD ["<src>",... "<dest>"]
299 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 COPY
326 -- COPY has two forms:
327 COPY <src> <dest>
330 # Required for paths with whitespace
332 COPY ["<src>",... "<dest>"]
333 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 ENTRYPOINT
355 -- ENTRYPOINT has two forms:
356 # executable form
359 ENTRYPOINT ["executable", "param1", "param2"]`
360 # run command in a shell - /bin/sh -c
362 ENTRYPOINT command param1 param2
363 -- 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 FROM ubuntu
391 ENTRYPOINT wc -l -
392 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 FROM ubuntu
403 CMD ["-l", "-"]
404 ENTRYPOINT ["/usr/bin/wc"]
405 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 USER
418 -- USER daemon
419 Sets the username or UID used for running subsequent commands.
420 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 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 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 WORKDIR /a
446 WORKDIR b
447 WORKDIR c
448 RUN pwd
449 In the above example, the output of the pwd command is a/b/c.
453 ARG
456 -- ARG [=]
457 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 [Warning] One or more build-args [foo] were not consumed
468 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 FROM busybox
478 ARG user1
479 ARG buildno
480 ...
481 A Dockerfile author may optionally specify a default value for an ARG
485 instruction:
486 FROM busybox
489 ARG user1=someuser
490 ARG buildno=1
491 ...
492 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 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 1 FROM busybox
508 2 USER ${user:-some_user}
509 3 ARG user
510 4 USER $user
511 ...
512 A user builds this file by calling:
516 $ docker build --build-arg user=what_user Dockerfile
519 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 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 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 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 Then, assume this image is built with this command:
555 $ docker build --build-arg CONT_IMG_VER=v2.0.1 Dockerfile
558 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 Using the example above but a different ENV specification you can cre‐
571 ate more
572 useful interactions between ARG and ENV instructions:
573 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 Unlike an ARG instruction, ENV values are always persisted in the built
583 image. Consider a docker build without the --build-arg flag:
584 $ docker build Dockerfile
587 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 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 Docker has a set of predefined ARG variables that you can use without a
606 corresponding ARG instruction in the Dockerfile.
607 · HTTP_PROXY
610 · http_proxy
612 · HTTPS_PROXY
614 · https_proxy
616 · FTP_PROXY
618 · ftp_proxy
620 · NO_PROXY
622 · no_proxy
624 To use these, simply pass them on the command line using the
628 --build-arg
629 <varname>=<value> flag.
630 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 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 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 -- 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
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)
680Manuals User DOCKERFILE(5)(Docker)