@@ -6,12 +6,14 @@

 Dockerfile - automate the steps of creating a Docker image

 # INTRODUCTION

+

 The **Dockerfile** is a configuration file that automates the steps of creating

 a Docker image. It is similar to a Makefile. Docker reads instructions from the

 **Dockerfile** to automate the steps otherwise performed manually to create an

-image. To build an image, create a file called **Dockerfile**.  The

-**Dockerfile** describes the steps taken to assemble the image. When the

-**Dockerfile** has been created, call the **docker build** command, using the

+image. To build an image, create a file called **Dockerfile**.

+

+The **Dockerfile** describes the steps taken to assemble the image. When the

+**Dockerfile** has been created, call the `docker build` command, using the

 path of directory that contains **Dockerfile** as the argument.

 # SYNOPSIS

@@ -20,7 +22,7 @@ INSTRUCTION arguments

 For example:

-FROM image

+  FROM image

 # DESCRIPTION

@@ -29,198 +31,265 @@ A Dockerfile is similar to a Makefile.

 # USAGE

-**sudo docker build .**

- -- runs the steps and commits them, building a final image

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

-    build. The build is run by the docker daemon, not the CLI. 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.

-    

-**sudo docker build -t repository/tag .**

- -- specifies a repository and tag at which to save the new image if the build 

-    succeeds. The Docker daemon runs the steps one-by-one, committing the result 

-    to a new image if necessary before finally outputting the ID of the new 

-    image. The Docker daemon automatically cleans up the context it is given.

-

-Docker re-uses intermediate images whenever possible. This significantly 

-accelerates the *docker build* process.

- 

+  sudo docker build .

+

+  -- Runs the steps and commits them, building a final image.

+  The path to the source repository defines where to find the context of the

+  build. The build is run by the Docker daemon, not the CLI. 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.

+

+  ```

+  sudo docker build -t repository/tag .

+  ```

+

+  -- specifies a repository and tag at which to save the new image if the build

+  succeeds. The Docker daemon runs the steps one-by-one, committing the result

+  to a new image if necessary, before finally outputting the ID of the new

+  image. The Docker daemon automatically cleans up the context it is given.

+

+  Docker re-uses intermediate images whenever possible. This significantly

+  accelerates the *docker build* process.

+

 # FORMAT

-**FROM image**

-or

-**FROM image:tag**

- -- The FROM instruction sets the base image for subsequent instructions. A

- valid Dockerfile must have FROM as its first instruction. The image can be any

- valid image. It is easy to start by pulling an image from the public

- repositories.

- -- FROM must be he first non-comment instruction in Dockerfile.

- -- FROM may appear multiple times within a single Dockerfile in order to create

- multiple images. 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 used

- tag does not exist, an error is returned.

+  `FROM image`

+

+  `FROM image:tag`

+

+  -- The **FROM** instruction sets the base image for subsequent instructions. A

+  valid Dockerfile must have **FROM** as its first instruction. The image can be any

+  valid image. It is easy to start by pulling an image from the public

+  repositories.

+

+  -- **FROM** must be the first non-comment instruction in Dockerfile.

+

+  -- **FROM** may appear multiple times within a single Dockerfile in order to create

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

+  used tag does not exist, an error is returned.

 **MAINTAINER**

- --The MAINTAINER instruction sets the Author field for the generated images.

+  -- **MAINTAINER** sets the Author field for the generated images.

 **RUN**

- --RUN has two forms:

- **RUN <command>**

- -- (the command is run in a shell - /bin/sh -c)

- **RUN ["executable", "param1", "param2"]**

- --The above is executable form.

- --The RUN instruction executes any commands in a new layer on top of the

- current image and commits the results. The committed image is used for the next

- step in 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 the history of an image. This is similar to source control.  The

- exec form makes it possible to avoid shell string munging. The exec form makes

- it possible to RUN commands using a base image that does not contain /bin/sh.

+  -- **RUN** has two forms:

+

+  ```

+  # the command is run in a shell - /bin/sh -c

+  RUN <command>

+

+  # Executable form

+  RUN ["executable", "param1", "param2"]

+  ```

+

+

+  -- The **RUN** instruction executes any commands in a new layer on top of the current

+  image and commits the results. The committed image is used for the next step in

+  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 the history of an image. This is similar to source control.  The

+  exec form makes it possible to avoid shell string munging. The exec form makes

+  it possible to **RUN** commands using a base image that does not contain `/bin/sh`.

 **CMD**

- --CMD has three forms:

-  **CMD ["executable", "param1", "param2"]** This is the preferred form, the

-  exec form.

-  **CMD ["param1", "param2"]** This command provides default parameters to

-  ENTRYPOINT)

-  **CMD command param1 param2** This command is run as a shell.

-  --There can be only one CMD in a Dockerfile. If more than one CMD is listed, only

-  the last CMD takes effect.

-  The main purpose of a CMD is to provide defaults for an executing container.

+  -- **CMD** has three forms:

+

+  ```

+  # Exececutable form

+  CMD ["executable", "param1", "param2"]`

+

+  # Provide default arguments to ENTRYPOINT

+  CMD ["param1", "param2"]`

+

+  # the command is run in a shell - /bin/sh -c

+  CMD command param1 param2

+  ```

+

+  -- There can be only one **CMD** in a Dockerfile. If more than one **CMD** is listed, only

+  the last **CMD** takes effect.

+  The main purpose of a **CMD** is to provide defaults for an executing container.

   These defaults may include an executable, or they can omit the executable. If

-  they omit the executable, an ENTRYPOINT must be specified.

-  When used in the shell or exec formats, the CMD instruction sets the command to

+  they omit the executable, an **ENTRYPOINT** must be specified.

+  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, the <command> executes in /bin/sh -c:

-  **FROM ubuntu**

-  **CMD echo "This is a test." | wc -**

-  If you run <command> without a shell, then you must express the command as a

+  If you use the shell form of the **CMD**, the `<command>` executes in `/bin/sh -c`:

+

+  ```

+  FROM ubuntu

+  CMD echo "This is a test." | wc -

+  ```

+

+  -- If you run **command** 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 form of CMD. All additional parameters must be individually expressed

+  preferred form of **CMD**. All additional parameters must be individually expressed

   as strings in the array:

-  **FROM ubuntu**

-  **CMD ["/usr/bin/wc","--help"]**

-  To make the container run the same executable every time, use ENTRYPOINT in

-  combination with CMD.

-  If the user specifies arguments to  docker run, the specified commands override

-  the default in CMD.

-  Do not confuse **RUN** with **CMD**. RUN runs a command and commits the result. CMD

-  executes nothing at build time, but specifies the intended command for the

-  image.

+

+  ```

+  FROM ubuntu

+  CMD ["/usr/bin/wc","--help"]

+  ```

+

+  -- To make the container run the same executable every time, use **ENTRYPOINT** in

+  combination with **CMD**. 

+  If the user specifies arguments to `docker run`, the specified commands

+  override the default in **CMD**.

+  Do not confuse **RUN** with **CMD**. **RUN** runs a command and commits the result.

+  **CMD** executes nothing at build time, but specifies the intended command for

+  the image.

 **EXPOSE**

- --**EXPOSE <port> [<port>...]**

- The **EXPOSE** instruction informs Docker that the container listens on the

- specified network ports at runtime. Docker uses this information to

- interconnect containers using links, and to set up port redirection on the host

- system.

+  -- `EXPOSE <port> [<port>...]`

+  The **EXPOSE** instruction informs Docker that the container listens on the

+  specified network ports at runtime. Docker uses this information to

+  interconnect containers using links, and to set up port redirection on the host

+  system.

 **ENV**

- --**ENV <key> <value>**

- The ENV instruction sets the environment variable <key> to

- the value <value>. This value is passed to all future 

- RUN, ENTRYPOINT, and CMD instructions. This is

- functionally equivalent to prefixing the command with **<key>=<value>**.  The

- environment variables that are set with ENV persist when a container is run

- from the resulting image. Use docker inspect to inspect these values, and

- change them using docker run **--env <key>=<value>.**

-

- Note that setting Setting **ENV DEBIAN_FRONTEND noninteractive** may cause

- unintended consequences, because it will persist when the container is run

- interactively, as with the following command: **docker run -t -i image bash**

+  -- `ENV <key> <value>`

+  The **ENV** instruction sets the environment variable <key> to

+  the value `<value>`. This value is passed to all future 

+  RUN, **ENTRYPOINT**, and **CMD** instructions. This is

+  functionally equivalent to prefixing the command with `<key>=<value>`.  The

+  environment variables that are set with **ENV** persist when a container is run

+  from the resulting image. Use `docker inspect` to inspect these values, and

+  change them using `docker run --env <key>=<value>`.

+

+  Note that setting "`ENV DEBIAN_FRONTEND noninteractive`" may cause

+  unintended consequences, because it will persist when the container is run

+  interactively, as with the following command: `docker run -t -i image bash`

 **ADD**

- --ADD has two forms:

- **ADD <src>... <dest>**

- **ADD ["<src>"... "<dest>"]** This form is required for paths containing

- whitespace.

- The ADD instruction copies new files, directories

- or remote file URLs to the filesystem of the container at path <dest>.

- Multiple <src> resources may be specified but if they are files or directories

- then they must be relative to the source directory that is being built

- (the context of the build). The <dest> is the absolute path, or path relative

- to `WORKDIR`, into which the source is copied inside the target container.

- All new files and directories are created with mode 0755 and with the uid 

- and gid of 0.

+  -- **ADD** has two forms:

+

+  ```

+  ADD <src> <dest>

+

+  # Required for paths with whitespace

+  ADD ["<src>", "<dest>"]

+  ```

+

+  The **ADD** instruction copies new files, directories

+  or remote file URLs to the filesystem of the container at path `<dest>`.

+  Multiple `<src>` resources may be specified but if they are files or directories

+  then they must be relative to the source directory that is being built

+  (the context of the build). The `<dest>` is the absolute path, or path relative

+  to **WORKDIR**, into which the source is copied inside the target container.

+  All new files and directories are created with mode 0755 and with the uid 

+  and gid of **0**.

 **COPY**

- --COPY has two forms:

- **COPY <src>... <dest>**

- **COPY ["<src>"... "<dest>"]** This form is required for paths containing

- whitespace.

- The COPY instruction copies new files from <src> and

- adds them to the filesystem of the container at path <dest>. The <src> must be

- the path to a file or directory relative to the source directory that is

- being built (the context of the build) or a remote file URL. The `<dest>` is an

- absolute path, or a path relative to `WORKDIR`, into which the source will

- be copied inside the target container. All new files and directories are

- created with mode 0755 and with the uid and gid of 0.

+  -- **COPY** has two forms:

+

+  ```

+  COPY <src> <dest>

+

+  # Required for paths with whitespace

+  COPY ["<src>", "<dest>"]

+  ```

+

+  The **COPY** instruction copies new files from `<src>` and

+  adds them to the filesystem of the container at path <dest>. The `<src>` must be

+  the path to a file or directory relative to the source directory that is

+  being built (the context of the build) or a remote file URL. The `<dest>` is an

+  absolute path, or a path relative to **WORKDIR**, into which the source will

+  be copied inside the target container. All new files and directories are

+  created with mode **0755** and with the uid and gid of **0**.

 **ENTRYPOINT**

- --**ENTRYPOINT** has two forms: ENTRYPOINT ["executable", "param1", "param2"]

- (This is like an exec, and is the preferred form.) ENTRYPOINT command param1

- param2 (This is running as a shell.) An ENTRYPOINT helps you configure a

- container that can be run as an executable. When you specify an ENTRYPOINT,

- the whole container runs as if it was only that executable.  The ENTRYPOINT

- instruction adds an entry command that is not overwritten when arguments are

- passed to docker run. This is different from the behavior of CMD. This allows

- arguments to be passed to the entrypoint, for instance docker run <image> -d

- passes the -d argument to the ENTRYPOINT.  Specify parameters either in the

- ENTRYPOINT JSON array (as in the preferred exec form above), or by using a CMD

- statement.  Parameters in the ENTRYPOINT are not overwritten by the docker run

- arguments.  Parameters specifies via CMD are overwritten by docker run

- arguments.  Specify a plain string for the ENTRYPOINT, and it will execute in

- /bin/sh -c, like a CMD instruction:

- FROM ubuntu

- ENTRYPOINT wc -l -

- This means that the Dockerfile's image always takes stdin as input (that's

- what "-" means), and prints the number of lines (that's what "-l" means). To

- make this optional but default, use a CMD:

- FROM ubuntu

- CMD ["-l", "-"]

- ENTRYPOINT ["/usr/bin/wc"]

+  -- **ENTRYPOINT** has two forms:

+

+  ```

+  # executable form

+  ENTRYPOINT ["executable", "param1", "param2"]`

+

+  # run command in a shell - /bin/sh -c

+  ENTRYPOINT command param1 param2

+  ```

+

+  -- An **ENTRYPOINT** helps you configure a

+  container that can be run as an executable. When you specify an **ENTRYPOINT**,

+  the whole container runs as if it was only that executable.  The **ENTRYPOINT**

+  instruction adds an entry command that is not overwritten when arguments are

+  passed to docker run. This is different from the behavior of CMD. This allows

+  arguments to be passed to the entrypoint, for instance `docker run <image> -d`

+  passes the -d argument to the **ENTRYPOINT**.  Specify parameters either in the

+  **ENTRYPOINT** JSON array (as in the preferred exec form above), or by using a **CMD**

+  statement.  Parameters in the **ENTRYPOINT** are not overwritten by the docker run

+  arguments.  Parameters specifies via **CMD** are overwritten by docker run

+  arguments.  Specify a plain string for the **ENTRYPOINT**, and it will execute in

+  `/bin/sh -c`, like a **CMD** instruction:

+

+  ```

+  FROM ubuntu

+  ENTRYPOINT wc -l -

+  ```

+

+  This means that the Dockerfile's image always takes stdin as input (that's

+  what "-" means), and prints the number of lines (that's what "-l" means). To

+  make this optional but default, use a **CMD**:

+

+  ```

+  FROM ubuntu

+  CMD ["-l", "-"]

+  ENTRYPOINT ["/usr/bin/wc"]

+  ```

 **VOLUME**

- --**VOLUME ["/data"]** 

- The VOLUME instruction creates a mount point with the specified name and marks

- it as holding externally-mounted volumes from the native host or from other

- containers.

+  -- `VOLUME ["/data"]`

+  The **VOLUME** instruction creates a mount point with the specified name and marks

+  it as holding externally-mounted volumes from the native host or from other

+  containers.

 **USER**

- -- **USER daemon**

- The USER instruction sets the username or UID that is used when running the

- image.

+  -- `USER daemon`

+  The **USER** instruction sets the username or UID that is used when running the

+  image.

+

+**WRKDIR**

+  -- `WORKDIR /path/to/workdir`

+  The **WORKDIR** instruction sets the working directory for the **RUN**, **CMD**,

+  **ENTRYPOINT**, **COPY** and **ADD** Dockerfile commands that follow it. It can

+  be used multiple times in a single Dockerfile. Relative paths are defined

+  relative to the path of the previous **WORKDIR** instruction. For example:

-**WORKDIR**

- -- **WORKDIR /path/to/workdir**

- The WORKDIR instruction sets the working directory for the **RUN**, **CMD**, **ENTRYPOINT**, **COPY** and **ADD** Dockerfile commands that follow it.

- It can be used multiple times in a single Dockerfile. Relative paths are defined relative to the path of the previous **WORKDIR** instruction. For example:

- **WORKDIR /a WORKDIR b WORKDIR c RUN pwd** 

- In the above example, the output of the **pwd** command is **a/b/c**.

+  ```

+  WORKDIR /a

+  WORKDIR b

+  WORKDIR c

+  RUN pwd

+  ```

+

+  In the above example, the output of the **pwd** command is **a/b/c**.

 **ONBUILD**

- -- **ONBUILD [INSTRUCTION]**

- The ONBUILD instruction adds a trigger instruction to the image, which is 

- executed at a later time, when the image is used as the base for another

- build. The trigger is 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.  This is useful if you are building an image to be

- used as a base for building other images, for example an application build

- environment or a daemon to be customized with a user-specific

- configuration.  For example, if your image is a reusable python

- application builder, it requires application source code to be

- added in a particular directory, and might require a build script

- to be called after that. You can't just call ADD and RUN now, because

- you don't yet have access to the application source code, and it 

- is different for each application build. Providing  

- application developers with a boilerplate Dockerfile to copy-paste

- into their application is inefficient, error-prone, and

- difficult to update because it mixes with application-specific code.

- The solution is to use **ONBUILD** to register instructions in advance, to

- run later, during the next build stage.  

+  -- `ONBUILD [INSTRUCTION]`

+  The **ONBUILD** instruction adds a trigger instruction to the image, which is 

+  executed at a later time, when the image is used as the base for another

+  build. The trigger is 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.  This is useful if you are building an image to be

+  used as a base for building other images, for example an application build

+  environment or a daemon to be customized with a user-specific

+  configuration.  For example, if your image is a reusable python

+  application builder, it requires application source code to be

+  added in a particular directory, and might require a build script

+  to be called after that. You can't just call **ADD** and **RUN** now, because

+  you don't yet have access to the application source code, and it

+  is different for each application build.

+

+  -- Providing application developers with a boilerplate Dockerfile to copy-paste

+  into their application is inefficient, error-prone, and

+  difficult to update because it mixes with application-specific code.

+  The solution is to use **ONBUILD** to register instructions in advance, to

+  run later, during the next build stage.

 # HISTORY

 *May 2014, Compiled by Zac Dover (zdover at redhat dot com) based on docker.com Dockerfile documentation.

+*Feb 2015, updated by Brian Goff (cpuguy83@gmail.com) for readability