Dockerfile Reference

3.1 FROM¶

FROM <image>

Or

FROM <image>:<tag>

The FROM instruction sets the Base Image 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 公共库.

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.

If no tag is given to the FROM instruction, latest is assumed. If the used tag does not exist, an error will be returned.

3.2 MAINTAINER¶

MAINTAINER <name>

The MAINTAINER instruction allows you to set the Author field of the generated images.

3.3 RUN¶

RUN has 2 forms:

• RUN <command> (the command is run in a shell - /bin/sh -c)
• RUN ["executable", "param1", "param2"] (exec form)

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.

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.

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.

3.4 CMD¶

CMD has three forms:

• CMD ["executable","param1","param2"] (like an exec, 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.

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.

When used in the shell or exec formats, 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.

If you use the shell form of the CMD, then the <command> will execute in /bin/sh -c:

FROM ubuntu
CMD echo "This is a test." | wc -

If you want to run your <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 format of CMD. Any additional parameters must be individually expressed as strings in the array:

FROM ubuntu
CMD ["/usr/bin/wc","--help"]

If you would like your container to run the same executable every time, then you should consider using ENTRYPOINT in combination with CMD. See 3.8 ENTRYPOINT.

If the user specifies arguments to docker run then they will override the default specified in CMD.

3.5 EXPOSE¶

EXPOSE <port> [<port>...]

The EXPOSE instruction exposes ports for use within links. This is functionally equivalent to running docker commit -run '{"PortSpecs": ["<port>", "<port2>"]}' outside the builder. Refer to 端口重定向 for detailed information.

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>

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>.

<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.

All new files and directories are created with mode 0755, uid and gid 0.

The copy obeys the following rules:

• The <src> path must be inside the context of the build; you cannot ADD ../something /something, because the first step of a docker build is to send the context directory (and subdirectories) to the docker daemon.

• If <src> is a URL and <dest> does not end with a trailing slash, then a file is downloaded from the URL and copied to <dest>.

• If <src> is a URL and <dest> does end with a trailing slash, then the filename is inferred from the URL and the file is downloaded to <dest>/<filename>. For instance, ADD http://example.com/foobar / would create the file /foobar. The URL must have a nontrivial path so that an appropriate filename can be discovered in this case (http://example.com will not work).

• If <src> is a directory, the entire directory is copied, including filesystem metadata.

• If <src> is a local tar archive in a recognized compression format (identity, gzip, bzip2 or xz) then it is unpacked as a directory. Resources 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.

• If <src> is any other kind of file, it is copied individually along with its metadata. In this case, if <dest> ends with a trailing slash /, it will be considered a directory and the contents of <src> will be written at <dest>/base(<src>).

• If <dest> does not end with a trailing slash, it will be considered a regular file and the contents of <src> will be written at <dest>.

• If <dest> doesn’t exist, it is created along with all missing directories in its path.

3.8 ENTRYPOINT¶

ENTRYPOINT has two forms:

• ENTRYPOINT ["executable", "param1", "param2"] (like an exec, preferred form)
• ENTRYPOINT command param1 param2 (as a shell)

There can only be one ENTRYPOINT in a Dockerfile. If you have more than one ENTRYPOINT, then only the last one in the Dockerfile will have an effect.

An ENTRYPOINT helps you to configure a container that you can run as an executable. That is, when you specify an ENTRYPOINT, then the whole container runs as if it was just that executable.

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.

You can specify parameters either in the ENTRYPOINT JSON array (as in “like an exec” above), or by using a CMD statement. Parameters in the ENTRYPOINT will not be overridden by the docker run arguments, but parameters specified via CMD will be overridden by docker run arguments.

Like a CMD, you can specify a plain string for the ENTRYPOINT and it will execute in /bin/sh -c:

FROM ubuntu
ENTRYPOINT wc -l -

For example, that Dockerfile’s image will always take stdin as input (“-”) and print the number of lines (“-l”). If you wanted to make this optional but default, you could use a CMD:

FROM ubuntu
CMD ["-l", "-"]
ENTRYPOINT ["/usr/bin/wc"]

3.9 VOLUME¶

VOLUME ["/data"]

The VOLUME instruction will create a mount point with the specified name and mark it as holding externally mounted volumes from native host or other containers. For more information/examples and mounting instructions via docker client, refer to 通过卷共享目录 documentation.

3.10 USER¶

USER daemon

The USER instruction sets the username or UID to use when running the image.

3.11 WORKDIR¶

WORKDIR /path/to/workdir

The WORKDIR instruction sets the working directory in which the command given by CMD is executed.

3.11 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.

Any build instruction can be registered as a trigger.

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 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 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 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 run later, during the next build stage.

Here’s how it works:

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.
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 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 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.

For example you might add something like this:

[...]
ONBUILD ADD . /app/src
ONBUILD RUN /usr/local/bin/python-build --dir /app/src
[...]