Docker can build images automatically by reading the instructions from a
`Dockerfile`, a text file that contains all the commands, in order, needed to
build a given image. `Dockerfile`s adhere to a specific format and use a
specific set of instructions. You can learn the basics on the
[Dockerfile Reference](https://docs.docker.com/reference/builder/) page. If
you’re new to writing `Dockerfile`s, you should start there.
This document covers the best practices and methods recommended by Docker,
Inc., for creating easy-to-use, effective `Dockerfile`s. We strongly suggest
you follow these recommendations (in fact, if you’re creating an Official
Image, you *must* adhere to these practices).
You can see many of these practices and recommendations in action in the [buildpack-deps `Dockerfile`](https://github.com/docker-library/buildpack-deps/blob/master/jessie/Dockerfile).
> Note: for more detailed explanations of any of the Dockerfile commands
>mentioned here, visit the [Dockerfile Reference](https://docs.docker.com/reference/builder/) page.
## General Guidelines and Recommendations
### Containers should be ephemeral
The container produced by the image your `Dockerfile` defines should be as
ephemeral as possible. “Ephemeral” here means that it can be stopped and
destroyed and a new one built and put in place with an absolute minimum of
set-up and configuration.
### Use a [`.dockerignore` file](https://docs.docker.com/reference/builder/#the-dockerignore-file)
For faster uploading and efficiency, you should make use of a `.dockerignore`
file to exclude files or directories from the build context. For example, unless
`.git` is needed by your build process or scripts, you should add it to
`.dockerignore`, which can save many megabytes worth of upload time.
### Avoid installing unnecessary packages
You should avoid installing extra or unnecessary packages just because they
might be “nice to have.” For example, you don’t need to include a text editor
in a database image.
### Run only one process per container
In almost all cases, you should only run a single process in a single
container. Decoupling applications into multiple containers makes it much
easier to scale horizontally and reuse containers. If that service depends on
another service, make use of [container linking](https://docs.docker.com/userguide/dockerlinks/).
### Minimize the number of layers
You need to find the balance between readability (and thus long-term
maintainability) of the `Dockerfile` and minimizing the number of layers it
uses. Be strategic and cautious about the number of layers you use.
### Sort multi-line arguments
Whenever possible, ease later changes by sorting multi-line arguments
alphanumerically. This will help you avoid duplication of packages and make the
list much easier to update. This also makes PRs a lot easier to read and
review. Adding a space before a backslash (`\`) helps as well.
Here’s an example from the [`buildpack-deps` image](https://github.com/docker-library/buildpack-deps):
RUN apt-get update && apt-get install -y \
bzr \
cvs \
git \
mercurial \
subversion
## The `Dockerfile` instructions
This section contains specific recommendations for the correct usage of the
* Avoid `RUN apt-get upgrade` or `dist-upgrade`, since many of the “essential” packages from the base images will fail to upgrade inside an unprivileged container. If a base package is out of date, you should contact its maintainers. If you know there’s a particular package, `foo`, that needs to be updated, use `apt-get install -y foo` and it will update automatically.
Because image size matters, using `ADD` to fetch packages from remote URLs is
strongly discouraged; you should use `curl` or `wget` instead. That way you can, where possible, delete the files you no longer need after they’ve been
extracted without having to add another layer in your image. For example, you