mirror of https://github.com/docker/cli.git
General cleanup of the builder.md file
Docker-DCO-1.1-Signed-off-by: James Turnbull <james@lovedthanlost.net> (github: jamtur01)
This commit is contained in:
parent
7cf495874c
commit
6c10e6fe81
|
@ -4,15 +4,17 @@ page_keywords: builder, docker, Dockerfile, automation, image creation
|
||||||
|
|
||||||
# Dockerfile Reference
|
# Dockerfile Reference
|
||||||
|
|
||||||
**Docker can act as a builder** and read instructions from a text *Dockerfile*
|
**Docker can build images automatically** by reading the instructions
|
||||||
to automate the steps you would otherwise take manually to create an image.
|
from a `Dockerfile`. A `Dockerfile` is a text document that contains all
|
||||||
Executing `docker build` will run your steps and commit them along the way,
|
the commands you would normally execute manually in order to build a
|
||||||
giving you a final image.
|
Docker image. By calling `docker build` from your terminal, you can have
|
||||||
|
Docker build your image step by step, executing the instructions
|
||||||
|
successively.
|
||||||
|
|
||||||
## Usage
|
## Usage
|
||||||
|
|
||||||
To [*build*](../commandline/cli/#cli-build) an image from a source repository,
|
To [*build*](../commandline/cli/#cli-build) an image from a source repository,
|
||||||
create a description file called Dockerfile at the root of your repository.
|
create a description file called `Dockerfile` at the root of your repository.
|
||||||
This file will describe the steps to assemble the image.
|
This file will describe the steps to assemble the image.
|
||||||
|
|
||||||
Then call `docker build` with the path of your source repository as the argument
|
Then call `docker build` with the path of your source repository as the argument
|
||||||
|
@ -55,13 +57,12 @@ accelerating `docker build` significantly (indicated by `Using cache`):
|
||||||
---> 1a5ffc17324d
|
---> 1a5ffc17324d
|
||||||
Successfully built 1a5ffc17324d
|
Successfully built 1a5ffc17324d
|
||||||
|
|
||||||
When you're done with your build, you're ready to look into
|
When you're done with your build, you're ready to look into [*Pushing a
|
||||||
[*Pushing a repository to its registry*](
|
repository to its registry*]( /userguide/dockerrepos/#image-push).
|
||||||
/userguide/dockerrepos/#image-push).
|
|
||||||
|
|
||||||
## Format
|
## Format
|
||||||
|
|
||||||
Here is the format of the Dockerfile:
|
Here is the format of the `Dockerfile`:
|
||||||
|
|
||||||
# Comment
|
# Comment
|
||||||
INSTRUCTION arguments
|
INSTRUCTION arguments
|
||||||
|
@ -69,8 +70,8 @@ Here is the format of the Dockerfile:
|
||||||
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.
|
be UPPERCASE in order to distinguish them from arguments more easily.
|
||||||
|
|
||||||
Docker evaluates the instructions in a Dockerfile in order. **The first
|
Docker runs the instructions in a `Dockerfile` in order. **The
|
||||||
instruction must be \`FROM\`** in order to specify the [*Base
|
first instruction must be \`FROM\`** in order to specify the [*Base
|
||||||
Image*](/terms/image/#base-image-def) from which you are building.
|
Image*](/terms/image/#base-image-def) from which you are building.
|
||||||
|
|
||||||
Docker will treat lines that *begin* with `#` as a
|
Docker will treat lines that *begin* with `#` as a
|
||||||
|
@ -80,10 +81,10 @@ be treated as an argument. This allows statements like:
|
||||||
# Comment
|
# Comment
|
||||||
RUN echo 'we are running some # of cool things'
|
RUN echo 'we are running some # of cool things'
|
||||||
|
|
||||||
Here is the set of instructions you can use in a Dockerfile
|
Here is the set of instructions you can use in a `Dockerfile` for building
|
||||||
for building images.
|
images.
|
||||||
|
|
||||||
## .dockerignore
|
## The `.dockerignore` file
|
||||||
|
|
||||||
If a file named `.dockerignore` exists in the source repository, then it
|
If a file named `.dockerignore` exists in the source repository, then it
|
||||||
is interpreted as a newline-separated list of exclusion patterns.
|
is interpreted as a newline-separated list of exclusion patterns.
|
||||||
|
@ -124,15 +125,15 @@ Or
|
||||||
FROM <image>:<tag>
|
FROM <image>:<tag>
|
||||||
|
|
||||||
The `FROM` instruction sets the [*Base Image*](/terms/image/#base-image-def)
|
The `FROM` instruction sets the [*Base Image*](/terms/image/#base-image-def)
|
||||||
for subsequent instructions. As such, a valid Dockerfile must have `FROM` as
|
for subsequent instructions. As such, a valid `Dockerfile` must have `FROM` as
|
||||||
its first instruction. The image can be any valid image – it is especially easy
|
its first instruction. The image can be any valid image – it is especially easy
|
||||||
to start by **pulling an image** from the [*Public Repositories*](
|
to start by **pulling an image** from the [*Public Repositories*](
|
||||||
/userguide/dockerrepos/#using-public-repositories).
|
/userguide/dockerrepos/#using-public-repositories).
|
||||||
|
|
||||||
`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
|
multiple images. Simply make a note of the last image ID output by the commit
|
||||||
before each new `FROM` command.
|
before each new `FROM` command.
|
||||||
|
|
||||||
If no `tag` is given to the `FROM` instruction, `latest` is assumed. If the
|
If no `tag` is given to the `FROM` instruction, `latest` is assumed. If the
|
||||||
|
@ -154,7 +155,7 @@ RUN has 2 forms:
|
||||||
|
|
||||||
The `RUN` instruction will execute any commands in a new layer on top of the
|
The `RUN` instruction will execute any commands in a new layer on top of the
|
||||||
current image and commit the results. The resulting committed image will be
|
current image and commit the results. The resulting committed image will be
|
||||||
used for the next step in the Dockerfile.
|
used for the next step in the `Dockerfile`.
|
||||||
|
|
||||||
Layering `RUN` instructions and generating commits conforms to the core
|
Layering `RUN` instructions and generating commits conforms to the core
|
||||||
concepts of Docker where commits are cheap and containers can be created from
|
concepts of Docker where commits are cheap and containers can be created from
|
||||||
|
@ -163,11 +164,11 @@ any point in an image's history, much like source control.
|
||||||
The *exec* form makes it possible to avoid shell string munging, and to `RUN`
|
The *exec* form makes it possible to avoid shell string munging, and to `RUN`
|
||||||
commands using a base image that does not contain `/bin/sh`.
|
commands using a base image that does not contain `/bin/sh`.
|
||||||
|
|
||||||
The cache for `RUN` instructions isn't invalidated automatically during the
|
The cache for `RUN` instructions isn't invalidated automatically during
|
||||||
next build. The cache for an instruction like `RUN apt-get dist-upgrade -y`
|
the next build. The cache for an instruction like `RUN apt-get
|
||||||
will be reused during the next build.
|
dist-upgrade -y` will be reused during the next build. The cache for
|
||||||
The cache for `RUN` instructions can be invalidated by using the `--no-cache`
|
`RUN` instructions can be invalidated by using the `--no-cache` flag,
|
||||||
flag, for example `docker build --no-cache`.
|
for example `docker build --no-cache`.
|
||||||
|
|
||||||
The cache for `RUN` instructions can be invalidated by `ADD` instructions. See
|
The cache for `RUN` instructions can be invalidated by `ADD` instructions. See
|
||||||
[below](#add) for details.
|
[below](#add) for details.
|
||||||
|
@ -178,28 +179,27 @@ The cache for `RUN` instructions can be invalidated by `ADD` instructions. See
|
||||||
permissions problems that can occur when using the AUFS file system. You
|
permissions problems that can occur when using the AUFS file system. You
|
||||||
might notice it during an attempt to `rm` a file, for example. The issue
|
might notice it during an attempt to `rm` a file, for example. The issue
|
||||||
describes a workaround.
|
describes a workaround.
|
||||||
- [Issue 2424](https://github.com/dotcloud/docker/issues/2424) Locale will
|
|
||||||
not be set automatically.
|
|
||||||
|
|
||||||
## CMD
|
## CMD
|
||||||
|
|
||||||
CMD has three forms:
|
The `CMD` instruction has three forms:
|
||||||
|
|
||||||
- `CMD ["executable","param1","param2"]` (like an *exec*, this is the preferred form)
|
- `CMD ["executable","param1","param2"]` (like an *exec*, this is the preferred form)
|
||||||
- `CMD ["param1","param2"]` (as *default parameters to ENTRYPOINT*)
|
- `CMD ["param1","param2"]` (as *default parameters to ENTRYPOINT*)
|
||||||
- `CMD command param1 param2` (as a *shell*)
|
- `CMD command param1 param2` (as a *shell*)
|
||||||
|
|
||||||
There can only be one CMD in a Dockerfile. If you list more than one CMD
|
There can only be one `CMD` instruction in a `Dockerfile`. If you list more than one `CMD`
|
||||||
then only the last CMD will take effect.
|
then only the last `CMD` will take effect.
|
||||||
|
|
||||||
**The main purpose of a CMD is to provide defaults for an executing
|
**The main purpose of a `CMD` is to provide defaults for an executing
|
||||||
container.** These defaults can include an executable, or they can omit
|
container.** These defaults can include an executable, or they can omit
|
||||||
the executable, in which case you must specify an ENTRYPOINT as well.
|
the executable, in which case you must specify an `ENTRYPOINT`
|
||||||
|
instruction as well.
|
||||||
|
|
||||||
When used in the shell or exec formats, the `CMD` instruction sets the command
|
When used in the shell or exec formats, the `CMD` instruction sets the command
|
||||||
to be executed when running the image.
|
to be executed when running the image.
|
||||||
|
|
||||||
If you use the *shell* form of the CMD, then the `<command>` will execute in
|
If you use the *shell* form of the `CMD`, then the `<command>` will execute in
|
||||||
`/bin/sh -c`:
|
`/bin/sh -c`:
|
||||||
|
|
||||||
FROM ubuntu
|
FROM ubuntu
|
||||||
|
@ -207,7 +207,7 @@ If you use the *shell* form of the CMD, then the `<command>` will execute in
|
||||||
|
|
||||||
If you want to **run your** `<command>` **without a shell** then you must
|
If you want to **run your** `<command>` **without a shell** then you must
|
||||||
express the command as a JSON array and give the full path to the executable.
|
express the command as a JSON array and give the full path to the executable.
|
||||||
**This array form is the preferred format of CMD.** Any additional parameters
|
**This array form is the preferred format of `CMD`.** Any additional parameters
|
||||||
must be individually expressed as strings in the array:
|
must be individually expressed as strings in the array:
|
||||||
|
|
||||||
FROM ubuntu
|
FROM ubuntu
|
||||||
|
@ -218,7 +218,7 @@ you should consider using `ENTRYPOINT` in combination with `CMD`. See
|
||||||
[*ENTRYPOINT*](#entrypoint).
|
[*ENTRYPOINT*](#entrypoint).
|
||||||
|
|
||||||
If the user specifies arguments to `docker run` then they will override the
|
If the user specifies arguments to `docker run` then they will override the
|
||||||
default specified in CMD.
|
default specified in `CMD`.
|
||||||
|
|
||||||
> **Note**:
|
> **Note**:
|
||||||
> don't confuse `RUN` with `CMD`. `RUN` actually runs a command and commits
|
> don't confuse `RUN` with `CMD`. `RUN` actually runs a command and commits
|
||||||
|
@ -264,24 +264,23 @@ being built (also called the *context* of the build) or a remote file URL.
|
||||||
`<dest>` is the absolute path to which the source will be copied inside the
|
`<dest>` is the absolute path to which the source will be copied inside the
|
||||||
destination container.
|
destination container.
|
||||||
|
|
||||||
All new files and directories are created with a uid and gid of 0.
|
All new files and directories are created with a UID and GID of 0.
|
||||||
|
|
||||||
In the case where `<src>` is a remote file URL, the destination will have permissions 600.
|
In the case where `<src>` is a remote file URL, the destination will
|
||||||
|
have permissions of 600.
|
||||||
|
|
||||||
> **Note**:
|
> **Note**:
|
||||||
> If you build by passing a Dockerfile through STDIN (`docker build - < somefile`),
|
> If you build by passing a `Dockerfile` through STDIN (`docker
|
||||||
> there is no build context, so the Dockerfile can only contain a URL
|
> build - < somefile`), there is no build context, so the `Dockerfile`
|
||||||
> based ADD statement.
|
> can only contain a URL based `ADD` instruction. You can also pass a
|
||||||
|
> compressed archive through STDIN: (`docker build - < archive.tar.gz`),
|
||||||
|
> the `Dockerfile` at the root of the archive and the rest of the
|
||||||
|
> archive will get used at the context of the build.
|
||||||
|
|
||||||
> You can also pass a compressed archive through STDIN:
|
|
||||||
> (`docker build - < archive.tar.gz`), the `Dockerfile` at the root of
|
|
||||||
> the archive and the rest of the archive will get used at the context
|
|
||||||
> of the build.
|
|
||||||
>
|
|
||||||
> **Note**:
|
> **Note**:
|
||||||
> If your URL files are protected using authentication, you will need to
|
> If your URL files are protected using authentication, you
|
||||||
> use `RUN wget` , `RUN curl`
|
> will need to use `RUN wget`, `RUN curl` or use another tool from
|
||||||
> or use another tool from within the container as ADD does not support
|
> within the container as the `ADD` instruction does not support
|
||||||
> authentication.
|
> authentication.
|
||||||
|
|
||||||
> **Note**:
|
> **Note**:
|
||||||
|
@ -314,9 +313,9 @@ The copy obeys the following rules:
|
||||||
from *remote* URLs are **not** decompressed. When a directory is copied or
|
from *remote* URLs are **not** decompressed. When a directory is copied or
|
||||||
unpacked, it has the same behavior as `tar -x`: the result is the union of:
|
unpacked, it has the same behavior as `tar -x`: the result is the union of:
|
||||||
|
|
||||||
1. whatever existed at the destination path and
|
1. Whatever existed at the destination path and
|
||||||
2. the contents of the source tree, with conflicts resolved in favor of
|
2. The contents of the source tree, with conflicts resolved in favor
|
||||||
"2." on a file-by-file basis.
|
of "2." on a file-by-file basis.
|
||||||
|
|
||||||
- If `<src>` is any other kind of file, it is copied individually along with
|
- If `<src>` is any other kind of file, it is copied individually along with
|
||||||
its metadata. In this case, if `<dest>` ends with a trailing slash `/`, it
|
its metadata. In this case, if `<dest>` ends with a trailing slash `/`, it
|
||||||
|
@ -342,7 +341,7 @@ being built (also called the *context* of the build).
|
||||||
`<dest>` is the absolute path to which the source will be copied inside the
|
`<dest>` is the absolute path to which the source will be copied inside the
|
||||||
destination container.
|
destination container.
|
||||||
|
|
||||||
All new files and directories are created with a uid and gid of 0.
|
All new files and directories are created with a UID and GID of 0.
|
||||||
|
|
||||||
> **Note**:
|
> **Note**:
|
||||||
> If you build using STDIN (`docker build - < somefile`), there is no
|
> If you build using STDIN (`docker build - < somefile`), there is no
|
||||||
|
@ -431,34 +430,34 @@ instructions via the Docker client, refer to [*Share Directories via Volumes*](
|
||||||
|
|
||||||
USER daemon
|
USER daemon
|
||||||
|
|
||||||
The `USER` instruction sets the username or UID to use when running the image
|
The `USER` instruction sets the user name or UID to use when running the image
|
||||||
and for any following `RUN` directives.
|
and for any following `RUN` directives.
|
||||||
|
|
||||||
## WORKDIR
|
## WORKDIR
|
||||||
|
|
||||||
WORKDIR /path/to/workdir
|
WORKDIR /path/to/workdir
|
||||||
|
|
||||||
The `WORKDIR` instruction sets the working directory for the `RUN`, `CMD` and
|
The `WORKDIR` instruction sets the working directory for any `RUN`, `CMD` and
|
||||||
`ENTRYPOINT` Dockerfile commands that follow it.
|
`ENTRYPOINT` instructions that follow it in the `Dockerfile`.
|
||||||
|
|
||||||
It can be used multiple times in the one Dockerfile. If a relative path
|
It can be used multiple times in the one `Dockerfile`. If a relative path
|
||||||
is provided, it will be relative to the path of the previous `WORKDIR`
|
is provided, it will be relative to the path of the previous `WORKDIR`
|
||||||
instruction. For example:
|
instruction. For example:
|
||||||
|
|
||||||
WORKDIR /a WORKDIR b WORKDIR c RUN pwd
|
WORKDIR /a WORKDIR b WORKDIR c RUN pwd
|
||||||
|
|
||||||
The output of the final `pwd` command in this
|
The output of the final `pwd` command in this Dockerfile would be
|
||||||
Dockerfile would be `/a/b/c`.
|
`/a/b/c`.
|
||||||
|
|
||||||
## ONBUILD
|
## ONBUILD
|
||||||
|
|
||||||
ONBUILD [INSTRUCTION]
|
ONBUILD [INSTRUCTION]
|
||||||
|
|
||||||
The `ONBUILD` instruction adds to the image a
|
The `ONBUILD` instruction adds to the image a *trigger* instruction to
|
||||||
"trigger" instruction to be executed at a later time, when the image is
|
be executed at a later time, when the image is used as the base for
|
||||||
used as the base for another build. The trigger will be executed in the
|
another build. The trigger will be executed in the context of the
|
||||||
context of the downstream build, as if it had been inserted immediately
|
downstream build, as if it had been inserted immediately after the
|
||||||
after the *FROM* instruction in the downstream Dockerfile.
|
`FROM` instruction in the downstream `Dockerfile`.
|
||||||
|
|
||||||
Any build instruction can be registered as a trigger.
|
Any build instruction can be registered as a trigger.
|
||||||
|
|
||||||
|
@ -466,33 +465,33 @@ This is useful if you are building an image which will be used as a base
|
||||||
to build other images, for example an application build environment or a
|
to build other images, for example an application build environment or a
|
||||||
daemon which may be customized with user-specific configuration.
|
daemon which may be customized with user-specific configuration.
|
||||||
|
|
||||||
For example, if your image is a reusable python application builder, it
|
For example, if your image is a reusable Python application builder, it
|
||||||
will require application source code to be added in a particular
|
will require application source code to be added in a particular
|
||||||
directory, and it might require a build script to be called *after*
|
directory, and it might require a build script to be called *after*
|
||||||
that. You can't just call *ADD* and *RUN* now, because you don't yet
|
that. You can't just call `ADD` and `RUN` now, because you don't yet
|
||||||
have access to the application source code, and it will be different for
|
have access to the application source code, and it will be different for
|
||||||
each application build. You could simply provide application developers
|
each application build. You could simply provide application developers
|
||||||
with a boilerplate Dockerfile to copy-paste into their application, but
|
with a boilerplate `Dockerfile` to copy-paste into their application, but
|
||||||
that is inefficient, error-prone and difficult to update because it
|
that is inefficient, error-prone and difficult to update because it
|
||||||
mixes with application-specific code.
|
mixes with application-specific code.
|
||||||
|
|
||||||
The solution is to use *ONBUILD* to register in advance instructions to
|
The solution is to use `ONBUILD` to register advance instructions to
|
||||||
run later, during the next build stage.
|
run later, during the next build stage.
|
||||||
|
|
||||||
Here's how it works:
|
Here's how it works:
|
||||||
|
|
||||||
1. When it encounters an *ONBUILD* instruction, the builder adds a
|
1. When it encounters an `ONBUILD` instruction, the builder adds a
|
||||||
trigger to the metadata of the image being built. The instruction
|
trigger to the metadata of the image being built. The instruction
|
||||||
does not otherwise affect the current build.
|
does not otherwise affect the current build.
|
||||||
2. At the end of the build, a list of all triggers is stored in the
|
2. At the end of the build, a list of all triggers is stored in the
|
||||||
image manifest, under the key *OnBuild*. They can be inspected with
|
image manifest, under the key `OnBuild`. They can be inspected with
|
||||||
*docker inspect*.
|
the `docker inspect` command.
|
||||||
3. Later the image may be used as a base for a new build, using the
|
3. Later the image may be used as a base for a new build, using the
|
||||||
*FROM* instruction. As part of processing the *FROM* instruction,
|
`FROM` instruction. As part of processing the `FROM` instruction,
|
||||||
the downstream builder looks for *ONBUILD* triggers, and executes
|
the downstream builder looks for `ONBUILD` triggers, and executes
|
||||||
them in the same order they were registered. If any of the triggers
|
them in the same order they were registered. If any of the triggers
|
||||||
fail, the *FROM* instruction is aborted which in turn causes the
|
fail, the `FROM` instruction is aborted which in turn causes the
|
||||||
build to fail. If all triggers succeed, the FROM instruction
|
build to fail. If all triggers succeed, the `FROM` instruction
|
||||||
completes and the build continues as usual.
|
completes and the build continues as usual.
|
||||||
4. Triggers are cleared from the final image after being executed. In
|
4. Triggers are cleared from the final image after being executed. In
|
||||||
other words they are not inherited by "grand-children" builds.
|
other words they are not inherited by "grand-children" builds.
|
||||||
|
@ -504,9 +503,9 @@ For example you might add something like this:
|
||||||
ONBUILD RUN /usr/local/bin/python-build --dir /app/src
|
ONBUILD RUN /usr/local/bin/python-build --dir /app/src
|
||||||
[...]
|
[...]
|
||||||
|
|
||||||
> **Warning**: Chaining ONBUILD instructions using ONBUILD ONBUILD isn't allowed.
|
> **Warning**: Chaining `ONBUILD` instructions using `ONBUILD ONBUILD` isn't allowed.
|
||||||
|
|
||||||
> **Warning**: ONBUILD may not trigger FROM or MAINTAINER instructions.
|
> **Warning**: The `ONBUILD` instruction may not trigger `FROM` or `MAINTAINER` instructions.
|
||||||
|
|
||||||
## Dockerfile Examples
|
## Dockerfile Examples
|
||||||
|
|
||||||
|
@ -557,3 +556,4 @@ For example you might add something like this:
|
||||||
|
|
||||||
# You᾿ll now have two images, 907ad6c2736f with /bar, and 695d7793cbe4 with
|
# You᾿ll now have two images, 907ad6c2736f with /bar, and 695d7793cbe4 with
|
||||||
# /oink.
|
# /oink.
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue