Docker is a powerful tool that can be used to build and deploy applications. However, if you’re not familiar with Docker build contexts, you may find it difficult to understand how it works. In this article, we’ll explore the different Docker build contexts and why you should use them. A Docker build context is a way of describing a set of instructions that will be executed when building an application from scratch. A build context can be created using the docker-compose up command or by using the –build-context flag when building an image. There are three main types of Docker build contexts: local, remote, and network. A local build context is used within your own machine and is associated with a specific directory. A remote build context is used on a remote machine and is associated with a specific network interface. A network build context builds applications across multiple machines on a network and can be used to create images that are ready for deployment on multiple platforms. A local Build Context A local build context is used within your own machine and is associated with a specific directory. To create a local Build Context, use the docker-compose up command or use the –build-context flag when building an image: $ docker-compose up -d mydir myapp This will create a mydir/myapp folder in your current working directory and add it to your docker-compose file: [mydir] # Add this line to your docker-compose file [myapp] # Use this line to define the environment variables for your app [network] # Use this line to define the network interface [local] # Use this line to define where your app will run
The Docker build context refers to the files and directories that will be available to the Docker engine when you run docker build. Anything not included in the build context won’t be accessible to commands in your Dockerfile.
You should audit your use of docker build to keep your build contexts small. Accidentally including unnecessary files can result in an excessively large build context, which will lead to longer builds.
What Is the Build Context?
Here’s a simple docker build command:
This builds a Docker image using the Dockerfile found in your working directory. The resulting image will be tagged as my-image:latest, although this detail isn’t important to this tutorial.
Within your Dockerfile, you’ll likely use COPY to add files and folders into your image:
This example copies the index.html file and css directory into your container. At first glance, it looks like the COPY statement simply references a path that’s resolved relative to your working directory.
This isn’t quite the case. COPY can only access resources available in the build context. In this example, the build context is the working directory, so the files and folders within it are available. By default, Docker uses the contents of the directory passed to docker build as the build context.
Why Is the Build Context Used?
The build context is important because the Docker CLI and Docker Engine might not be running on the same machine. When you run docker build, the CLI sends the files and folders to build to the Docker engine. This set of files and folders becomes the build context.
Furthermore, not every build context is as straightforward as reusing your working directory. Docker also supports Git repository URLs as the path given to docker build. In this case, the build context becomes the content of the specified repository.
The build context’s default “include all” behavior is fine for many small repositories. Problems become apparent once you add files to your working directory that aren’t used by your Dockerfile. Resources such as prebuilt binaries, documentation files, and dependency libraries will be included in the build context even though they’re redundant.
Including too many assets in the build context can become a performance drain. You’re needlessly copying files that will never be used. The slowdown will be particularly evident if you’re connected to a remote Docker daemon or if you’re using a slow mechanical hard drive. You’ll see “sending build context to Docker daemon” in your shell while the copy is completed.
Docker does try to minimize redundant copying on its own. The BuildKit build backend—used since Docker 18.09—added support for incremental transfers. This means that Docker will usually only need to copy files added or changed since your last build. It’ll still copy the whole lot on the first build.
Excluding Resources from the Build Context
To resolve wasteful copying for good, you must tell Docker what it can omit from the build context. Let’s start by creating a Dockerfile:
This simple Dockerfile could be used by an application written in Node.js. Node.js programs use npm as their package manager. Packages are installed to a node_modules folder. When you run npm install locally, during development, the packages will be downloaded to the node_modules folder in your working directory.
The Dockerfile runs npm install itself to acquire the dependencies. This ensures that the image is fully self-contained. There’s no need to copy in the local node_modules folder, as it’s not used by the Dockerfile.
Despite this, Docker will still include the node_modules folder in the default build context. To exclude it, create a .dockerignore file in your working directory. This file has a similar syntax to .gitignore.
Any paths listed in .dockerignore will be excluded from the build context. You should make sure that .dockerignore is kept updated with changes to your project’s filesystem structure. You can substantially reduce Docker build context copying time by checking that only relevant paths (those actually used by your Dockerfile) are present in the build context.
In the case of our example, the node_modules folder could include thousands of files if we have a lot of dependencies in our project. Copying them to the Docker daemon as part of the build context could take several seconds and would be a wasteful operation. The Dockerfile completely ignores them, fetching its own dependencies via npm install instead.
Other Build Context Issues
Not using .dockerignore can introduce other issues, too. A Dockerfile with this line is particularly problematic:
This will copy everything in your working directory. This might seem like a good idea until you realize that your .git history and any secret files will also end up within your container.
Copying an unfiltered build context also prevents Docker layer caching from working effectively. As something in your working directory will probably change between builds, Docker would need to run the COPY instruction every time. This would create a new layer—and new layers for any subsequent instructions—even if the assets you’re interested in haven’t changed.
Compressing the Build Context
You can compress the build context to further improve build performance. Pass the –compress flag to docker build to apply gzip compression. The compression occurs before the context is sent to the Docker daemon.
This can improve performance in some scenarios. The compression adds its own overheads, though—your system now needs to compress the context, and the receiving Docker daemon has to uncompress it. Using compression could actually be slower than copying the original files, in some circumstances. Experiment with each of your images to assess whether you see an improvement.
Conclusion
The Docker build context defines the files that will be available for copying in your Dockerfile. The build context is copied over to the Docker daemon before the build begins.
Build contexts default to including the contents of the directory or Git repository you passed to docker build. You can omit items from the build context by creating a .dockerignore file. This increases efficiency by reducing the amount of redundant data passed to the Docker daemon.
