From 6c10e6fe817db30be29efd0ef249ee156246717d Mon Sep 17 00:00:00 2001 From: James Turnbull Date: Fri, 11 Jul 2014 22:28:36 -0400 Subject: [PATCH] General cleanup of the builder.md file Docker-DCO-1.1-Signed-off-by: James Turnbull (github: jamtur01) --- docs/sources/reference/builder.md | 150 +++++++++++++++--------------- 1 file changed, 75 insertions(+), 75 deletions(-) diff --git a/docs/sources/reference/builder.md b/docs/sources/reference/builder.md index 58854f5a..57ddb529 100644 --- a/docs/sources/reference/builder.md +++ b/docs/sources/reference/builder.md @@ -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 : 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 `` will execute in +If you use the *shell* form of the `CMD`, then the `` will execute in `/bin/sh -c`: FROM ubuntu @@ -207,7 +207,7 @@ If you use the *shell* form of the CMD, then the `` will execute in If you want to **run your** `` **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. `` 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 `` is a remote file URL, the destination will have permissions 600. +In the case where `` 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. +> 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. -> 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 `` is any other kind of file, it is copied individually along with its metadata. In this case, if `` ends with a trailing slash `/`, it @@ -342,7 +341,7 @@ being built (also called the *context* of the build). `` 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. +