q3k
/
docker-cli-openbsd
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

General cleanup of the builder.md file 

Docker-DCO-1.1-Signed-off-by: James Turnbull <james@lovedthanlost.net> (github: jamtur01)
master
James Turnbull 2014-07-11 22:28:36 -04:00 committed by Tibor Vass
parent 7cf495874c
commit 6c10e6fe81
1 changed files with 75 additions and 75 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

150
docs/sources/reference/builder.md
View File

@ -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.