diff --git a/docs/sources/commandline/cli.rst b/docs/sources/commandline/cli.rst index d0a8d83c0c..8068b881ce 100644 --- a/docs/sources/commandline/cli.rst +++ b/docs/sources/commandline/cli.rst @@ -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 ` 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 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. +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 ` 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. -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. diff --git a/docs/sources/use/builder.rst b/docs/sources/use/builder.rst index b8dd95bad0..2035c276dd 100644 --- a/docs/sources/use/builder.rst +++ b/docs/sources/use/builder.rst @@ -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 ` 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": ["", ""]}'`` outside the builder. Refer to :ref:`port_redirection` for detailed information. +.. _dockerfile_env: + 3.6 ENV ------- @@ -203,6 +227,8 @@ with ``=`` 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 ```` 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 ======================