1DOCKERFILE(5) May 2014 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
12 creating a Docker image. It is similar to a Makefile. Docker reads
13 instructions from the Dockerfile to automate the steps otherwise
14 performed 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
70 significantly
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
86 instructions. 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
99 commit 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
138 created from
139 any point in the history of an image. This is similar to source
140 control. 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
173 executable. 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
193 command 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
207 ENTRYPOINT 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
212 result.
213 CMD executes nothing at build time, but specifies the intended
214 command 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,
244 separate
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
250 previous
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 <key> 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
309 container.
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 <dest>. The
335 <src> must 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
365 ENTRYPOINT,
366 the whole container runs as if it was only that executable. The
367 ENTRYPOINT
368 instruction adds an entry command that is not overwritten when
369 arguments 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
437 defined
438 relative to the path of the previous WORKDIR instruction. For
439 example:
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 <name>[=<default value>]
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
500 command-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
520 defined 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
536 available to the RUN instruction. Environment variables defined using
537 the
538 ENV instruction always override an ARG instruction of the same name.
539 Consider
540 this Dockerfile with an ENV and ARG instruction.
541 1 FROM ubuntu
544 2 ARG CONT_IMG_VER
545 3 ENV CONT_IMG_VER v1.0.0
546 4 RUN echo $CONT_IMG_VER
547 Then, assume this image is built with this command:
551 $ docker build --build-arg CONT_IMG_VER=v2.0.1 Dockerfile
554 In this case, the RUN instruction uses v1.0.0 instead of the ARG
558 setting
559 passed by the user:v2.0.1 This behavior is similar to a shell
560 script where a locally scoped variable overrides the variables passed
561 as
562 arguments or inherited from environment, from its point of
563 definition.
564 Using the example above but a different ENV specification you can
567 create more
568 useful interactions between ARG and ENV instructions:
569 1 FROM ubuntu
572 2 ARG CONT_IMG_VER
573 3 ENV CONT_IMG_VER ${CONT_IMG_VER:-v1.0.0}
574 4 RUN echo $CONT_IMG_VER
575 Unlike an ARG instruction, ENV values are always persisted in the built
579 image. Consider a docker build without the --build-arg flag:
580 $ docker build Dockerfile
583 Using this Dockerfile example, CONT_IMG_VER is still persisted in the
587 image but
588 its value would be v1.0.0 as it is the default set in line 3 by the
589 ENV instruction.
590 The variable expansion technique in this example allows you to pass
593 arguments
594 from the command line and persist them in the final image by
595 leveraging the
596 ENV instruction. Variable expansion is only supported for a limited
597 set of
598 Dockerfile instructions. ⟨#environment-replacement⟩
599 Docker has a set of predefined ARG variables that you can use without a
602 corresponding ARG instruction in the Dockerfile.
603 · HTTP_PROXY
606 · http_proxy
608 · HTTPS_PROXY
610 · https_proxy
612 · FTP_PROXY
614 · ftp_proxy
616 · NO_PROXY
618 · no_proxy
620 To use these, simply pass them on the command line using the
624 --build-arg
625 <varname>=<value> flag.
626 ONBUILD
629 -- ONBUILD [INSTRUCTION]
630 The ONBUILD instruction adds a trigger instruction to an image. The
631 trigger is executed at a later time, when the image is used as the
632 base for
633 another build. Docker executes the trigger in the context of the
634 downstream
635 build, as if the trigger existed immediately after the FROM
636 instruction in
637 the downstream Dockerfile.
638 You can register any build instruction as a trigger. A trigger is
641 useful if
642 you are defining an image to use as a base for building other images.
643 For
644 example, if you are defining an application build environment or a
645 daemon that
646 is customized with a user-specific configuration.
647 Consider an image intended as a reusable python application builder. It
650 must
651 add application source code to a particular directory, and might need
652 a build
653 script called after that. You can't just call ADD and RUN now,
654 because
655 you don't yet have access to the application source code, and it is
656 different
657 for each application build.
658 -- Providing application developers with a boilerplate Dockerfile to
661 copy-paste
662 into their application is inefficient, error-prone, and
663 difficult to update because it mixes with application-specific code.
664 The solution is to use ONBUILD to register instructions in advance,
665 to
666 run later, during the next build stage.
667
671 *May 2014, Compiled by Zac Dover (zdover at redhat dot com) based on
672 docker.com Dockerfile documentation. *Feb 2015, updated by Brian Goff
673 (cpuguy83@gmail.com) for readability *Sept 2015, updated by Sally
674 O'Malley (somalley@redhat.com) *Oct 2016, updated by Addam Hardy
675 (addam.hardy@gmail.com)
676Zac Dover Docker User Manuals DOCKERFILE(5)