1DOCKERFILE(5)(Docker) DOCKERFILE(5)(Docker)
2
3
4
5Zac Dover May 2014
6
7
9 Dockerfile - automate the steps of creating a Docker image
10
11
12
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
20
21 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
25
26
28 INSTRUCTION arguments
29
30
31 For example:
32
33
34 FROM image
35
36
37
39 A Dockerfile is a file that automates the steps of creating a Docker
40 image. A Dockerfile is similar to a Makefile.
41
42
43
45 docker build .
46
47
48 -- 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
57
58 docker build -t repository/tag .
59
60
61
62 -- 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
71
72 Docker re-uses intermediate images whenever possible. This signifi‐
73 cantly
74 accelerates the docker build process.
75
76
77
79 FROM image
80
81
82 FROM image:tag
83
84
85 FROM image@digest
86
87
88 -- 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
95
96 -- FROM must be the first non-comment instruction in Dockerfile.
97
98
99 -- 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
105
106 -- 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
109
110 -- 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
113
114 MAINTAINER
115 -- MAINTAINER sets the Author field for the generated images.
116 Useful for providing users with an email or url for support.
117
118
119 RUN
120 -- RUN has two forms:
121
122
123 # the command is run in a shell - /bin/sh -c
124 RUN <command>
125
126 # Executable form
127 RUN ["executable", "param1", "param2"]
128
129
130
131 -- 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
137
138 -- 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
149
150 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
154
155 CMD
156 -- CMD has three forms:
157
158
159 # Executable form
160 CMD ["executable", "param1", "param2"]`
161
162 # Provide default arguments to ENTRYPOINT
163 CMD ["param1", "param2"]`
164
165 # the command is run in a shell - /bin/sh -c
166 CMD command param1 param2
167
168
169
170 -- 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
184
185 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
189
190 FROM ubuntu
191 CMD echo "This is a test." | wc -
192
193
194
195 -- 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
203
204 FROM ubuntu
205 CMD ["/usr/bin/wc","--help"]
206
207
208
209 -- 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
220
221 LABEL
222 -- LABEL <key>=<value> [<key>=<value> ...]or
223
224
225 LABEL <key>[ <value>]
226 LABEL <key>[ <value>]
227 ...
228
229
230
231 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
237
238 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
244
245
246 An image can have more than one label. To specify multiple labels, sep‐
247 arate
248 each key-value pair by a space.
249
250
251 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
256
257 To display an image's labels, use the docker inspect command.
258
259
260 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
269
270 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
283
284 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
290
291 ADD
292 -- ADD has two forms:
293
294
295 ADD <src> <dest>
296
297 # Required for paths with whitespace
298 ADD ["<src>",... "<dest>"]
299
300
301
302 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
324
325 COPY
326 -- COPY has two forms:
327
328
329 COPY <src> <dest>
330
331 # Required for paths with whitespace
332 COPY ["<src>",... "<dest>"]
333
334
335
336 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
353
354 ENTRYPOINT
355 -- ENTRYPOINT has two forms:
356
357
358 # executable form
359 ENTRYPOINT ["executable", "param1", "param2"]`
360
361 # run command in a shell - /bin/sh -c
362 ENTRYPOINT command param1 param2
363
364
365
366 -- 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
389
390 FROM ubuntu
391 ENTRYPOINT wc -l -
392
393
394
395 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
401
402 FROM ubuntu
403 CMD ["-l", "-"]
404 ENTRYPOINT ["/usr/bin/wc"]
405
406
407
408 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
416
417 USER
418 -- USER daemon
419 Sets the username or UID used for running subsequent commands.
420
421
422 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
427
428 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
434
435 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
444
445 WORKDIR /a
446 WORKDIR b
447 WORKDIR c
448 RUN pwd
449
450
451
452 In the above example, the output of the pwd command is a/b/c.
453
454
455 ARG
456 -- ARG [=]
457
458
459 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
466
467 [Warning] One or more build-args [foo] were not consumed
468
469
470
471 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
476
477 FROM busybox
478 ARG user1
479 ARG buildno
480 ...
481
482
483
484 A Dockerfile author may optionally specify a default value for an ARG
485 instruction:
486
487
488 FROM busybox
489 ARG user1=someuser
490 ARG buildno=1
491 ...
492
493
494
495 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
499
500 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
506
507 1 FROM busybox
508 2 USER ${user:-some_user}
509 3 ARG user
510 4 USER $user
511 ...
512
513
514
515 A user builds this file by calling:
516
517
518 $ docker build --build-arg user=what_user Dockerfile
519
520
521
522 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
530
531 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
537
538
539 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
546
547 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
552
553
554 Then, assume this image is built with this command:
555
556
557 $ docker build --build-arg CONT_IMG_VER=v2.0.1 Dockerfile
558
559
560
561 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
569
570 Using the example above but a different ENV specification you can cre‐
571 ate more
572 useful interactions between ARG and ENV instructions:
573
574
575 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
580
581
582 Unlike an ARG instruction, ENV values are always persisted in the built
583 image. Consider a docker build without the --build-arg flag:
584
585
586 $ docker build Dockerfile
587
588
589
590 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
595
596 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
604
605 Docker has a set of predefined ARG variables that you can use without a
606 corresponding ARG instruction in the Dockerfile.
607
608
609 · HTTP_PROXY
610
611 · http_proxy
612
613 · HTTPS_PROXY
614
615 · https_proxy
616
617 · FTP_PROXY
618
619 · ftp_proxy
620
621 · NO_PROXY
622
623 · no_proxy
624
625
626
627 To use these, simply pass them on the command line using the
628 --build-arg
629 <varname>=<value> flag.
630
631
632 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
643
644 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
652
653 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
663
664 -- 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
672
673
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)
680
681
682
683Manuals User DOCKERFILE(5)(Docker)