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 <charleswhchan@users.noreply.github.com>
This commit is contained in:
Charles Chan
parent
7ce97dbe30
commit
60f76bbfe1
|
|
@ -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 <command>` (the command is run in a shell - `/bin/sh -c` - *shell* form)
|
||||
- `RUN <command>` (*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 <key>=<value>`.
|
||||
|
||||
> **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 <key>=<value> <command>`.
|
||||
|
|
@ -512,16 +519,16 @@ directories then they must be relative to the source directory that is
|
|||
being built (the context of the build).
|
||||
|
||||
Each `<src>` 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 `<dest>` 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 `<src>` 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 `<src>` 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 `<src>` resource may be specified but they must be relative
|
|||
to the source directory that is being built (the context of the build).
|
||||
|
||||
Each `<src>` 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 `<dest>` 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 `<src>` 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 `<src>` 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)
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue