4.1.2.5 Build Context Docs

Build context docs explain what the Docker build context actually is — the set of files sent to the daemon when a build starts — and why understanding and documenting its boundaries matters for both build performance and avoiding accidentally including unintended files in an image.

What the Build Context Includes

The build context is, by default, everything in the directory specified as the final argument to docker build, all of which is sent to the daemon before the build even begins, regardless of whether every file is actually used by a COPY or ADD instruction.

docker build -t myapp .

The . here means the entire current directory, including its full contents, is sent as the build context.

Why an Overly Large Context Matters

A build context containing large, unnecessary files — log files, local virtual environments, build artifacts from previous builds — slows down every build, since all of it must be transferred to the daemon before the build can proceed, even if none of those files are ever referenced.

du -sh .

Checking the size of the directory that will become the build context is a quick way to spot unexpectedly large, unnecessary content before it becomes a recurring build performance problem.

Excluding Files With .dockerignore

A .dockerignore file lets specific files and directories be excluded from the build context entirely, both speeding up builds and preventing unintended files from accidentally ending up inside the image through an overly broad COPY instruction.

.git
node_modules
*.log
.env

Documenting Why Specific Exclusions Exist

Some exclusions are not obvious at a glance — excluding .env specifically to avoid accidentally baking secrets into an image, for instance — and benefit from a brief comment explaining the reasoning, so a future maintainer does not inadvertently remove a security-relevant exclusion.

# Never include local secrets in the build context
.env

Why Build Context Documentation Matters

Clearly understanding and documenting what is and is not included in the build context prevents both unnecessary build slowdowns from oversized contexts and security risks from sensitive files being unintentionally copied into an image.