mirror of
https://github.com/moby/moby.git
synced 2022-11-09 12:21:53 -05:00
Make dockerfile docs easier to find. Clean up formatting.
This commit is contained in:
Andy Rothfusz
parent
f8dfd0aa5e
commit
aa5671411b
1 changed files with 94 additions and 66 deletions
|
|
@ -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 <image>``
|
||||
|
||||
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 <name>``
|
||||
|
||||
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 <command>``
|
||||
|
||||
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 <command>``
|
||||
|
||||
The `CMD` instruction sets the command to be executed when running the image.
|
||||
This is functionally equivalent to running
|
||||
`docker commit -run '{"Cmd": <command>}'` 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": <command>}'`` 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 <port> [<port>...]``
|
||||
|
||||
The `EXPOSE` instruction sets ports to be publicly exposed when running the
|
||||
image. This is functionally equivalent to running
|
||||
`docker commit -run '{"PortSpecs": ["<port>", "<port2>"]}'` 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": ["<port>", "<port2>"]}'`` outside the
|
||||
builder.
|
||||
|
||||
3.6 ENV
|
||||
-------
|
||||
|
||||
``ENV <key> <value>``
|
||||
|
||||
The `ENV` instruction sets the environment variable `<key>` to the value
|
||||
`<value>`. This value will be passed to all future ``RUN`` instructions. This is
|
||||
functionally equivalent to prefixing the command with `<key>=<value>`
|
||||
The ``ENV`` instruction sets the environment variable ``<key>`` to the
|
||||
value ``<value>``. This value will be passed to all future ``RUN``
|
||||
instructions. This is functionally equivalent to prefixing the command
|
||||
with ``<key>=<value>``
|
||||
|
||||
.. 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 <src> <dest>``
|
||||
|
||||
The `ADD` instruction will copy new files from <src> and add them to the container's filesystem at path `<dest>`.
|
||||
The ``ADD`` instruction will copy new files from <src> and add them to
|
||||
the container's filesystem at path ``<dest>``.
|
||||
|
||||
`<src>` 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.
|
||||
``<src>`` 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.
|
||||
|
||||
`<dest>` is the path at which the source will be copied in the destination container.
|
||||
``<dest>`` is the path at which the source will be copied in the
|
||||
destination container.
|
||||
|
||||
The copy obeys the following rules:
|
||||
|
||||
If `<src>` is a directory, the entire directory is copied, including filesystem metadata.
|
||||
* If ``<src>`` is a directory, the entire directory is copied,
|
||||
including filesystem metadata.
|
||||
* If ``<src>``` is a tar archive in a recognized compression format
|
||||
(identity, gzip, bzip2 or xz), it is unpacked as a directory.
|
||||
|
||||
If `<src>` 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 `<src>` is any other kind of file, it is copied individually along with its metadata. In this case,
|
||||
if `<dst>` ends with a trailing slash '/', it will be considered a directory and the contents of `<src>`
|
||||
will be written at `<dst>/base(<src>)`.
|
||||
If `<dst>` does not end with a trailing slash, it will be considered a regular file and the contents
|
||||
of `<src>` will be written at `<dst>`.
|
||||
with conflicts resolved in favor of 2) on a file-by-file basis.
|
||||
|
||||
If `<dest>` 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 ``<src>`` is any other kind of file, it is copied individually
|
||||
along with its metadata. In this case, if ``<dst>`` ends with a
|
||||
trailing slash ``/``, it will be considered a directory and the
|
||||
contents of ``<src>`` will be written at ``<dst>/base(<src>)``.
|
||||
* If ``<dst>`` does not end with a trailing slash, it will be
|
||||
considered a regular file and the contents of ``<src>`` will be
|
||||
written at ``<dst>``.
|
||||
* If ``<dest>`` 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 <image> -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 <image> -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
|
||||
======================
|
||||
|
|
|
|||
Loading…
Reference in a new issue