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

Add more info about when build cache is invalidated/used - Issue #3636

Browse source 
Plus some edits as suggested by @jamtur01

Closes #3636

Signed-off-by: Doug Davis <dug@us.ibm.com>
This commit is contained in:
Doug Davis 2014-09-29 08:34:58 -07:00
parent d142b18aab
commit 83f0f46b7c
2 changed files with 54 additions and 8 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

40
docs/sources/articles/dockerfile_best-practices.md
View file

@ -75,6 +75,43 @@ Here’s an example from the [`buildpack-deps` image](https://github.com/docker-
mercurial \
subversion
### Build Cache
During the process of building an image Docker will step through the
instructions in your `Dockerfile` executing each in the order specified.
As each instruction is examined Docker will look for an existing image in its
cache that it can reuse, rather than creating a new (duplicate) image.
If you do not want to use the cache at all you can use the ` --no-cache=true`
option on the `docker build` command.
However, if you do let Docker use its cache then it is very important to
understand when it will, and will not, find a matching image. The basic rules
that Docker will follow are outlined below:
* Starting with a base image that is already in the cache, the next
instruction is compared against all child images derived from that base
image to see if one of them was built using the exact same instruction. If
not, the cache is invalidated.
* In most cases simply comparing the instruction in the `Dockerfile` with one
of the child images is sufficient. However, certain instructions require
a little more examination and explanation.
* In the case of the `ADD` and `COPY` instructions, the contents of the file(s)
being put into the image are examined. Specifically, a checksum is done
of the file(s) and then that checksum is used during the cache lookup.
If anything has changed in the file(s), including its metadata,
then the cache is invalidated.
* Aside from the `ADD` and `COPY` commands cache checking will not look at the
files in the container to determine a cache match. For example, when processing
a `RUN apt-get -y update` command the files updated in the container
will not be examined to determine if a cache hit exists. In that case just
the command string itself will be used to find a match.
Once the cache is invalidated, all subsequent `Dockerfile` commands will
generate new images and the cache will not be used.
## The `Dockerfile` instructions
This section contains specific recommendations for the correct usage of the
@ -336,4 +373,5 @@ These Official Repos have exemplary `Dockerfile`s:
* [Dockerfile Reference](https://docs.docker.com/reference/builder/#onbuild)
* [More about Base Images](https://docs.docker.com/articles/baseimages/)
* [More about Automated Builds](https://docs.docker.com/docker-hub/builds/)
* [Guidelines for Creating Official Repositories](https://docs.docker.com/docker-hub/official_repos/)
* [Guidelines for Creating Official
Repositories](https://docs.docker.com/docker-hub/official_repos/)

22
docs/sources/reference/builder.md
View file

@ -13,8 +13,8 @@ successively.
This page discusses the specifics of all the instructions you can use in your
`Dockerfile`. To further help you write a clear, readable, maintainable
`Dockerfile`, we've also written a [`Dockerfile` Best Practices guide](/articles/dockerfile_best-practices).
`Dockerfile`, we've also written a [`Dockerfile` Best Practices
guide](/articles/dockerfile_best-practices).
## Usage
@ -60,7 +60,9 @@ to be created - so `RUN cd /tmp` will not have any effect on the next
instructions.
Whenever possible, Docker will re-use the intermediate images,
accelerating `docker build` significantly (indicated by `Using cache`):
accelerating `docker build` significantly (indicated by `Using cache` -
see the [`Dockerfile` Best Practices
guide](/articles/dockerfile_best-practices/#build-cache) for more information):
$ sudo docker build -t SvenDowideit/ambassador .
Uploading context 10.24 kB
@ -192,10 +194,13 @@ commands using a base image that does not contain `/bin/sh`.
> you must use double-quotes (") around words not single-quotes (').
The cache for `RUN` instructions isn't invalidated automatically during
the next build. The cache for an instruction like `RUN apt-get
dist-upgrade -y` will be reused during the next build. The cache for
`RUN` instructions can be invalidated by using the `--no-cache` flag,
for example `docker build --no-cache`.
the next build. The cache for an instruction like
`RUN apt-get dist-upgrade -y` will be reused during the next build. The
cache for `RUN` instructions can be invalidated by using the `--no-cache`
flag, for example `docker build --no-cache`.
See the [`Dockerfile` Best Practices
guide](/articles/dockerfile_best-practices/#build-cache) for more information.
The cache for `RUN` instructions can be invalidated by `ADD` instructions. See
[below](#add) for details.
@ -325,6 +330,9 @@ have permissions of 600.
> The first encountered `ADD` instruction will invalidate the cache for all
> following instructions from the Dockerfile if the contents of `<src>` have
> changed. This includes invalidating the cache for `RUN` instructions.
> See the [`Dockerfile` Best Practices
guide](/articles/dockerfile_best-practices/#build-cache) for more information.
The copy obeys the following rules: