kotovalexarian-likes-github/moby--moby
1
0
Fork 0
mirror of https://github.com/moby/moby.git synced 2022-11-09 12:21:53 -05:00
Code Releases Activity

Cleans up docs/man/Dockerfile.5.md

Browse source 
Signed-off-by: Brian Goff <cpuguy83@gmail.com>
This commit is contained in:
Brian Goff 2015-02-09 19:57:52 -05:00
parent a98355561d
commit 14131b65c4
1 changed files with 234 additions and 165 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

395
docs/man/Dockerfile.5.md
View file

@ -6,12 +6,14 @@
Dockerfile - automate the steps of creating a Docker image Dockerfile - automate the steps of creating a Docker image
# INTRODUCTION # INTRODUCTION
The **Dockerfile** is a configuration file that automates the steps of creating 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 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 **Dockerfile** to automate the steps otherwise performed manually to create an
image. To build an image, create a file called **Dockerfile**. The image. To build an image, create a file called **Dockerfile**.
**Dockerfile** describes the steps taken to assemble the image. When the
**Dockerfile** has been created, call the **docker build** command, using the 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. path of directory that contains **Dockerfile** as the argument.
# SYNOPSIS # SYNOPSIS
@ -20,7 +22,7 @@ INSTRUCTION arguments
For example: For example:
FROM image FROM image
# DESCRIPTION # DESCRIPTION
@ -29,198 +31,265 @@ A Dockerfile is similar to a Makefile.
# USAGE # USAGE
**sudo docker build .** 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 .** -- Runs the steps and commits them, building a final image.
-- specifies a repository and tag at which to save the new image if the build The path to the source repository defines where to find the context of the
succeeds. The Docker daemon runs the steps one-by-one, committing the result build. The build is run by the Docker daemon, not the CLI. The whole
to a new image if necessary before finally outputting the ID of the new context must be transferred to the daemon. The Docker CLI reports
image. The Docker daemon automatically cleans up the context it is given. `"Sending build context to Docker daemon"` when the context is sent to the
daemon.
Docker re-uses intermediate images whenever possible. This significantly ```
accelerates the *docker build* process. 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 # FORMAT
**FROM image** `FROM image`
or
**FROM image:tag** `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 -- The **FROM** instruction sets the base image for subsequent instructions. A
valid image. It is easy to start by pulling an image from the public valid Dockerfile must have **FROM** as its first instruction. The image can be any
repositories. valid image. It is easy to start by pulling an image from the public
-- FROM must be he first non-comment instruction in Dockerfile. repositories.
-- 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 -- **FROM** must be the first non-comment instruction in Dockerfile.
each new FROM command.
-- If no tag is given to the FROM instruction, latest is assumed. If the used -- **FROM** may appear multiple times within a single Dockerfile in order to create
tag does not exist, an error is returned. 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** **MAINTAINER**
--The MAINTAINER instruction sets the Author field for the generated images. -- **MAINTAINER** sets the Author field for the generated images.
**RUN** **RUN**
--RUN has two forms: -- **RUN** has two forms:
**RUN <command>**
-- (the command is run in a shell - /bin/sh -c) ```
**RUN ["executable", "param1", "param2"]** # the command is run in a shell - /bin/sh -c
--The above is executable form. RUN <command>
--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 # Executable form
step in Dockerfile. RUN ["executable", "param1", "param2"]
--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 -- The **RUN** instruction executes any commands in a new layer on top of the current
it possible to RUN commands using a base image that does not contain /bin/sh. 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**
--CMD has three forms: -- **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 # Exececutable form
ENTRYPOINT) CMD ["executable", "param1", "param2"]`
**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 # Provide default arguments to ENTRYPOINT
the last CMD takes effect. CMD ["param1", "param2"]`
The main purpose of a CMD is to provide defaults for an executing container.
# 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 These defaults may include an executable, or they can omit the executable. If
they omit the executable, an ENTRYPOINT must be specified. they omit the executable, an **ENTRYPOINT** must be specified.
When used in the shell or exec formats, the CMD instruction sets the command to When used in the shell or exec formats, the **CMD** instruction sets the command to
be executed when running the image. be executed when running the image.
If you use the shell form of the CMD, the <command> executes in /bin/sh -c: 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 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 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: 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 FROM ubuntu
combination with CMD. CMD ["/usr/bin/wc","--help"]
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 -- To make the container run the same executable every time, use **ENTRYPOINT** in
executes nothing at build time, but specifies the intended command for the combination with **CMD**.
image. 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**
--**EXPOSE <port> [<port>...]** -- `EXPOSE <port> [<port>...]`
The **EXPOSE** instruction informs Docker that the container listens on the The **EXPOSE** instruction informs Docker that the container listens on the
specified network ports at runtime. Docker uses this information to specified network ports at runtime. Docker uses this information to
interconnect containers using links, and to set up port redirection on the host interconnect containers using links, and to set up port redirection on the host
system. system.
**ENV** **ENV**
--**ENV <key> <value>** -- `ENV <key> <value>`
The ENV instruction sets the environment variable <key> to The **ENV** instruction sets the environment variable <key> to
the value <value>. This value is passed to all future the value `<value>`. This value is passed to all future
RUN, ENTRYPOINT, and CMD instructions. This is RUN, **ENTRYPOINT**, and **CMD** instructions. This is
functionally equivalent to prefixing the command with **<key>=<value>**. The functionally equivalent to prefixing the command with `<key>=<value>`. The
environment variables that are set with ENV persist when a container is run 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 from the resulting image. Use `docker inspect` to inspect these values, and
change them using docker run **--env <key>=<value>.** change them using `docker run --env <key>=<value>`.
Note that setting Setting **ENV DEBIAN_FRONTEND noninteractive** may cause Note that setting "`ENV DEBIAN_FRONTEND noninteractive`" may cause
unintended consequences, because it will persist when the container is run unintended consequences, because it will persist when the container is run
interactively, as with the following command: **docker run -t -i image bash** interactively, as with the following command: `docker run -t -i image bash`
**ADD** **ADD**
--ADD has two forms: -- **ADD** has two forms:
**ADD <src>... <dest>**
**ADD ["<src>"... "<dest>"]** This form is required for paths containing ```
whitespace. ADD <src> <dest>
The ADD instruction copies new files, directories
or remote file URLs to the filesystem of the container at path <dest>. # Required for paths with whitespace
Multiple <src> resources may be specified but if they are files or directories ADD ["<src>", "<dest>"]
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. The **ADD** instruction copies new files, directories
All new files and directories are created with mode 0755 and with the uid or remote file URLs to the filesystem of the container at path `<dest>`.
and gid of 0. 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**
--COPY has two forms: -- **COPY** has two forms:
**COPY <src>... <dest>**
**COPY ["<src>"... "<dest>"]** This form is required for paths containing ```
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 # Required for paths with whitespace
the path to a file or directory relative to the source directory that is COPY ["<src>", "<dest>"]
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 The **COPY** instruction copies new files from `<src>` and
created with mode 0755 and with the uid and gid of 0. 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**
--**ENTRYPOINT** has two forms: ENTRYPOINT ["executable", "param1", "param2"] -- **ENTRYPOINT** has two forms:
(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, # executable form
the whole container runs as if it was only that executable. The ENTRYPOINT ENTRYPOINT ["executable", "param1", "param2"]`
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 # run command in a shell - /bin/sh -c
arguments to be passed to the entrypoint, for instance docker run <image> -d ENTRYPOINT command param1 param2
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 -- An **ENTRYPOINT** helps you configure a
arguments. Parameters specifies via CMD are overwritten by docker run container that can be run as an executable. When you specify an **ENTRYPOINT**,
arguments. Specify a plain string for the ENTRYPOINT, and it will execute in the whole container runs as if it was only that executable. The **ENTRYPOINT**
/bin/sh -c, like a CMD instruction: instruction adds an entry command that is not overwritten when arguments are
FROM ubuntu passed to docker run. This is different from the behavior of CMD. This allows
ENTRYPOINT wc -l - arguments to be passed to the entrypoint, for instance `docker run <image> -d`
This means that the Dockerfile's image always takes stdin as input (that's passes the -d argument to the **ENTRYPOINT**. Specify parameters either in the
what "-" means), and prints the number of lines (that's what "-l" means). To **ENTRYPOINT** JSON array (as in the preferred exec form above), or by using a **CMD**
make this optional but default, use a CMD: statement. Parameters in the **ENTRYPOINT** are not overwritten by the docker run
FROM ubuntu arguments. Parameters specifies via **CMD** are overwritten by docker run
CMD ["-l", "-"] arguments. Specify a plain string for the **ENTRYPOINT**, and it will execute in
ENTRYPOINT ["/usr/bin/wc"] `/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**
--**VOLUME ["/data"]** -- `VOLUME ["/data"]`
The VOLUME instruction creates a mount point with the specified name and marks 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 it as holding externally-mounted volumes from the native host or from other
containers. containers.
**USER** **USER**
-- **USER daemon** -- `USER daemon`
The USER instruction sets the username or UID that is used when running the The **USER** instruction sets the username or UID that is used when running the
image. image.
**WORKDIR** **WRKDIR**
-- **WORKDIR /path/to/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. The **WORKDIR** instruction sets the working directory for the **RUN**, **CMD**,
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: **ENTRYPOINT**, **COPY** and **ADD** Dockerfile commands that follow it. It can
**WORKDIR /a WORKDIR b WORKDIR c RUN pwd** be used multiple times in a single Dockerfile. Relative paths are defined
In the above example, the output of the **pwd** command is **a/b/c**. 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**
-- **ONBUILD [INSTRUCTION]** -- `ONBUILD [INSTRUCTION]`
The ONBUILD instruction adds a trigger instruction to the image, which is 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 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 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 if it had been inserted immediately after the **FROM** instruction in the
downstream Dockerfile. Any build instruction can be registered as a downstream Dockerfile. Any build instruction can be registered as a
trigger. This is useful if you are building an image to be 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 used as a base for building other images, for example an application build
environment or a daemon to be customized with a user-specific environment or a daemon to be customized with a user-specific
configuration. For example, if your image is a reusable python configuration. For example, if your image is a reusable python
application builder, it requires application source code to be application builder, it requires application source code to be
added in a particular directory, and might require a build script 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 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 you don't yet have access to the application source code, and it
is different for each application build. Providing is different for each application build.
application developers with a boilerplate Dockerfile to copy-paste
into their application is inefficient, error-prone, and -- Providing application developers with a boilerplate Dockerfile to copy-paste
difficult to update because it mixes with application-specific code. into their application is inefficient, error-prone, and
The solution is to use **ONBUILD** to register instructions in advance, to difficult to update because it mixes with application-specific code.
run later, during the next build stage. The solution is to use **ONBUILD** to register instructions in advance, to
run later, during the next build stage.
# HISTORY # HISTORY
*May 2014, Compiled by Zac Dover (zdover at redhat dot com) based on docker.com Dockerfile documentation. *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