From aa5671411b727d7142c289b5c1b473209aeaf630 Mon Sep 17 00:00:00 2001 From: Andy Rothfusz Date: Wed, 17 Jul 2013 18:56:40 -0700 Subject: [PATCH] Make dockerfile docs easier to find. Clean up formatting. --- docs/sources/use/builder.rst | 160 ++++++++++++++++++++--------------- 1 file changed, 94 insertions(+), 66 deletions(-) diff --git a/docs/sources/use/builder.rst b/docs/sources/use/builder.rst index ceda9c99dd..9ea8033b98 100644 --- a/docs/sources/use/builder.rst +++ b/docs/sources/use/builder.rst @@ -1,25 +1,27 @@ -:title: Docker Builder +:title: Dockerfile Builder :description: Docker Builder specifes a simple DSL which allows you to automate the steps you would normally manually take to create an image. :keywords: builder, docker, Docker Builder, automation, image creation -============== -Docker Builder -============== +================== +Dockerfile Builder +================== + +**Docker can act as a builder** and read instructions from a text +Dockerfile to automate the steps you would otherwise make manually to +create an image. Executing ``docker build`` will run your steps and +commit them along the way, giving you a final image. .. contents:: Table of Contents -Docker Builder specifes a simple DSL which allows you to automate the steps you -would normally manually take to create an image. Docker Build will run your -steps and commit them along the way, giving you a final image. - 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 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: +Then call ``docker build`` with the path of your source repository as +argument: ``docker build .`` @@ -36,136 +38,162 @@ before finally outputting the ID of your new image. The Dockerfile format is quite simple: - ``instruction arguments`` +:: + + # Comment + INSTRUCTION arguments The Instruction is not case-sensitive, however convention is for them to be UPPERCASE in order to distinguish them from arguments more easily. -Dockerfiles are evaluated in order, therefore the first instruction must be -`FROM` in order to specify the base image from which you are building. +Docker evaluates the instructions in a Dockerfile in order. **The first +instruction must be `FROM`** in order to specify the base image from +which you are building. -Docker will ignore lines in Dockerfiles prefixed with "`#`", so you may add -comment lines. A comment marker in the rest of the line will be treated as an -argument. +Docker will ignore **comment lines** *beginning* with ``#``. A comment +marker anywhere in the rest of the line will be treated as an argument. 3. Instructions =============== -Docker builder comes with a set of instructions, described below. +Here is the set of instructions you can use in a ``Dockerfile`` for +building images. 3.1 FROM -------- ``FROM `` -The `FROM` instruction sets the base image for subsequent instructions. As such, -a valid Dockerfile must have it as its first instruction. +The ``FROM`` instruction sets the :ref:`base_image_def` for subsequent +instructions. As such, a valid Dockerfile must have ``FROM`` as its +first instruction. -`FROM` can be included 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. +``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 before each new ``FROM`` command. 3.2 MAINTAINER -------------- ``MAINTAINER `` -The `MAINTAINER` instruction allows you to set the Author field of the generated -images. +The ``MAINTAINER`` instruction allows you to set the *Author* field of +the generated images. 3.3 RUN ------- ``RUN `` -The `RUN` instruction will execute any commands on the current image and commit -the results. The resulting committed image will be used for the next step in the -Dockerfile. +The ``RUN`` instruction will execute any commands on the current image +and commit the results. The resulting committed image will be 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 any point in an image's history, much like source control. +Layering ``RUN`` instructions and generating commits conforms to the +core concepts of Docker where commits are cheap and containers can be +created from any point in an image's history, much like source +control. 3.4 CMD ------- ``CMD `` -The `CMD` instruction sets the command to be executed when running the image. -This is functionally equivalent to running -`docker commit -run '{"Cmd": }'` outside the builder. +The ``CMD`` instruction sets the command to be executed when running +the image. This is functionally equivalent to running ``docker commit +-run '{"Cmd": }'`` outside the builder. -.. note:: - Don't confuse `RUN` with `CMD`. `RUN` actually runs a command and commits - the result; `CMD` does not execute anything at build time, but specifies the - intended command for the image. +.. note:: + Don't confuse `RUN` with `CMD`. `RUN` actually runs a + command and commits the result; `CMD` does not execute anything at + build time, but specifies the intended command for the image. 3.5 EXPOSE ---------- ``EXPOSE [...]`` -The `EXPOSE` instruction sets ports to be publicly exposed when running the -image. This is functionally equivalent to running -`docker commit -run '{"PortSpecs": ["", ""]}'` outside the builder. +The ``EXPOSE`` instruction sets ports to be publicly exposed when +running the image. This is functionally equivalent to running ``docker +commit -run '{"PortSpecs": ["", ""]}'`` outside the +builder. 3.6 ENV ------- ``ENV `` -The `ENV` instruction sets the environment variable `` to the value -``. This value will be passed to all future ``RUN`` instructions. This is -functionally equivalent to prefixing the command with `=` +The ``ENV`` instruction sets the environment variable ```` to the +value ````. This value will be passed to all future ``RUN`` +instructions. This is functionally equivalent to prefixing the command +with ``=`` -.. note:: - The environment variables will persist when a container is run from the resulting image. +.. note:: + The environment variables will persist when a container is run + from the resulting image. 3.7 ADD ------- ``ADD `` -The `ADD` instruction will copy new files from and add them to the container's filesystem at path ``. +The ``ADD`` instruction will copy new files from and add them to +the container's filesystem at path ````. -`` must be the path to a file or directory relative to the source directory being built (also called the -context of the build) or a remote file URL. +```` must be the path to a file or directory relative to the +source directory being built (also called the *context* of the build) or +a remote file URL. -`` is the path at which the source will be copied in the destination container. +```` is the path at which the source will be copied in the +destination container. The copy obeys the following rules: -If `` is a directory, the entire directory is copied, including filesystem metadata. +* If ```` is a directory, the entire directory is copied, + including filesystem metadata. +* If ````` is a tar archive in a recognized compression format + (identity, gzip, bzip2 or xz), it is unpacked as a directory. -If `` is a tar archive in a recognized compression format (identity, gzip, bzip2 or xz), it -is unpacked as a directory. + When a directory is copied or unpacked, it has the same behavior as + ``tar -x``: the result is the union of -When a directory is copied or unpacked, it has the same behavior as 'tar -x': the result is the union of -a) whatever existed at the destination path and b) the contents of the source tree, with conflicts resolved -in favor of b on a file-by-file basis. + 1. whatever existed at the destination path and + 2. the contents of the source tree, -If `` is any other kind of file, it is copied individually along with its metadata. In this case, -if `` ends with a trailing slash '/', it will be considered a directory and the contents of `` -will be written at `/base()`. -If `` does not end with a trailing slash, it will be considered a regular file and the contents -of `` will be written at ``. + with conflicts resolved in favor of 2) on a file-by-file basis. -If `` doesn't exist, it is created along with all missing directories in its path. All new -files and directories are created with mode 0700, uid and gid 0. +* If ```` is any other kind of file, it is copied individually + along with its metadata. In this case, if ```` ends with a + trailing slash ``/``, it will be considered a directory and the + contents of ```` will be written at ``/base()``. +* If ```` does not end with a trailing slash, it will be + considered a regular file and the contents of ```` will be + written at ````. +* If ```` doesn't exist, it is created along with all missing + directories in its path. All new files and directories are created + with mode 0700, uid and gid 0. 3.8 ENTRYPOINT ------------- ``ENTRYPOINT /bin/echo`` -The `ENTRYPOINT` instruction adds an entry command that will not be overwritten when arguments are passed to docker run, unlike the behavior of `CMD`. This allows arguments to be passed to the entrypoint. i.e. `docker run -d` will pass the "-d" argument to the entrypoint. +The ``ENTRYPOINT`` instruction adds an entry command that will not be +overwritten when arguments are passed to docker run, unlike the +behavior of ``CMD``. This allows arguments to be passed to the +entrypoint. i.e. ``docker run -d`` will pass the "-d" argument +to the entrypoint. 3.9 VOLUME ---------- ``VOLUME ["/data"]`` -The `VOLUME` instruction will add one or more new volumes to any container created from the image. +The ``VOLUME`` instruction will add one or more new volumes to any +container created from the image. 4. Dockerfile Examples ======================