Layers and the build cache

An image is built one Dockerfile instruction at a time, and each step’s result is kept as a layer. Build again and Docker checks each step against its cache: if the step and everything it depends on are unchanged, it reuses the old layer instead of running the step.

Two rules decide whether a step is a cache hit. Both come straight from Docker’s documentation:

• RUN is matched on its command text alone. The builder doesn’t look at what the command would download. Same text, cache hit.
• COPY is matched on a checksum of the files it copies. Edit one of those files and the checksum changes.

And the rule that makes ordering matter: once one step misses, every step after it is rebuilt. In the docs’ own words, “Once the cache is invalidated, all subsequent Dockerfile commands generate new images and the cache isn’t used.”

Watch the cascade

This project is a small Node.js app. The first Dockerfile copies everything, then installs dependencies. Edit src/server.js and watch which steps rebuild. Then switch to “Package files first” and do the same.

With everything copied first, a one-character code change changes the checksum of COPY . .. That invalidates RUN npm ci after it, so you reinstall every dependency on every edit. Copy just package.json and the lockfile first, install, and then copy the rest. Now a code change only misses at the second COPY, and the slow install stays cached. It only reruns when the dependency files themselves change, which is exactly when it should.

docker build -t cache-demo .        # first build: everything runs
docker build -t cache-demo .        # again: every step shows CACHED
echo "// edit" >> src/server.js
docker build -t cache-demo .        # which steps rebuilt?
docker history cache-demo           # one line per layer