From 60f76bbfe1baaa0c1cc94b997022df6b8c44f07f Mon Sep 17 00:00:00 2001 From: Charles Chan Date: Sun, 6 Sep 2015 15:48:05 -0700 Subject: [PATCH] Touch up "Dockerfile reference" - add example for `docker build -f ...` - modifiy `FROM` explaination into bullet points - add/clarify examples for `LABEL` and `ADD` instructions - fix review comments (PR #16109) Signed-off-by: Charles Chan --- docs/reference/builder.md | 83 ++++++++++++++++++++++----------------- 1 file changed, 46 insertions(+), 37 deletions(-) diff --git a/docs/reference/builder.md b/docs/reference/builder.md index 3a73b87d29..2565b7eaeb 100644 --- a/docs/reference/builder.md +++ b/docs/reference/builder.md @@ -45,8 +45,8 @@ Dockerfile. >the build to transfer the entire contents of your hard drive to the Docker >daemon. -To use a file in the build context, the `Dockerfile` refers to the file with -an instruction, for example, a `COPY` instruction. To increase the build's +To use a file in the build context, the `Dockerfile` refers to the file specified +in an instruction, for example, a `COPY` instruction. To increase the build's performance, exclude files and directories by adding a `.dockerignore` file to the context directory. For information about how to [create a `.dockerignore` file](#dockerignore-file) see the documentation on this page. @@ -55,12 +55,15 @@ Traditionally, the `Dockerfile` is called `Dockerfile` and located in the root of the context. You use the `-f` flag with `docker build` to point to a Dockerfile anywhere in your file system. + $ docker build -f /path/to/a/Dockerfile . + You can specify a repository and tag at which to save the new image if the build succeeds: $ docker build -t shykes/myapp . -The Docker daemon will run your steps one-by-one, committing the result +The Docker daemon runs the instructions in the `Dockerfile` one-by-one, +committing the result of each instruction to a new image if necessary, before finally outputting the ID of your new image. The Docker daemon will automatically clean up the context you sent. @@ -69,10 +72,11 @@ Note that each instruction is run independently, and causes a new image to be created - so `RUN cd /tmp` will not have any effect on the next instructions. -Whenever possible, Docker will re-use the intermediate images, -accelerating `docker build` significantly (indicated by `Using cache` - -see the [`Dockerfile` Best Practices -guide](/articles/dockerfile_best-practices/#build-cache) for more information): +Whenever possible, Docker will re-use the intermediate images (cache), +to accelerate the `docker build` process significantly. This is indicated by +the `Using cache` message in the console output. +(For more information, see the [Build cache section](/articles/dockerfile_best-practices/#build-cache)) in the +`Dockerfile` best practices guide: $ docker build -t SvenDowideit/ambassador . Uploading context 10.24 kB @@ -97,7 +101,7 @@ Here is the format of the `Dockerfile`: # Comment INSTRUCTION arguments -The Instruction is not case-sensitive, however convention is for them to +The instruction is not case-sensitive, however convention is for them to be UPPERCASE in order to distinguish them from arguments more easily. Docker runs the instructions in a `Dockerfile` in order. **The @@ -214,7 +218,7 @@ This file causes the following build behavior: | `*/*/temp*` | Exclude files starting with name `temp` from any subdirectory that is two levels below the root directory. For example, the file `/somedir/subdir/temporary.txt` is ignored. | | `temp?` | Exclude the files that match the pattern in the root directory. For example, the files `tempa`, `tempb` in the root directory are ignored. | | `*.md ` | Exclude all markdown files in the root directory. | -| `!LICENSE.md` | Exception to the Markdown files exclusion is this file, `LICENSE.md`, Include this file in the build. | +| `!LICENSE.md` | Exception to the Markdown files exclusion. `LICENSE.md`is included in the build. | The placement of `!` exception rules influences the matching algorithm; the last line of the `.dockerignore` that matches a particular file determines @@ -259,13 +263,13 @@ its first instruction. The image can be any valid image – it is especially eas to start by **pulling an image** from the [*Public Repositories*]( /userguide/dockerrepos). -`FROM` must be the first non-comment instruction in the `Dockerfile`. +- `FROM` must be the first non-comment instruction in the `Dockerfile`. -`FROM` can appear multiple times within a single `Dockerfile` in order to create +- `FROM` can appear multiple times within a single `Dockerfile` in order to create multiple images. Simply make a note of the last image ID output by the commit before each new `FROM` command. -The `tag` or `digest` values are optional. If you omit either of them, the builder +- The `tag` or `digest` values are optional. If you omit either of them, the builder assumes a `latest` by default. The builder returns an error if it cannot match the `tag` value. @@ -280,7 +284,7 @@ generated images. RUN has 2 forms: -- `RUN ` (the command is run in a shell - `/bin/sh -c` - *shell* form) +- `RUN ` (*shell* form, the command is run in a shell - `/bin/sh -c`) - `RUN ["executable", "param1", "param2"]` (*exec* form) The `RUN` instruction will execute any commands in a new layer on top of the @@ -402,28 +406,31 @@ default specified in `CMD`. The `LABEL` instruction adds metadata to an image. A `LABEL` is a key-value pair. To include spaces within a `LABEL` value, use quotes and -backslashes as you would in command-line parsing. +backslashes as you would in command-line parsing. A few usage examples: LABEL "com.example.vendor"="ACME Incorporated" - -An image can have more than one label. To specify multiple labels, separate each -key-value pair with whitespace. - LABEL com.example.label-with-value="foo" LABEL version="1.0" LABEL description="This text illustrates \ that label-values can span multiple lines." -Docker recommends combining labels in a single `LABEL` instruction where +An image can have more than one label. To specify multiple labels, +Docker recommends combining labels into a single `LABEL` instruction where possible. Each `LABEL` instruction produces a new layer which can result in an -inefficient image if you use many labels. This example results in four image -layers. +inefficient image if you use many labels. This example results in a single image +layer. LABEL multi.label1="value1" multi.label2="value2" other="value3" + +The above can also be written as: + + LABEL multi.label1="value1" \ + multi.label2="value2" \ + other="value3" -Labels are additive including `LABEL`s in `FROM` images. As the system -encounters and then applies a new label, new `key`s override any previous labels -with identical keys. +Labels are additive including `LABEL`s in `FROM` images. If Docker +encounters a label/key that already exists, the new value overrides any previous +labels with identical keys. To view an image's labels, use the `docker inspect` command. @@ -484,14 +491,14 @@ and ENV myCat fluffy will yield the same net results in the final container, but the first form -does it all in one layer. +is preferred because it produces a single cache layer. The environment variables set using `ENV` will persist when a container is run from the resulting image. You can view the values using `docker inspect`, and change them using `docker run --env =`. > **Note**: -> Environment persistence can cause unexpected effects. For example, +> Environment persistence can cause unexpected side effects. For example, > setting `ENV DEBIAN_FRONTEND noninteractive` may confuse apt-get > users on a Debian-based image. To set a value for a single command, use > `RUN = `. @@ -512,16 +519,16 @@ directories then they must be relative to the source directory that is being built (the context of the build). Each `` may contain wildcards and matching will be done using Go's -[filepath.Match](http://golang.org/pkg/path/filepath#Match) rules. -For most command line uses this should act as expected, for example: +[filepath.Match](http://golang.org/pkg/path/filepath#Match) rules. For example: ADD hom* /mydir/ # adds all files starting with "hom" - ADD hom?.txt /mydir/ # ? is replaced with any single character + ADD hom?.txt /mydir/ # ? is replaced with any single character, e.g., "home.txt" The `` is an absolute path, or a path relative to `WORKDIR`, into which the source will be copied inside the destination container. - ADD test aDir/ # adds "test" to `WORKDIR`/aDir/ + ADD test relativeDir/ # adds "test" to `WORKDIR`/relativeDir/ + ADD test /absoluteDir # adds "test" to /absoluteDir All new files and directories are created with a UID and GID of 0. @@ -554,7 +561,7 @@ of whether or not the file has changed and the cache should be updated. guide](/articles/dockerfile_best-practices/#build-cache) for more information. -The copy obeys the following rules: +`ADD` obeys the following rules: - The `` path must be inside the *context* of the build; you cannot `ADD ../something /something`, because the first step of a @@ -573,6 +580,7 @@ The copy obeys the following rules: - If `` is a directory, the entire contents of the directory are copied, including filesystem metadata. + > **Note**: > The directory itself is not copied, just its contents. @@ -615,16 +623,16 @@ Multiple `` resource may be specified but they must be relative to the source directory that is being built (the context of the build). Each `` may contain wildcards and matching will be done using Go's -[filepath.Match](http://golang.org/pkg/path/filepath#Match) rules. -For most command line uses this should act as expected, for example: +[filepath.Match](http://golang.org/pkg/path/filepath#Match) rules. For example: COPY hom* /mydir/ # adds all files starting with "hom" - COPY hom?.txt /mydir/ # ? is replaced with any single character + COPY hom?.txt /mydir/ # ? is replaced with any single character, e.g., "home.txt" The `` is an absolute path, or a path relative to `WORKDIR`, into which the source will be copied inside the destination container. - COPY test aDir/ # adds "test" to `WORKDIR`/aDir/ + COPY test relativeDir/ # adds "test" to `WORKDIR`/relativeDir/ + COPY test /absoluteDir # adds "test" to /absoluteDir All new files and directories are created with a UID and GID of 0. @@ -632,7 +640,7 @@ All new files and directories are created with a UID and GID of 0. > If you build using STDIN (`docker build - < somefile`), there is no > build context, so `COPY` can't be used. -The copy obeys the following rules: +`COPY` obeys the following rules: - The `` path must be inside the *context* of the build; you cannot `COPY ../something /something`, because the first step of a @@ -641,6 +649,7 @@ The copy obeys the following rules: - If `` is a directory, the entire contents of the directory are copied, including filesystem metadata. + > **Note**: > The directory itself is not copied, just its contents. @@ -664,7 +673,7 @@ The copy obeys the following rules: ENTRYPOINT has two forms: - `ENTRYPOINT ["executable", "param1", "param2"]` - (the preferred *exec* form) + (*exec* form, preferred) - `ENTRYPOINT command param1 param2` (*shell* form)