FWD » Deployment

When images are built off a base Docker image (the FWD images, and subsequently the customer Docker images) and "latest" tag is used, changes can be pulled into the layer above that may not be desired.

By tagging a base image with some sort of convention, the layer above can utilize that tag in it's FROM directive, and not pull in changes that may be pulled in if :latest is used.

🧩 How Docker Determines if a Step Needs to Be Re-Executed or a Layer Recreated¶

When you run docker build, Docker executes your Dockerfile instruction by instruction, and after each instruction it decides whether it can reuse a cached layer or needs to recreate it.

---

1. Layer Cache is Keyed by Build Context and Instruction¶

For every Dockerfile instruction (FROM, RUN, COPY, etc.), Docker calculates a cache key that includes:

• The instruction text itself
• The context of all previous layers (the image it’s building on)
• Any files referenced by that instruction (for example, from COPY or ADD)

If all of those inputs are byte-for-byte identical to a previous build, Docker reuses the cached layer.
If anything differs — even whitespace in the instruction or file modification — that step and all following steps are rebuilt.

---

2. How Each Instruction Affects Caching¶

FROM

• Reused if the base image digest is identical.
• If the tag points to a new digest → cache is invalidated.

RUN

• Cache key includes the command text and the filesystem snapshot from the previous step.
• Any change in command, arguments, or environment causes rebuild.

COPY / ADD

• Cache key includes the content hash of the copied files.
• If any file content changes → step and following steps are rebuilt. (Timestamps do not matter.)

ENV, ARG, WORKDIR, USER, EXPOSE, etc.

• Cache depends on instruction text. Any change → cache busts.

CMD, ENTRYPOINT, LABEL, etc.

• Affects only metadata; reused if text is identical.

---

3. Once a Step Changes, All Following Layers Rebuild¶

Cache reuse is linear.
As soon as one step changes, all later steps must be re-executed because the filesystem changed.

Example of good caching structure:

FROM ubuntu:24.04
RUN apt-get update && apt-get install -y curl
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .

If only your application source code changes, Docker will reuse all prior layers up to the final COPY . . step.

---

4. Build Arguments and Cache Busting¶

Build args (ARG) and environment variables (ENV) affect cache only if used in the same layer.

Example:

ARG BUILD_DATE
RUN echo $BUILD_DATE

Changing --build-arg BUILD_DATE forces that RUN step and all subsequent steps to rebuild.

---

5. Manual Cache Control¶

To force Docker to ignore cache:

docker build --no-cache .

Or add a dummy command that always changes:

RUN echo "Force rebuild $(date)" 

---

🔍 Quick Summary¶

Instruction Type	What Invalidates Cache
FROM	Base image digest changes
RUN	Command text or previous layer changes
COPY / ADD	File contents differ
ENV, ARG, etc.	Instruction text or value changes
Any Step After a Change	Always rebuilt

---

💡 Pro Tip: See Which Layers Were Reused¶

You can inspect caching behavior with:

docker build --progress=plain .

Each step will indicate whether it used cache:

# Using cache
#0  CACHED

or executed:

#0  RUN apt-get update && apt-get install ...