github.com/caseyhadden/docker@v1.6.2/docs/sources/reference/builder.md (about) 1 page_title: Dockerfile Reference 2 page_description: Dockerfiles use a simple DSL which allows you to automate the steps you would normally manually take to create an image. 3 page_keywords: builder, docker, Dockerfile, automation, image creation 4 5 # Dockerfile Reference 6 7 **Docker can build images automatically** by reading the instructions 8 from a `Dockerfile`. A `Dockerfile` is a text document that contains all 9 the commands you would normally execute manually in order to build a 10 Docker image. By calling `docker build` from your terminal, you can have 11 Docker build your image step by step, executing the instructions 12 successively. 13 14 This page discusses the specifics of all the instructions you can use in your 15 `Dockerfile`. To further help you write a clear, readable, maintainable 16 `Dockerfile`, we've also written a [`Dockerfile` Best Practices 17 guide](/articles/dockerfile_best-practices). Lastly, you can test your 18 Dockerfile knowledge with the [Dockerfile tutorial](/userguide/level1). 19 20 ## Usage 21 22 To [*build*](/reference/commandline/cli/#build) an image from a source repository, 23 create a description file called `Dockerfile` at the root of your repository. 24 This file will describe the steps to assemble the image. 25 26 Then call `docker build` with the path of your source repository as the argument 27 (for example, `.`): 28 29 $ sudo docker build . 30 31 The path to the source repository defines where to find the *context* of 32 the build. The build is run by the Docker daemon, not by the CLI, so the 33 whole context must be transferred to the daemon. The Docker CLI reports 34 "Sending build context to Docker daemon" when the context is sent to the daemon. 35 36 > **Warning** 37 > Avoid using your root directory, `/`, as the root of the source repository. The 38 > `docker build` command will use whatever directory contains the Dockerfile as the build 39 > context (including all of its subdirectories). The build context will be sent to the 40 > Docker daemon before building the image, which means if you use `/` as the source 41 > repository, the entire contents of your hard drive will get sent to the daemon (and 42 > thus to the machine running the daemon). You probably don't want that. 43 44 In most cases, it's best to put each Dockerfile in an empty directory, and then add only 45 the files needed for building that Dockerfile to that directory. To further speed up the 46 build, you can exclude files and directories by adding a `.dockerignore` file to the same 47 directory. 48 49 You can specify a repository and tag at which to save the new image if 50 the build succeeds: 51 52 $ sudo docker build -t shykes/myapp . 53 54 The Docker daemon will run your steps one-by-one, committing the result 55 to a new image if necessary, before finally outputting the ID of your 56 new image. The Docker daemon will automatically clean up the context you 57 sent. 58 59 Note that each instruction is run independently, and causes a new image 60 to be created - so `RUN cd /tmp` will not have any effect on the next 61 instructions. 62 63 Whenever possible, Docker will re-use the intermediate images, 64 accelerating `docker build` significantly (indicated by `Using cache` - 65 see the [`Dockerfile` Best Practices 66 guide](/articles/dockerfile_best-practices/#build-cache) for more information): 67 68 $ sudo docker build -t SvenDowideit/ambassador . 69 Uploading context 10.24 kB 70 Uploading context 71 Step 1 : FROM docker-ut 72 ---> cbba202fe96b 73 Step 2 : MAINTAINER SvenDowideit@home.org.au 74 ---> Using cache 75 ---> 51182097be13 76 Step 3 : CMD env | grep _TCP= | sed 's/.*_PORT_\([0-9]*\)_TCP=tcp:\/\/\(.*\):\(.*\)/socat TCP4-LISTEN:\1,fork,reuseaddr TCP4:\2:\3 \&/' | sh && top 77 ---> Using cache 78 ---> 1a5ffc17324d 79 Successfully built 1a5ffc17324d 80 81 When you're done with your build, you're ready to look into [*Pushing a 82 repository to its registry*]( /userguide/dockerrepos/#contributing-to-docker-hub). 83 84 ## Format 85 86 Here is the format of the `Dockerfile`: 87 88 # Comment 89 INSTRUCTION arguments 90 91 The Instruction is not case-sensitive, however convention is for them to 92 be UPPERCASE in order to distinguish them from arguments more easily. 93 94 Docker runs the instructions in a `Dockerfile` in order. **The 95 first instruction must be \`FROM\`** in order to specify the [*Base 96 Image*](/terms/image/#base-image) from which you are building. 97 98 Docker will treat lines that *begin* with `#` as a 99 comment. A `#` marker anywhere else in the line will 100 be treated as an argument. This allows statements like: 101 102 # Comment 103 RUN echo 'we are running some # of cool things' 104 105 Here is the set of instructions you can use in a `Dockerfile` for building 106 images. 107 108 ### Environment Replacement 109 110 > **Note**: prior to 1.3, `Dockerfile` environment variables were handled 111 > similarly, in that they would be replaced as described below. However, there 112 > was no formal definition on as to which instructions handled environment 113 > replacement at the time. After 1.3 this behavior will be preserved and 114 > canonical. 115 116 Environment variables (declared with [the `ENV` statement](#env)) can also be used in 117 certain instructions as variables to be interpreted by the `Dockerfile`. Escapes 118 are also handled for including variable-like syntax into a statement literally. 119 120 Environment variables are notated in the `Dockerfile` either with 121 `$variable_name` or `${variable_name}`. They are treated equivalently and the 122 brace syntax is typically used to address issues with variable names with no 123 whitespace, like `${foo}_bar`. 124 125 Escaping is possible by adding a `\` before the variable: `\$foo` or `\${foo}`, 126 for example, will translate to `$foo` and `${foo}` literals respectively. 127 128 Example (parsed representation is displayed after the `#`): 129 130 FROM busybox 131 ENV foo /bar 132 WORKDIR ${foo} # WORKDIR /bar 133 ADD . $foo # ADD . /bar 134 COPY \$foo /quux # COPY $foo /quux 135 136 The instructions that handle environment variables in the `Dockerfile` are: 137 138 * `ENV` 139 * `ADD` 140 * `COPY` 141 * `WORKDIR` 142 * `EXPOSE` 143 * `VOLUME` 144 * `USER` 145 146 `ONBUILD` instructions are **NOT** supported for environment replacement, even 147 the instructions above. 148 149 Environment variable subtitution will use the same value for each variable 150 throughout the entire command. In other words, in this example: 151 152 ENV abc=hello 153 ENV abc=bye def=$abc 154 ENV ghi=$abc 155 156 will result in `def` having a value of `hello`, not `bye`. However, 157 `ghi` will have a value of `bye` because it is not part of the same command 158 that set `abc` to `bye`. 159 160 ## The `.dockerignore` file 161 162 If a file named `.dockerignore` exists in the source repository, then it 163 is interpreted as a newline-separated list of exclusion patterns. 164 Exclusion patterns match files or directories relative to the source repository 165 that will be excluded from the context. Globbing is done using Go's 166 [filepath.Match](http://golang.org/pkg/path/filepath#Match) rules. 167 168 > **Note**: 169 > The `.dockerignore` file can even be used to ignore the `Dockerfile` and 170 > `.dockerignore` files. This might be useful if you are copying files from 171 > the root of the build context into your new containter but do not want to 172 > include the `Dockerfile` or `.dockerignore` files (e.g. `ADD . /someDir/`). 173 174 The following example shows the use of the `.dockerignore` file to exclude the 175 `.git` directory from the context. Its effect can be seen in the changed size of 176 the uploaded context. 177 178 $ sudo docker build . 179 Uploading context 18.829 MB 180 Uploading context 181 Step 0 : FROM busybox 182 ---> 769b9341d937 183 Step 1 : CMD echo Hello World 184 ---> Using cache 185 ---> 99cc1ad10469 186 Successfully built 99cc1ad10469 187 $ echo ".git" > .dockerignore 188 $ sudo docker build . 189 Uploading context 6.76 MB 190 Uploading context 191 Step 0 : FROM busybox 192 ---> 769b9341d937 193 Step 1 : CMD echo Hello World 194 ---> Using cache 195 ---> 99cc1ad10469 196 Successfully built 99cc1ad10469 197 198 ## FROM 199 200 FROM <image> 201 202 Or 203 204 FROM <image>:<tag> 205 206 Or 207 208 FROM <image>@<digest> 209 210 The `FROM` instruction sets the [*Base Image*](/terms/image/#base-image) 211 for subsequent instructions. As such, a valid `Dockerfile` must have `FROM` as 212 its first instruction. The image can be any valid image – it is especially easy 213 to start by **pulling an image** from the [*Public Repositories*]( 214 /userguide/dockerrepos). 215 216 `FROM` must be the first non-comment instruction in the `Dockerfile`. 217 218 `FROM` can appear multiple times within a single `Dockerfile` in order to create 219 multiple images. Simply make a note of the last image ID output by the commit 220 before each new `FROM` command. 221 222 The `tag` or `digest` values are optional. If you omit either of them, the builder 223 assumes a `latest` by default. The builder returns an error if it cannot match 224 the `tag` value. 225 226 ## MAINTAINER 227 228 MAINTAINER <name> 229 230 The `MAINTAINER` instruction allows you to set the *Author* field of the 231 generated images. 232 233 ## RUN 234 235 RUN has 2 forms: 236 237 - `RUN <command>` (the command is run in a shell - `/bin/sh -c` - *shell* form) 238 - `RUN ["executable", "param1", "param2"]` (*exec* form) 239 240 The `RUN` instruction will execute any commands in a new layer on top of the 241 current image and commit the results. The resulting committed image will be 242 used for the next step in the `Dockerfile`. 243 244 Layering `RUN` instructions and generating commits conforms to the core 245 concepts of Docker where commits are cheap and containers can be created from 246 any point in an image's history, much like source control. 247 248 The *exec* form makes it possible to avoid shell string munging, and to `RUN` 249 commands using a base image that does not contain `/bin/sh`. 250 251 > **Note**: 252 > To use a different shell, other than '/bin/sh', use the *exec* form 253 > passing in the desired shell. For example, 254 > `RUN ["/bin/bash", "-c", "echo hello"]` 255 256 > **Note**: 257 > The *exec* form is parsed as a JSON array, which means that 258 > you must use double-quotes (") around words not single-quotes ('). 259 260 > **Note**: 261 > Unlike the *shell* form, the *exec* form does not invoke a command shell. 262 > This means that normal shell processing does not happen. For example, 263 > `RUN [ "echo", "$HOME" ]` will not do variable substitution on `$HOME`. 264 > If you want shell processing then either use the *shell* form or execute 265 > a shell directly, for example: `RUN [ "sh", "-c", "echo", "$HOME" ]`. 266 267 The cache for `RUN` instructions isn't invalidated automatically during 268 the next build. The cache for an instruction like 269 `RUN apt-get dist-upgrade -y` will be reused during the next build. The 270 cache for `RUN` instructions can be invalidated by using the `--no-cache` 271 flag, for example `docker build --no-cache`. 272 273 See the [`Dockerfile` Best Practices 274 guide](/articles/dockerfile_best-practices/#build-cache) for more information. 275 276 The cache for `RUN` instructions can be invalidated by `ADD` instructions. See 277 [below](#add) for details. 278 279 ### Known Issues (RUN) 280 281 - [Issue 783](https://github.com/docker/docker/issues/783) is about file 282 permissions problems that can occur when using the AUFS file system. You 283 might notice it during an attempt to `rm` a file, for example. 284 285 For systems that have recent aufs version (i.e., `dirperm1` mount option can 286 be set), docker will attempt to fix the issue automatically by mounting 287 the layers with `dirperm1` option. More details on `dirperm1` option can be 288 found at [`aufs` man page](http://aufs.sourceforge.net/aufs3/man.html) 289 290 If your system doesnt have support for `dirperm1`, the issue describes a workaround. 291 292 ## CMD 293 294 The `CMD` instruction has three forms: 295 296 - `CMD ["executable","param1","param2"]` (*exec* form, this is the preferred form) 297 - `CMD ["param1","param2"]` (as *default parameters to ENTRYPOINT*) 298 - `CMD command param1 param2` (*shell* form) 299 300 There can only be one `CMD` instruction in a `Dockerfile`. If you list more than one `CMD` 301 then only the last `CMD` will take effect. 302 303 **The main purpose of a `CMD` is to provide defaults for an executing 304 container.** These defaults can include an executable, or they can omit 305 the executable, in which case you must specify an `ENTRYPOINT` 306 instruction as well. 307 308 > **Note**: 309 > If `CMD` is used to provide default arguments for the `ENTRYPOINT` 310 > instruction, both the `CMD` and `ENTRYPOINT` instructions should be specified 311 > with the JSON array format. 312 313 > **Note**: 314 > The *exec* form is parsed as a JSON array, which means that 315 > you must use double-quotes (") around words not single-quotes ('). 316 317 > **Note**: 318 > Unlike the *shell* form, the *exec* form does not invoke a command shell. 319 > This means that normal shell processing does not happen. For example, 320 > `CMD [ "echo", "$HOME" ]` will not do variable substitution on `$HOME`. 321 > If you want shell processing then either use the *shell* form or execute 322 > a shell directly, for example: `CMD [ "sh", "-c", "echo", "$HOME" ]`. 323 324 When used in the shell or exec formats, the `CMD` instruction sets the command 325 to be executed when running the image. 326 327 If you use the *shell* form of the `CMD`, then the `<command>` will execute in 328 `/bin/sh -c`: 329 330 FROM ubuntu 331 CMD echo "This is a test." | wc - 332 333 If you want to **run your** `<command>` **without a shell** then you must 334 express the command as a JSON array and give the full path to the executable. 335 **This array form is the preferred format of `CMD`.** Any additional parameters 336 must be individually expressed as strings in the array: 337 338 FROM ubuntu 339 CMD ["/usr/bin/wc","--help"] 340 341 If you would like your container to run the same executable every time, then 342 you should consider using `ENTRYPOINT` in combination with `CMD`. See 343 [*ENTRYPOINT*](#entrypoint). 344 345 If the user specifies arguments to `docker run` then they will override the 346 default specified in `CMD`. 347 348 > **Note**: 349 > don't confuse `RUN` with `CMD`. `RUN` actually runs a command and commits 350 > the result; `CMD` does not execute anything at build time, but specifies 351 > the intended command for the image. 352 353 ## LABEL 354 355 LABEL <key>=<value> <key>=<value> <key>=<value> ... 356 357 The `LABEL` instruction adds metadata to an image. A `LABEL` is a 358 key-value pair. To include spaces within a `LABEL` value, use quotes and 359 blackslashes as you would in command-line parsing. 360 361 LABEL "com.example.vendor"="ACME Incorporated" 362 363 An image can have more than one label. To specify multiple labels, separate each 364 key-value pair by an EOL. 365 366 LABEL com.example.label-without-value 367 LABEL com.example.label-with-value="foo" 368 LABEL version="1.0" 369 LABEL description="This text illustrates \ 370 that label-values can span multiple lines." 371 372 Docker recommends combining labels in a single `LABEL` instruction where 373 possible. Each `LABEL` instruction produces a new layer which can result in an 374 inefficient image if you use many labels. This example results in four image 375 layers. 376 377 Labels are additive including `LABEL`s in `FROM` images. As the system 378 encounters and then applies a new label, new `key`s override any previous labels 379 with identical keys. 380 381 To view an image's labels, use the `docker inspect` command. 382 383 ## EXPOSE 384 385 EXPOSE <port> [<port>...] 386 387 The `EXPOSE` instructions informs Docker that the container will listen on the 388 specified network ports at runtime. Docker uses this information to interconnect 389 containers using links (see the [Docker User 390 Guide](/userguide/dockerlinks)) and to determine which ports to expose to the 391 host when [using the -P flag](/reference/run/#expose-incoming-ports). 392 393 > **Note**: 394 > `EXPOSE` doesn't define which ports can be exposed to the host or make ports 395 > accessible from the host by default. To expose ports to the host, at runtime, 396 > [use the `-p` flag](/userguide/dockerlinks) or 397 > [the -P flag](/reference/run/#expose-incoming-ports). 398 399 ## ENV 400 401 ENV <key> <value> 402 ENV <key>=<value> ... 403 404 The `ENV` instruction sets the environment variable `<key>` to the value 405 `<value>`. This value will be in the environment of all "descendent" `Dockerfile` 406 commands and can be [replaced inline](#environment-replacement) in many as well. 407 408 The `ENV` instruction has two forms. The first form, `ENV <key> <value>`, 409 will set a single variable to a value. The entire string after the first 410 space will be treated as the `<value>` - including characters such as 411 spaces and quotes. 412 413 The second form, `ENV <key>=<value> ...`, allows for multiple variables to 414 be set at one time. Notice that the second form uses the equals sign (=) 415 in the syntax, while the first form does not. Like command line parsing, 416 quotes and backslashes can be used to include spaces within values. 417 418 For example: 419 420 ENV myName="John Doe" myDog=Rex\ The\ Dog \ 421 myCat=fluffy 422 423 and 424 425 ENV myName John Doe 426 ENV myDog Rex The Dog 427 ENV myCat fluffy 428 429 will yield the same net results in the final container, but the first form 430 does it all in one layer. 431 432 The environment variables set using `ENV` will persist when a container is run 433 from the resulting image. You can view the values using `docker inspect`, and 434 change them using `docker run --env <key>=<value>`. 435 436 > **Note**: 437 > Environment persistence can cause unexpected effects. For example, 438 > setting `ENV DEBIAN_FRONTEND noninteractive` may confuse apt-get 439 > users on a Debian-based image. To set a value for a single command, use 440 > `RUN <key>=<value> <command>`. 441 442 ## ADD 443 444 ADD has two forms: 445 446 - `ADD <src>... <dest>` 447 - `ADD ["<src>"... "<dest>"]` (this form is required for paths containing 448 whitespace) 449 450 The `ADD` instruction copies new files, directories or remote file URLs from `<src>` 451 and adds them to the filesystem of the container at the path `<dest>`. 452 453 Multiple `<src>` resource may be specified but if they are files or 454 directories then they must be relative to the source directory that is 455 being built (the context of the build). 456 457 Each `<src>` may contain wildcards and matching will be done using Go's 458 [filepath.Match](http://golang.org/pkg/path/filepath#Match) rules. 459 For most command line uses this should act as expected, for example: 460 461 ADD hom* /mydir/ # adds all files starting with "hom" 462 ADD hom?.txt /mydir/ # ? is replaced with any single character 463 464 The `<dest>` is an absolute path, or a path relative to `WORKDIR`, into which 465 the source will be copied inside the destination container. 466 467 ADD test aDir/ # adds "test" to `WORKDIR`/aDir/ 468 469 All new files and directories are created with a UID and GID of 0. 470 471 In the case where `<src>` is a remote file URL, the destination will 472 have permissions of 600. If the remote file being retrieved has an HTTP 473 `Last-Modified` header, the timestamp from that header will be used 474 to set the `mtime` on the destination file. Then, like any other file 475 processed during an `ADD`, `mtime` will be included in the determination 476 of whether or not the file has changed and the cache should be updated. 477 478 > **Note**: 479 > If you build by passing a `Dockerfile` through STDIN (`docker 480 > build - < somefile`), there is no build context, so the `Dockerfile` 481 > can only contain a URL based `ADD` instruction. You can also pass a 482 > compressed archive through STDIN: (`docker build - < archive.tar.gz`), 483 > the `Dockerfile` at the root of the archive and the rest of the 484 > archive will get used at the context of the build. 485 486 > **Note**: 487 > If your URL files are protected using authentication, you 488 > will need to use `RUN wget`, `RUN curl` or use another tool from 489 > within the container as the `ADD` instruction does not support 490 > authentication. 491 492 > **Note**: 493 > The first encountered `ADD` instruction will invalidate the cache for all 494 > following instructions from the Dockerfile if the contents of `<src>` have 495 > changed. This includes invalidating the cache for `RUN` instructions. 496 > See the [`Dockerfile` Best Practices 497 guide](/articles/dockerfile_best-practices/#build-cache) for more information. 498 499 500 The copy obeys the following rules: 501 502 - The `<src>` path must be inside the *context* of the build; 503 you cannot `ADD ../something /something`, because the first step of a 504 `docker build` is to send the context directory (and subdirectories) to the 505 docker daemon. 506 507 - If `<src>` is a URL and `<dest>` does not end with a trailing slash, then a 508 file is downloaded from the URL and copied to `<dest>`. 509 510 - If `<src>` is a URL and `<dest>` does end with a trailing slash, then the 511 filename is inferred from the URL and the file is downloaded to 512 `<dest>/<filename>`. For instance, `ADD http://example.com/foobar /` would 513 create the file `/foobar`. The URL must have a nontrivial path so that an 514 appropriate filename can be discovered in this case (`http://example.com` 515 will not work). 516 517 - If `<src>` is a directory, the entire contents of the directory are copied, 518 including filesystem metadata. 519 > **Note**: 520 > The directory itself is not copied, just its contents. 521 522 - If `<src>` is a *local* tar archive in a recognized compression format 523 (identity, gzip, bzip2 or xz) then it is unpacked as a directory. Resources 524 from *remote* URLs are **not** decompressed. When a directory is copied or 525 unpacked, it has the same behavior as `tar -x`: the result is the union of: 526 527 1. Whatever existed at the destination path and 528 2. The contents of the source tree, with conflicts resolved in favor 529 of "2." on a file-by-file basis. 530 531 - If `<src>` is any other kind of file, it is copied individually along with 532 its metadata. In this case, if `<dest>` ends with a trailing slash `/`, it 533 will be considered a directory and the contents of `<src>` will be written 534 at `<dest>/base(<src>)`. 535 536 - If multiple `<src>` resources are specified, either directly or due to the 537 use of a wildcard, then `<dest>` must be a directory, and it must end with 538 a slash `/`. 539 540 - If `<dest>` does not end with a trailing slash, it will be considered a 541 regular file and the contents of `<src>` will be written at `<dest>`. 542 543 - If `<dest>` doesn't exist, it is created along with all missing directories 544 in its path. 545 546 ## COPY 547 548 COPY has two forms: 549 550 - `COPY <src>... <dest>` 551 - `COPY ["<src>"... "<dest>"]` (this form is required for paths containing 552 whitespace) 553 554 The `COPY` instruction copies new files or directories from `<src>` 555 and adds them to the filesystem of the container at the path `<dest>`. 556 557 Multiple `<src>` resource may be specified but they must be relative 558 to the source directory that is being built (the context of the build). 559 560 Each `<src>` may contain wildcards and matching will be done using Go's 561 [filepath.Match](http://golang.org/pkg/path/filepath#Match) rules. 562 For most command line uses this should act as expected, for example: 563 564 COPY hom* /mydir/ # adds all files starting with "hom" 565 COPY hom?.txt /mydir/ # ? is replaced with any single character 566 567 The `<dest>` is an absolute path, or a path relative to `WORKDIR`, into which 568 the source will be copied inside the destination container. 569 570 COPY test aDir/ # adds "test" to `WORKDIR`/aDir/ 571 572 All new files and directories are created with a UID and GID of 0. 573 574 > **Note**: 575 > If you build using STDIN (`docker build - < somefile`), there is no 576 > build context, so `COPY` can't be used. 577 578 The copy obeys the following rules: 579 580 - The `<src>` path must be inside the *context* of the build; 581 you cannot `COPY ../something /something`, because the first step of a 582 `docker build` is to send the context directory (and subdirectories) to the 583 docker daemon. 584 585 - If `<src>` is a directory, the entire contents of the directory are copied, 586 including filesystem metadata. 587 > **Note**: 588 > The directory itself is not copied, just its contents. 589 590 - If `<src>` is any other kind of file, it is copied individually along with 591 its metadata. In this case, if `<dest>` ends with a trailing slash `/`, it 592 will be considered a directory and the contents of `<src>` will be written 593 at `<dest>/base(<src>)`. 594 595 - If multiple `<src>` resources are specified, either directly or due to the 596 use of a wildcard, then `<dest>` must be a directory, and it must end with 597 a slash `/`. 598 599 - If `<dest>` does not end with a trailing slash, it will be considered a 600 regular file and the contents of `<src>` will be written at `<dest>`. 601 602 - If `<dest>` doesn't exist, it is created along with all missing directories 603 in its path. 604 605 ## ENTRYPOINT 606 607 ENTRYPOINT has two forms: 608 609 - `ENTRYPOINT ["executable", "param1", "param2"]` 610 (the preferred *exec* form) 611 - `ENTRYPOINT command param1 param2` 612 (*shell* form) 613 614 An `ENTRYPOINT` allows you to configure a container that will run as an executable. 615 616 For example, the following will start nginx with its default content, listening 617 on port 80: 618 619 docker run -i -t --rm -p 80:80 nginx 620 621 Command line arguments to `docker run <image>` will be appended after all 622 elements in an *exec* form `ENTRYPOINT`, and will override all elements specified 623 using `CMD`. 624 This allows arguments to be passed to the entry point, i.e., `docker run <image> -d` 625 will pass the `-d` argument to the entry point. 626 You can override the `ENTRYPOINT` instruction using the `docker run --entrypoint` 627 flag. 628 629 The *shell* form prevents any `CMD` or `run` command line arguments from being 630 used, but has the disadvantage that your `ENTRYPOINT` will be started as a 631 subcommand of `/bin/sh -c`, which does not pass signals. 632 This means that the executable will not be the container's `PID 1` - and 633 will _not_ receive Unix signals - so your executable will not receive a 634 `SIGTERM` from `docker stop <container>`. 635 636 Only the last `ENTRYPOINT` instruction in the `Dockerfile` will have an effect. 637 638 ### Exec form ENTRYPOINT example 639 640 You can use the *exec* form of `ENTRYPOINT` to set fairly stable default commands 641 and arguments and then use either form of `CMD` to set additional defaults that 642 are more likely to be changed. 643 644 FROM ubuntu 645 ENTRYPOINT ["top", "-b"] 646 CMD ["-c"] 647 648 When you run the container, you can see that `top` is the only process: 649 650 $ docker run -it --rm --name test top -H 651 top - 08:25:00 up 7:27, 0 users, load average: 0.00, 0.01, 0.05 652 Threads: 1 total, 1 running, 0 sleeping, 0 stopped, 0 zombie 653 %Cpu(s): 0.1 us, 0.1 sy, 0.0 ni, 99.7 id, 0.0 wa, 0.0 hi, 0.0 si, 0.0 st 654 KiB Mem: 2056668 total, 1616832 used, 439836 free, 99352 buffers 655 KiB Swap: 1441840 total, 0 used, 1441840 free. 1324440 cached Mem 656 657 PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND 658 1 root 20 0 19744 2336 2080 R 0.0 0.1 0:00.04 top 659 660 To examine the result further, you can use `docker exec`: 661 662 $ docker exec -it test ps aux 663 USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND 664 root 1 2.6 0.1 19752 2352 ? Ss+ 08:24 0:00 top -b -H 665 root 7 0.0 0.1 15572 2164 ? R+ 08:25 0:00 ps aux 666 667 And you can gracefully request `top` to shut down using `docker stop test`. 668 669 The following `Dockerfile` shows using the `ENTRYPOINT` to run Apache in the 670 foreground (i.e., as `PID 1`): 671 672 ``` 673 FROM debian:stable 674 RUN apt-get update && apt-get install -y --force-yes apache2 675 EXPOSE 80 443 676 VOLUME ["/var/www", "/var/log/apache2", "/etc/apache2"] 677 ENTRYPOINT ["/usr/sbin/apache2ctl", "-D", "FOREGROUND"] 678 ``` 679 680 If you need to write a starter script for a single executable, you can ensure that 681 the final executable receives the Unix signals by using `exec` and `gosu` 682 commands: 683 684 ```bash 685 #!/bin/bash 686 set -e 687 688 if [ "$1" = 'postgres' ]; then 689 chown -R postgres "$PGDATA" 690 691 if [ -z "$(ls -A "$PGDATA")" ]; then 692 gosu postgres initdb 693 fi 694 695 exec gosu postgres "$@" 696 fi 697 698 exec "$@" 699 ``` 700 701 Lastly, if you need to do some extra cleanup (or communicate with other containers) 702 on shutdown, or are co-ordinating more than one executable, you may need to ensure 703 that the `ENTRYPOINT` script receives the Unix signals, passes them on, and then 704 does some more work: 705 706 ``` 707 #!/bin/sh 708 # Note: I've written this using sh so it works in the busybox container too 709 710 # USE the trap if you need to also do manual cleanup after the service is stopped, 711 # or need to start multiple services in the one container 712 trap "echo TRAPed signal" HUP INT QUIT KILL TERM 713 714 # start service in background here 715 /usr/sbin/apachectl start 716 717 echo "[hit enter key to exit] or run 'docker stop <container>'" 718 read 719 720 # stop service and clean up here 721 echo "stopping apache" 722 /usr/sbin/apachectl stop 723 724 echo "exited $0" 725 ``` 726 727 If you run this image with `docker run -it --rm -p 80:80 --name test apache`, 728 you can then examine the container's processes with `docker exec`, or `docker top`, 729 and then ask the script to stop Apache: 730 731 ```bash 732 $ docker exec -it test ps aux 733 USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND 734 root 1 0.1 0.0 4448 692 ? Ss+ 00:42 0:00 /bin/sh /run.sh 123 cmd cmd2 735 root 19 0.0 0.2 71304 4440 ? Ss 00:42 0:00 /usr/sbin/apache2 -k start 736 www-data 20 0.2 0.2 360468 6004 ? Sl 00:42 0:00 /usr/sbin/apache2 -k start 737 www-data 21 0.2 0.2 360468 6000 ? Sl 00:42 0:00 /usr/sbin/apache2 -k start 738 root 81 0.0 0.1 15572 2140 ? R+ 00:44 0:00 ps aux 739 $ docker top test 740 PID USER COMMAND 741 10035 root {run.sh} /bin/sh /run.sh 123 cmd cmd2 742 10054 root /usr/sbin/apache2 -k start 743 10055 33 /usr/sbin/apache2 -k start 744 10056 33 /usr/sbin/apache2 -k start 745 $ /usr/bin/time docker stop test 746 test 747 real 0m 0.27s 748 user 0m 0.03s 749 sys 0m 0.03s 750 ``` 751 752 > **Note:** you can over ride the `ENTRYPOINT` setting using `--entrypoint`, 753 > but this can only set the binary to *exec* (no `sh -c` will be used). 754 755 > **Note**: 756 > The *exec* form is parsed as a JSON array, which means that 757 > you must use double-quotes (") around words not single-quotes ('). 758 759 > **Note**: 760 > Unlike the *shell* form, the *exec* form does not invoke a command shell. 761 > This means that normal shell processing does not happen. For example, 762 > `ENTRYPOINT [ "echo", "$HOME" ]` will not do variable substitution on `$HOME`. 763 > If you want shell processing then either use the *shell* form or execute 764 > a shell directly, for example: `ENTRYPOINT [ "sh", "-c", "echo", "$HOME" ]`. 765 > Variables that are defined in the `Dockerfile`using `ENV`, will be substituted by 766 > the `Dockerfile` parser. 767 768 ### Shell form ENTRYPOINT example 769 770 You can specify a plain string for the `ENTRYPOINT` and it will execute in `/bin/sh -c`. 771 This form will use shell processing to substitute shell environment variables, 772 and will ignore any `CMD` or `docker run` command line arguments. 773 To ensure that `docker stop` will signal any long running `ENTRYPOINT` executable 774 correctly, you need to remember to start it with `exec`: 775 776 FROM ubuntu 777 ENTRYPOINT exec top -b 778 779 When you run this image, you'll see the single `PID 1` process: 780 781 $ docker run -it --rm --name test top 782 Mem: 1704520K used, 352148K free, 0K shrd, 0K buff, 140368121167873K cached 783 CPU: 5% usr 0% sys 0% nic 94% idle 0% io 0% irq 0% sirq 784 Load average: 0.08 0.03 0.05 2/98 6 785 PID PPID USER STAT VSZ %VSZ %CPU COMMAND 786 1 0 root R 3164 0% 0% top -b 787 788 Which will exit cleanly on `docker stop`: 789 790 $ /usr/bin/time docker stop test 791 test 792 real 0m 0.20s 793 user 0m 0.02s 794 sys 0m 0.04s 795 796 If you forget to add `exec` to the beginning of your `ENTRYPOINT`: 797 798 FROM ubuntu 799 ENTRYPOINT top -b 800 CMD --ignored-param1 801 802 You can then run it (giving it a name for the next step): 803 804 $ docker run -it --name test top --ignored-param2 805 Mem: 1704184K used, 352484K free, 0K shrd, 0K buff, 140621524238337K cached 806 CPU: 9% usr 2% sys 0% nic 88% idle 0% io 0% irq 0% sirq 807 Load average: 0.01 0.02 0.05 2/101 7 808 PID PPID USER STAT VSZ %VSZ %CPU COMMAND 809 1 0 root S 3168 0% 0% /bin/sh -c top -b cmd cmd2 810 7 1 root R 3164 0% 0% top -b 811 812 You can see from the output of `top` that the specified `ENTRYPOINT` is not `PID 1`. 813 814 If you then run `docker stop test`, the container will not exit cleanly - the 815 `stop` command will be forced to send a `SIGKILL` after the timeout: 816 817 $ docker exec -it test ps aux 818 PID USER COMMAND 819 1 root /bin/sh -c top -b cmd cmd2 820 7 root top -b 821 8 root ps aux 822 $ /usr/bin/time docker stop test 823 test 824 real 0m 10.19s 825 user 0m 0.04s 826 sys 0m 0.03s 827 828 ## VOLUME 829 830 VOLUME ["/data"] 831 832 The `VOLUME` instruction creates a mount point with the specified name 833 and marks it as holding externally mounted volumes from native host or other 834 containers. The value can be a JSON array, `VOLUME ["/var/log/"]`, or a plain 835 string with multiple arguments, such as `VOLUME /var/log` or `VOLUME /var/log 836 /var/db`. For more information/examples and mounting instructions via the 837 Docker client, refer to 838 [*Share Directories via Volumes*](/userguide/dockervolumes/#volume) 839 documentation. 840 841 The `docker run` command initializes the newly created volume with any data 842 that exists at the specified location within the base image. For example, 843 consider the following Dockerfile snippet: 844 845 FROM ubuntu 846 RUN mkdir /myvol 847 RUN echo "hello world" > /myvol/greating 848 VOLUME /myvol 849 850 This Dockerfile results in an image that causes `docker run`, to 851 create a new mount point at `/myvol` and copy the `greating` file 852 into the newly created volume. 853 854 > **Note**: 855 > The list is parsed as a JSON array, which means that 856 > you must use double-quotes (") around words not single-quotes ('). 857 858 ## USER 859 860 USER daemon 861 862 The `USER` instruction sets the user name or UID to use when running the image 863 and for any `RUN`, `CMD` and `ENTRYPOINT` instructions that follow it in the 864 `Dockerfile`. 865 866 ## WORKDIR 867 868 WORKDIR /path/to/workdir 869 870 The `WORKDIR` instruction sets the working directory for any `RUN`, `CMD`, 871 `ENTRYPOINT`, `COPY` and `ADD` instructions that follow it in the `Dockerfile`. 872 873 It can be used multiple times in the one `Dockerfile`. If a relative path 874 is provided, it will be relative to the path of the previous `WORKDIR` 875 instruction. For example: 876 877 WORKDIR /a 878 WORKDIR b 879 WORKDIR c 880 RUN pwd 881 882 The output of the final `pwd` command in this `Dockerfile` would be 883 `/a/b/c`. 884 885 The `WORKDIR` instruction can resolve environment variables previously set using 886 `ENV`. You can only use environment variables explicitly set in the `Dockerfile`. 887 For example: 888 889 ENV DIRPATH /path 890 WORKDIR $DIRPATH/$DIRNAME 891 892 The output of the final `pwd` command in this `Dockerfile` would be 893 `/path/$DIRNAME` 894 895 ## ONBUILD 896 897 ONBUILD [INSTRUCTION] 898 899 The `ONBUILD` instruction adds to the image a *trigger* instruction to 900 be executed at a later time, when the image is used as the base for 901 another build. The trigger will be executed in the context of the 902 downstream build, as if it had been inserted immediately after the 903 `FROM` instruction in the downstream `Dockerfile`. 904 905 Any build instruction can be registered as a trigger. 906 907 This is useful if you are building an image which will be used as a base 908 to build other images, for example an application build environment or a 909 daemon which may be customized with user-specific configuration. 910 911 For example, if your image is a reusable Python application builder, it 912 will require application source code to be added in a particular 913 directory, and it might require a build script to be called *after* 914 that. You can't just call `ADD` and `RUN` now, because you don't yet 915 have access to the application source code, and it will be different for 916 each application build. You could simply provide application developers 917 with a boilerplate `Dockerfile` to copy-paste into their application, but 918 that is inefficient, error-prone and difficult to update because it 919 mixes with application-specific code. 920 921 The solution is to use `ONBUILD` to register advance instructions to 922 run later, during the next build stage. 923 924 Here's how it works: 925 926 1. When it encounters an `ONBUILD` instruction, the builder adds a 927 trigger to the metadata of the image being built. The instruction 928 does not otherwise affect the current build. 929 2. At the end of the build, a list of all triggers is stored in the 930 image manifest, under the key `OnBuild`. They can be inspected with 931 the `docker inspect` command. 932 3. Later the image may be used as a base for a new build, using the 933 `FROM` instruction. As part of processing the `FROM` instruction, 934 the downstream builder looks for `ONBUILD` triggers, and executes 935 them in the same order they were registered. If any of the triggers 936 fail, the `FROM` instruction is aborted which in turn causes the 937 build to fail. If all triggers succeed, the `FROM` instruction 938 completes and the build continues as usual. 939 4. Triggers are cleared from the final image after being executed. In 940 other words they are not inherited by "grand-children" builds. 941 942 For example you might add something like this: 943 944 [...] 945 ONBUILD ADD . /app/src 946 ONBUILD RUN /usr/local/bin/python-build --dir /app/src 947 [...] 948 949 > **Warning**: Chaining `ONBUILD` instructions using `ONBUILD ONBUILD` isn't allowed. 950 951 > **Warning**: The `ONBUILD` instruction may not trigger `FROM` or `MAINTAINER` instructions. 952 953 ## Dockerfile Examples 954 955 # Nginx 956 # 957 # VERSION 0.0.1 958 959 FROM ubuntu 960 MAINTAINER Victor Vieux <victor@docker.com> 961 962 LABEL Description="This image is used to start the foobar executable" Vendor="ACME Products" Version="1.0" 963 RUN apt-get update && apt-get install -y inotify-tools nginx apache2 openssh-server 964 965 # Firefox over VNC 966 # 967 # VERSION 0.3 968 969 FROM ubuntu 970 971 # Install vnc, xvfb in order to create a 'fake' display and firefox 972 RUN apt-get update && apt-get install -y x11vnc xvfb firefox 973 RUN mkdir ~/.vnc 974 # Setup a password 975 RUN x11vnc -storepasswd 1234 ~/.vnc/passwd 976 # Autostart firefox (might not be the best way, but it does the trick) 977 RUN bash -c 'echo "firefox" >> /.bashrc' 978 979 EXPOSE 5900 980 CMD ["x11vnc", "-forever", "-usepw", "-create"] 981 982 # Multiple images example 983 # 984 # VERSION 0.1 985 986 FROM ubuntu 987 RUN echo foo > bar 988 # Will output something like ===> 907ad6c2736f 989 990 FROM ubuntu 991 RUN echo moo > oink 992 # Will output something like ===> 695d7793cbe4 993 994 # You᾿ll now have two images, 907ad6c2736f with /bar, and 695d7793cbe4 with 995 # /oink. 996