@@ -88,31 +88,65 @@ Examples:

     Usage: docker build [OPTIONS] PATH | URL | -

     Build a new container image from the source code at PATH

-      -t="": Repository name (and optionally a tag) to be applied to the resulting image in case of success.

+      -t="": Repository name (and optionally a tag) to be applied 

+             to the resulting image in case of success.

       -q=false: Suppress verbose build output.

       -no-cache: Do not use the cache when building the image.

       -rm: Remove intermediate containers after a successful build

-    When a single Dockerfile is given as URL, then no context is set. When a git repository is set as URL, the repository is used as context

+

+The files at PATH or URL are called the "context" of the build. The

+build process may refer to any of the files in the context, for

+example when using an :ref:`ADD <dockerfile_add>` instruction.  When a

+single ``Dockerfile`` is given as URL, then no context is set.  When a

+git repository is set as URL, then the repository is used as the

+context

 .. _cli_build_examples:

+.. seealso:: :ref:`dockerbuilder`.

+

 Examples:

 ~~~~~~~~~

 .. code-block:: bash

     sudo docker build .

+    Uploading context 10240 bytes

+    Step 1 : FROM busybox

+    Pulling repository busybox

+     ---> e9aa60c60128MB/2.284 MB (100%) endpoint: https://cdn-registry-1.docker.io/v1/

+    Step 2 : RUN ls -lh /

+     ---> Running in 9c9e81692ae9

+    total 24

+    drwxr-xr-x    2 root     root        4.0K Mar 12  2013 bin

+    drwxr-xr-x    5 root     root        4.0K Oct 19 00:19 dev

+    drwxr-xr-x    2 root     root        4.0K Oct 19 00:19 etc

+    drwxr-xr-x    2 root     root        4.0K Nov 15 23:34 lib

+    lrwxrwxrwx    1 root     root           3 Mar 12  2013 lib64 -> lib

+    dr-xr-xr-x  116 root     root           0 Nov 15 23:34 proc

+    lrwxrwxrwx    1 root     root           3 Mar 12  2013 sbin -> bin

+    dr-xr-xr-x   13 root     root           0 Nov 15 23:34 sys

+    drwxr-xr-x    2 root     root        4.0K Mar 12  2013 tmp

+    drwxr-xr-x    2 root     root        4.0K Nov 15 23:34 usr

+     ---> b35f4035db3f

+    Step 3 : CMD echo Hello World

+     ---> Running in 02071fceb21b

+     ---> f52f38b7823e

+    Successfully built f52f38b7823e

+

+This example specifies that the PATH is ``.``, and so all the files in

+the local directory get tar'd and sent to the Docker daemon.  The PATH

+specifies where to find the files for the "context" of the build on

+the Docker daemon. Remember that the daemon could be running on a

+remote machine and that no parsing of the Dockerfile happens at the

+client side (where you're running ``docker build``). That means that

+*all* the files at PATH get sent, not just the ones listed to

+:ref:`ADD <dockerfile_add>` in the ``Dockerfile``.

+

+The transfer of context from the local machine to the Docker daemon is

+what the ``docker`` client means when you see the "Uploading context"

+message.

-This will read the ``Dockerfile`` from the current directory. It will

-also send any other files and directories found in the current

-directory to the ``docker`` daemon.

-

-The contents of this directory would be used by ``ADD`` commands found

-within the ``Dockerfile``.  This will send a lot of data to the

-``docker`` daemon if the current directory contains a lot of data.  If

-the absolute path is provided instead of ``.`` then only the files and

-directories required by the ADD commands from the ``Dockerfile`` will be

-added to the context and transferred to the ``docker`` daemon.

 .. code-block:: bash

@@ -129,16 +163,15 @@ tag will be ``2.0``

 This will read a ``Dockerfile`` from *stdin* without context. Due to

 the lack of a context, no contents of any local directory will be sent

-to the ``docker`` daemon.  ``ADD`` doesn't work when running in this

-mode because the absence of the context provides no source files to

-copy to the container.

+to the ``docker`` daemon.  Since there is no context, a Dockerfile

+``ADD`` only works if it refers to a remote URL.

 .. code-block:: bash

     sudo docker build github.com/creack/docker-firefox

-This will clone the Github repository and use it as context. The

-``Dockerfile`` at the root of the repository is used as

+This will clone the Github repository and use the cloned repository as

+context. The ``Dockerfile`` at the root of the repository is used as

 ``Dockerfile``.  Note that you can specify an arbitrary git repository

 by using the ``git://`` schema.

@@ -15,27 +15,39 @@ commit them along the way, giving you a final image.

 .. contents:: Table of Contents

+.. _dockerfile_usage:

+

 1. Usage

 ========

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

+To :ref:`build <cli_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.

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

-argument:

+argument (for example, ``.``):

     ``sudo docker build .``

+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 "Uploading context" when the context is sent to the daemon.

+

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

 build succeeds:

     ``sudo docker build -t shykes/myapp .``

-Docker will run your steps one-by-one, committing the result if necessary,

-before finally outputting the ID of your new image.

+The Docker daemon will run your steps one-by-one, committing the

+result if necessary, before finally outputting the ID of your new

+image. The Docker daemon will automatically clean up the context you

+sent.

-When you're done with your build, you're ready to look into :ref:`image_push`.

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

+:ref:`image_push`.

+

+.. _dockerfile_format:

 2. Format

 =========

@@ -63,12 +75,16 @@ allows statements like:

     # Comment

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

+.. _dockerfile_instructions:

+

 3. Instructions

 ===============

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

 building images.

+.. _dockerfile_from:

+

 3.1 FROM

 --------

@@ -94,6 +110,8 @@ output by the commit before each new ``FROM`` command.

 If no ``tag`` is given to the ``FROM`` instruction, ``latest`` is

 assumed. If the used tag does not exist, an error will be returned.

+.. _dockerfile_maintainer:

+

 3.2 MAINTAINER

 --------------

@@ -102,6 +120,8 @@ assumed. If the used tag does not exist, an error will be returned.

 The ``MAINTAINER`` instruction allows you to set the *Author* field of

 the generated images.

+.. _dockerfile_run:

+

 3.3 RUN

 -------

@@ -124,7 +144,7 @@ Known Issues (RUN)

   ``rm`` a file, for example. The issue describes a workaround.

 * :issue:`2424` Locale will not be set automatically.

-

+.. _dockerfile_cmd:

 3.4 CMD

 -------

@@ -169,7 +189,7 @@ array:

 If you would like your container to run the same executable every

 time, then you should consider using ``ENTRYPOINT`` in combination

-with ``CMD``. See :ref:`entrypoint_def`.

+with ``CMD``. See :ref:`dockerfile_entrypoint`.

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

 override the default specified in CMD.

@@ -179,6 +199,8 @@ override the default specified in CMD.

     command and commits the result; ``CMD`` does not execute anything at

     build time, but specifies the intended command for the image.

+.. _dockerfile_expose:

+

 3.5 EXPOSE

 ----------

@@ -189,6 +211,8 @@ functionally equivalent to running ``docker commit -run '{"PortSpecs":

 ["<port>", "<port2>"]}'`` outside the builder. Refer to

 :ref:`port_redirection` for detailed information.

+.. _dockerfile_env:

+

 3.6 ENV

 -------

@@ -203,6 +227,8 @@ with ``<key>=<value>``

     The environment variables will persist when a container is run

     from the resulting image.

+.. _dockerfile_add:

+

 3.7 ADD

 -------

@@ -263,7 +289,7 @@ The copy obeys the following rules:

 * If ``<dest>`` doesn't exist, it is created along with all missing

   directories in its path.

-.. _entrypoint_def:

+.. _dockerfile_entrypoint:

 3.8 ENTRYPOINT

 --------------

@@ -312,6 +338,7 @@ this optional but default, you could use a CMD:

     CMD ["-l", "-"]

     ENTRYPOINT ["/usr/bin/wc"]

+.. _dockerfile_volume:

 3.9 VOLUME

 ----------

@@ -322,6 +349,8 @@ The ``VOLUME`` instruction will create a mount point with the specified name and

 as holding externally mounted volumes from native host or other containers. For more information/examples 

 and mounting instructions via docker client, refer to :ref:`volume_def` documentation. 

+.. _dockerfile_user:

+

 3.10 USER

 ---------

@@ -330,6 +359,8 @@ and mounting instructions via docker client, refer to :ref:`volume_def` document

 The ``USER`` instruction sets the username or UID to use when running

 the image.

+.. _dockerfile_workdir:

+

 3.11 WORKDIR

 ------------

@@ -338,6 +369,7 @@ the image.

 The ``WORKDIR`` instruction sets the working directory in which

 the command given by ``CMD`` is executed.

+.. _dockerfile_examples:

 4. Dockerfile Examples

 ======================