@@ -10,48 +10,50 @@ parent = "mn_reference"

 # Dockerfile reference

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

-

-This page discusses the specifics of all the instructions you can use in your

-`Dockerfile`. To further help you write a clear, readable, maintainable

-`Dockerfile`, we've also written a [`Dockerfile` Best Practices

-guide](/articles/dockerfile_best-practices). Lastly, you can test your

-Dockerfile knowledge with the [Dockerfile tutorial](/userguide/level1).

+Docker can build images automatically by reading the instructions from a

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

+user could call on the command line to assemble an image. Using `docker build`

+users can create an automated build that executes several command-line

+instructions in succession.

+

+This page describes the commands you can use in a `Dockerfile`. When you are

+done reading this page, refer to the [`Dockerfile` Best

+Practices](/articles/dockerfile_best-practices) for a tip-oriented guide.

 ## Usage

-To [*build*](/reference/commandline/build) an image from a source repository,

-create a description file called `Dockerfile` at the root of your repository.

-This file will describe the steps to assemble the image.

+The [`docker build`](/reference/commandline/build/) command builds an image from

+a `Dockerfile` and a *context*. The build's context is the files at a specified

+location `PATH` or `URL`. The `PATH` is a directory on your local filesystem.

+The `URL` is a the location of a Git repository.

-Then call `docker build` with the path of your source repository as the argument

-(for example, `.`):

+A context is processed recursively. So, a `PATH` includes any subdirectories and

+the `URL` includes the repository and its submodules. A simple build command

+that uses the current directory as context:

     $ docker build .

+    Sending build context to Docker daemon  6.51 MB

+    ...

+

+The build is run by the Docker daemon, not by the CLI. The first thing a build

+process does is send the entire context (recursively) to the daemon.  In most

+cases, it's best to start with an empty directory as context and keep your

+Dockerfile in that directory. Add only the files needed for building the

+Dockerfile.

+

+>**Warning**: Do not use your root directory, `/`, as the `PATH` as it causes

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

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

-The path to the source repository defines where to find the *context* of

-the build. The build is run by the Docker daemon, not by the CLI, so the

-whole context must be transferred to the daemon. The Docker CLI reports

-"Sending build context to Docker daemon" when the context is sent to the daemon.

-

-> **Warning**

-> Avoid using your root directory, `/`, as the root of the source repository. The 

-> `docker build` command will use whatever directory contains the Dockerfile as the build

-> context (including all of its subdirectories). The build context will be sent to the

-> Docker daemon before building the image, which means if you use `/` as the source

-> repository, the entire contents of your hard drive will get sent to the daemon (and

-> thus to the machine running the daemon). You probably don't want that.

-

-In most cases, it's best to put each Dockerfile in an empty directory. Then,

-only add the files needed for building the Dockerfile to the directory. To

-increase the build's performance, you can exclude files and directories by

-adding a `.dockerignore` file to the directory.  For information about how to

-[create a `.dockerignore` file](#dockerignore-file) on this page.

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

 You can specify a repository and tag at which to save the new image if

 the build succeeds:

@@ -166,13 +168,13 @@ as well as:

 > variable, even when combined with any of the instructions listed above.

 Environment variable substitution will use the same value for each variable

-throughout the entire command.  In other words, in this example:

+throughout the entire command. In other words, in this example:

     ENV abc=hello

     ENV abc=bye def=$abc

     ENV ghi=$abc

-will result in `def` having a value of `hello`, not `bye`.  However, 

+will result in `def` having a value of `hello`, not `bye`. However, 

 `ghi` will have a value of `bye` because it is not part of the same command

 that set `abc` to `bye`.

@@ -191,7 +193,7 @@ expansion) is done using Go's

 You can specify exceptions to exclusion rules. To do this, simply prefix a

 pattern with an `!` (exclamation mark) in the same way you would in a

-`.gitignore` file.  Currently there is no support for regular expressions.

+`.gitignore` file. Currently there is no support for regular expressions.

 Formats like `[^temp*]` are ignored. 

 The following is an example `.dockerignore` file:

@@ -310,7 +312,7 @@ 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 

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

@@ -888,7 +890,7 @@ The `VOLUME` instruction creates a mount point with the specified name

 and marks it as holding externally mounted volumes from native host or other

 containers. The value can be a JSON array, `VOLUME ["/var/log/"]`, or a plain

 string with multiple arguments, such as `VOLUME /var/log` or `VOLUME /var/log

-/var/db`.  For more information/examples and mounting instructions via the

+/var/db`. For more information/examples and mounting instructions via the

 Docker client, refer to 

 [*Share Directories via Volumes*](/userguide/dockervolumes/#mount-a-host-directory-as-a-data-volume)

 documentation.