@@ -4,15 +4,17 @@ page_keywords: builder, docker, Dockerfile, automation, image creation

 # Dockerfile Reference

-**Docker can act as a builder** and read instructions from a text *Dockerfile*

-to automate the steps you would otherwise take manually to create an image.

-Executing `docker build` will run your steps and commit them along the way,

-giving you a final image.

+**Docker can build images automatically** by reading the instructions

+from a `Dockerfile`. A `Dockerfile` is a text document that contains all

+the commands you would normally execute manually in order to build a

+Docker image. By calling `docker build` from your terminal, you can have

+Docker build your image step by step, executing the instructions

+successively.

 ## Usage

 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.

 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

     Successfully built 1a5ffc17324d

-When you're done with your build, you're ready to look into

-[*Pushing a repository to its registry*](

-/userguide/dockerrepos/#image-push).

+When you're done with your build, you're ready to look into [*Pushing a

+repository to its registry*]( /userguide/dockerrepos/#image-push).

 ## Format

-Here is the format of the Dockerfile:

+Here is the format of the `Dockerfile`:

     # Comment

     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

 be UPPERCASE in order to distinguish them from arguments more easily.

-Docker evaluates the instructions in a Dockerfile in order. **The first

-instruction must be \`FROM\`** in order to specify the [*Base

+Docker runs the instructions in a `Dockerfile` in order. **The

+first instruction must be \`FROM\`** in order to specify the [*Base

 Image*](/terms/image/#base-image-def) from which you are building.

 Docker will treat lines that *begin* with `#` as a

@@ -80,10 +81,10 @@ be treated as an argument. This allows statements like:

     # Comment

     RUN echo 'we are running some # of cool things'

-Here is the set of instructions you can use in a Dockerfile

-for building images.

+Here is the set of instructions you can use in a `Dockerfile` for building

+images.

-## .dockerignore

+## The `.dockerignore` file

 If a file named `.dockerignore` exists in the source repository, then it

 is interpreted as a newline-separated list of exclusion patterns.

@@ -124,15 +125,15 @@ Or

     FROM <image>:<tag>

 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

 to start by **pulling an image** from the [*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

-multiple images. Simply make a note of the last image id output by the commit

+`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.

 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

 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

 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`

 commands using a base image that does not contain `/bin/sh`.

-The cache for `RUN` instructions isn't invalidated automatically during the

-next build. The cache for an instruction like `RUN apt-get dist-upgrade -y`

-will be reused during the next build.

-The cache for `RUN` instructions can be invalidated by using the `--no-cache`

-flag, for example `docker build --no-cache`.

+The cache for `RUN` instructions isn't invalidated automatically during

+the next build. The cache for an instruction like `RUN apt-get

+dist-upgrade -y` will be reused during the next build.  The cache for

+`RUN` instructions can be invalidated by using the `--no-cache` flag,

+for example `docker build --no-cache`.

 The cache for `RUN` instructions can be invalidated by `ADD` instructions. See

 [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

   might notice it during an attempt to `rm` a file, for example. The issue

   describes a workaround.

-- [Issue 2424](https://github.com/dotcloud/docker/issues/2424) Locale will

-  not be set automatically.

 ## CMD

-CMD has three forms:

+The `CMD` instruction has three forms:

 - `CMD ["executable","param1","param2"]` (like an *exec*, this is the preferred form)

 - `CMD ["param1","param2"]` (as *default parameters to ENTRYPOINT*)

 - `CMD command param1 param2` (as a *shell*)

-There can only be one CMD in a Dockerfile. If you list more than one CMD

-then only the last CMD will take effect.

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

-**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

-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

 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`:

     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

 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:

     FROM ubuntu

@@ -218,7 +218,7 @@ you should consider using `ENTRYPOINT` in combination with `CMD`. See

 [*ENTRYPOINT*](#entrypoint).

 If the user specifies arguments to `docker run` then they will override the

-default specified in CMD.

+default specified in `CMD`.

 > **Note**:

 > 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

 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**:

-> If you build by passing a Dockerfile through STDIN (`docker build - < somefile`),

-> there is no build context, so the Dockerfile can only contain a URL

-> based ADD statement.

-

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

->

+> If you build by passing a `Dockerfile` through STDIN (`docker

+> build - < somefile`), there is no build context, so the `Dockerfile`

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

+

 > **Note**:

-> If your URL files are protected using authentication, you will need to

-> use `RUN wget` , `RUN curl`

-> or use another tool from within the container as ADD does not support

+> If your URL files are protected using authentication, you

+> will need to use `RUN wget`, `RUN curl` or use another tool from

+> within the container as the `ADD` instruction does not support

 > authentication.

 > **Note**:

@@ -314,9 +313,9 @@ The copy obeys the following rules:

   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:

-    1. whatever existed at the destination path and

-    2. the contents of the source tree, with conflicts resolved in favor of 

-       "2." on a file-by-file basis.

+    1. Whatever existed at the destination path and

+    2. The contents of the source tree, with conflicts resolved in favor

+       of "2." on a file-by-file basis.

 - 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

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

 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**:

 > 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

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

 ## WORKDIR

     WORKDIR /path/to/workdir

-The `WORKDIR` instruction sets the working directory for the `RUN`, `CMD` and

-`ENTRYPOINT` Dockerfile commands that follow it.

+The `WORKDIR` instruction sets the working directory for any `RUN`, `CMD` and

+`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`

 instruction. For example:

     WORKDIR /a WORKDIR b WORKDIR c RUN pwd

-The output of the final `pwd` command in this

-Dockerfile would be `/a/b/c`.

+The output of the final `pwd` command in this Dockerfile would be

+`/a/b/c`.

 ## ONBUILD

     ONBUILD [INSTRUCTION]

-The `ONBUILD` instruction adds to the image a

-"trigger" instruction to be executed at a later time, when the image is

-used as the base for another build. The trigger will be executed in the

-context of the downstream build, as if it had been inserted immediately

-after the *FROM* instruction in the downstream Dockerfile.

+The `ONBUILD` instruction adds to the image a *trigger* instruction to

+be executed at a later time, when the image is used as the base for

+another build. The trigger will be executed in the context of the

+downstream build, as if it had been inserted immediately after the

+`FROM` instruction in the downstream `Dockerfile`.

 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

 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

 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

 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

 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.

 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

    does not otherwise affect the current build.

 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

-   *docker inspect*.

+   image manifest, under the key `OnBuild`. They can be inspected with

+   the `docker inspect` command.

 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,

-   the downstream builder looks for *ONBUILD* triggers, and executes

+   `FROM` instruction. As part of processing the `FROM` instruction,

+   the downstream builder looks for `ONBUILD` triggers, and executes

    them in the same order they were registered. If any of the triggers

-   fail, the *FROM* instruction is aborted which in turn causes the

-   build to fail. If all triggers succeed, the FROM instruction

+   fail, the `FROM` instruction is aborted which in turn causes the

+   build to fail. If all triggers succeed, the `FROM` instruction

    completes and the build continues as usual.

 4. Triggers are cleared from the final image after being executed. In

    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

     [...]

-> **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

@@ -557,3 +556,4 @@ For example you might add something like this:

     # You᾿ll now have two images, 907ad6c2736f with /bar, and 695d7793cbe4 with

     # /oink.

+