From 14131b65c41ee9f562c3311e533e0f7d9c9de97b Mon Sep 17 00:00:00 2001 From: Brian Goff Date: Mon, 9 Feb 2015 19:57:52 -0500 Subject: [PATCH] Cleans up docs/man/Dockerfile.5.md Signed-off-by: Brian Goff --- docs/man/Dockerfile.5.md | 399 +++++++++++++++++++++++---------------- 1 file changed, 234 insertions(+), 165 deletions(-) diff --git a/docs/man/Dockerfile.5.md b/docs/man/Dockerfile.5.md index dd1d8b2ce1..42d0385093 100644 --- a/docs/man/Dockerfile.5.md +++ b/docs/man/Dockerfile.5.md @@ -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. + 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. -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 ** - -- (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 + + # 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 executes in /bin/sh -c: - **FROM ubuntu** - **CMD echo "This is a test." | wc -** - If you run without a shell, then you must express the command as a + If you use the shell form of the **CMD**, the `` 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 [...]** - 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 [...]` + 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 ** - The ENV instruction sets the environment variable to - the value . This value is passed to all future - RUN, ENTRYPOINT, and CMD instructions. This is - functionally equivalent to prefixing the command with **=**. 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 =.** + -- `ENV ` + The **ENV** instruction sets the environment variable to + the value ``. This value is passed to all future + RUN, **ENTRYPOINT**, and **CMD** instructions. This is + functionally equivalent to prefixing the command with `=`. 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 =`. - 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** + 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 ... ** - **ADD [""... ""]** 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 . - Multiple 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 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 + + # Required for paths with whitespace + ADD ["", ""] + ``` + + The **ADD** instruction copies new files, directories + or remote file URLs to the filesystem of the container at path ``. + Multiple `` 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 `` 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 ... ** - **COPY [""... ""]** This form is required for paths containing - whitespace. - The COPY instruction copies new files from and - adds them to the filesystem of the container at path . The 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 `` 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 + + # Required for paths with whitespace + COPY ["", ""] + ``` + + The **COPY** instruction copies new files from `` and + adds them to the filesystem of the container at path . The `` 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 `` 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 -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 -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. -**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**. +**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 /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