From 83f0f46b7c0475ae1da329cd97a8c0a67bdc2a6a Mon Sep 17 00:00:00 2001 From: Doug Davis Date: Mon, 29 Sep 2014 08:34:58 -0700 Subject: [PATCH] Add more info about when build cache is invalidated/used - Issue #3636 Plus some edits as suggested by @jamtur01 Closes #3636 Signed-off-by: Doug Davis --- .../articles/dockerfile_best-practices.md | 40 ++++++++++++++++++- docs/sources/reference/builder.md | 22 ++++++---- 2 files changed, 54 insertions(+), 8 deletions(-) diff --git a/docs/sources/articles/dockerfile_best-practices.md b/docs/sources/articles/dockerfile_best-practices.md index 520c3bfb43..51ff49ed36 100644 --- a/docs/sources/articles/dockerfile_best-practices.md +++ b/docs/sources/articles/dockerfile_best-practices.md @@ -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/) \ No newline at end of file +* [Guidelines for Creating Official +Repositories](https://docs.docker.com/docker-hub/official_repos/) diff --git a/docs/sources/reference/builder.md b/docs/sources/reference/builder.md index d3560de718..85961f5e1e 100644 --- a/docs/sources/reference/builder.md +++ b/docs/sources/reference/builder.md @@ -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 `` 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: