5.1 Build Context

The build context is the set of files, rooted at a specified directory, that is sent to the Docker daemon at the start of a build, made available to instructions like COPY and ADD that need to bring files from outside the image into it.

Specifying the Build Context

The build context is specified as the final positional argument to docker build, typically a directory path.

docker build -t myapp .

Here, the current directory becomes the build context — every file within it (subject to .dockerignore exclusions) becomes available to the build.

Why the Entire Context Is Transferred Upfront

Before any instruction executes, the entire build context is packaged and sent to the daemon, which is why a build context containing unnecessarily large files or directories can noticeably slow down the very start of a build, even before any actual build instructions run.

docker build -t myapp . 

Sending build context to Docker daemon  1.2GB

This message, printed near the start of a build, reveals exactly how large the transferred context actually was — a surprisingly large number here is often a sign that unnecessary files are being included.

Only Context Files Can Be Used by COPY and ADD

COPY and ADD instructions can only reference files within the build context; a path outside of it, even if it exists on the host filesystem, is simply not accessible to the build.

COPY ../shared-config.yaml ./

This instruction fails, since ../shared-config.yaml lies outside the build context directory and therefore was never transferred to the daemon in the first place.

Reducing the Build Context With .dockerignore

A .dockerignore file excludes specified patterns from what gets included in the transferred build context, directly addressing both unnecessary transfer time and unintended file inclusion.

node_modules
.git
*.log

Why Understanding the Build Context Matters

Recognizing exactly what the build context includes, and why only files within it are accessible to build instructions, helps avoid both unnecessarily slow builds and confusing "file not found" errors caused by referencing a path that was never actually part of the transferred context.