4.1.1.2 Dockerfile Filesystem Changes

Dockerfile filesystem changes are the modifications a RUN, COPY, or ADD instruction makes to an image's filesystem during a build, each one producing a new, discrete layer reflecting exactly what changed relative to the state before that instruction ran.

RUN: Executing Commands That Modify the Filesystem

RUN executes a command inside a temporary container based on the current build state, and any filesystem changes that command makes — installed packages, generated files, modified configuration — are captured as the resulting layer.

RUN apt-get update && apt-get install -y curl

This instruction's layer reflects exactly the filesystem changes that resulted from running this specific command, nothing more.

COPY: Bringing Files From the Build Context

COPY copies files or directories from the build context (the files available to the build, typically the current directory) into the image's filesystem at a specified destination.

COPY requirements.txt /app/requirements.txt
COPY . /app

Each COPY instruction's resulting layer contains exactly the files it copied, at exactly the destination path specified.

ADD: A More Capable but Less Predictable Alternative

ADD behaves similarly to COPY but with additional capabilities — automatically extracting compressed archives, and fetching files directly from a URL — capabilities that introduce behavior some teams prefer to avoid in favor of COPY's simpler, more predictable behavior.

ADD https://example.com/archive.tar.gz /app/

Using COPY for straightforward file copying, reserving ADD only for cases that genuinely need its additional capabilities, is a common convention to avoid the implicit behavior surprising someone reading the Dockerfile later.

Verifying What a Filesystem-Changing Instruction Actually Produced

After a build, the resulting layer from any filesystem-changing instruction can be inspected to confirm it produced exactly the intended change.

docker history --no-trunc myapp:1.0

Why Understanding These Instructions Matters

RUN, COPY, and ADD are the three instructions responsible for essentially all of an image's actual filesystem content beyond its base image, making a precise understanding of how each one behaves essential to writing a Dockerfile that produces exactly the intended result, without unnecessary size or unexpected content.