Docker Build Context Reference

The most common build context source is a local directory. Docker will use all files in the specified directory as the build context:

docker build .

In this example, . refers to the current directory.

You can specify a Git repository URL as the build context. Docker will clone the repository and use it as the build context:

docker build https://github.com/user/repo.git#branch:subdirectory

This command clones the specified Git repository, checks out the specified branch, and uses the subdirectory as the build context.

Docker can use a tar archive as the build context. This can be provided either remotely via HTTP or as a local file:

docker build http://server/context.tar.gz
docker build - < context.tar.gz

You can pass a Dockerfile directly via STDIN by using the - (hyphen) character as the build context:

docker build - < Dockerfile
echo -e 'FROM alpine\nRUN echo "Hello, World!"' | docker build -

When using STDIN as the build context, you can't use ADD or COPY commands in your Dockerfile, as there are no files available in the context.

The most important tool for controlling the build context is the .dockerignore file. This file uses patterns similar to .gitignore to specify which files and directories should be excluded from the build context:

# Example .dockerignore file
node_modules
npm-debug.log
.git
.gitignore
*.md
*.log
dist
coverage
.env
.DS_Store

Using .dockerignore effectively can significantly reduce the size of the build context, leading to faster builds and better layer caching.

You can specify a subdirectory of your project as the build context to limit what files are included:

docker build ./app

This command uses only the ./app directory as the build context, excluding other directories in your project.

You can place your Dockerfile outside the build context and reference it with the -f flag:

docker build -f ../Dockerfiles/Dockerfile.prod ./app

This command uses ./app as the build context but uses a Dockerfile located at ../Dockerfiles/Dockerfile.prod.

Docker BuildKit supports external resources in Dockerfiles, allowing you to reference resources outside the build context:

# Syntax must be set for BuildKit features
# syntax=docker/dockerfile:1.4

FROM alpine
# Copy from HTTP source directly, no need to include in build context
ADD --checksum=sha256:36b2b2a4802d52d3f527471e8a66d73daed88962b1e0f937ec48a2b567bcc9c0 \
    https://example.com/files/myfile.tar.gz /usr/local/
RUN tar -xzf /usr/local/myfile.tar.gz -C /usr/local/

This feature requires BuildKit to be enabled and allows you to reference resources that don't need to be included in the build context.

In multi-stage builds, the build context is the same for all stages, but you can selectively copy files between stages:

FROM node:18 AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM nginx:alpine
# Only copy what's needed from the builder stage
COPY --from=builder /app/dist /usr/share/nginx/html

This approach allows you to have a large build context for the build stage but keep the final image small by copying only the necessary files.

BuildKit allows you to mount SSH agents and secrets during the build, which can be useful for accessing private repositories or credentials without including them in the build context:

# Build with SSH agent forwarding
DOCKER_BUILDKIT=1 docker build --ssh default=$SSH_AUTH_SOCK .

# In Dockerfile
# syntax=docker/dockerfile:1.4
FROM alpine
RUN --mount=type=ssh git clone [email protected]:private/repo.git

This feature allows you to access protected resources during the build without adding sensitive information to the build context or the final image.

You can combine different sources for the Dockerfile and build context:

# Use a Dockerfile from Git but provide context via STDIN
docker build -f https://github.com/user/repo/raw/branch/Dockerfile - < context.tar.gz

This approach allows for flexible build configurations, especially in CI/CD environments.

If your build is slow because of a large build context, you can investigate which files are being included:

# Check the size of your potential build context
du -sh .

# Find large files in your directory
find . -type f -size +10M | sort -rh

# Test what .dockerignore would exclude
find . -type f -not -path "*/\.*" | grep -v -f .dockerignore

Use this information to refine your .dockerignore file or restructure your project.

If files referenced in your Dockerfile can't be found during the build:

1. Check that the files exist in the build context, not just on your local filesystem.
2. Ensure the files aren't being excluded by .dockerignore.
3. Verify that the paths in COPY or ADD instructions are correct relative to the build context, not the Dockerfile location.

Path resolution in Dockerfiles can be confusing, especially when using external Dockerfiles:

# The context is ./app, but the Dockerfile is in ../Dockerfiles
docker build -f ../Dockerfiles/Dockerfile.prod ./app

In this example, paths in COPY/ADD instructions must be relative to ./app (the context), not to ../Dockerfiles (where the Dockerfile is located).