docker build (legacy builder) (original) (raw)

This page refers to the legacy implementation of docker build, using the legacy (pre-BuildKit) build backend. This configuration is only relevant if you're building Windows containers.

For information about the default docker build, using Buildx, seedocker buildx build.

When building with legacy builder, images are created from a Dockerfile by running a sequence ofcommits. This process is inefficient and slow compared to using BuildKit, which is why this build strategy is deprecated for all use cases except for building Windows containers. It's still useful for building Windows containers because BuildKit doesn't yet have full feature parity for Windows.

Builds invoked with docker build use Buildx (and BuildKit) by default, unless:

• You're running Docker Engine in Windows container mode
• You explicitly opt out of using BuildKit by setting the environment variable DOCKER_BUILDKIT=0.

The descriptions on this page only covers information that's exclusive to the legacy builder, and cases where behavior in the legacy builder deviates from behavior in BuildKit. For information about features and flags that are common between the legacy builder and BuildKit, such as --tag and --target, refer to the documentation fordocker buildx build.

Build context with the legacy builder

The build context is the positional argument you pass when invoking the build command. In the following example, the context is ., meaning current the working directory.

When using the legacy builder, the build context is sent over to the daemon in its entirety. With BuildKit, only the files you use in your builds are transmitted. The legacy builder doesn't calculate which files it needs beforehand. This means that for builds with a large context, context transfer can take a long time, even if you're only using a subset of the files included in the context.

When using the legacy builder, it's therefore extra important that you carefully consider what files you include in the context you specify. Use a.dockerignorefile to exclude files and directories that you don't require in your build from being sent as part of the build context.

Accessing paths outside the build context

The legacy builder will error out if you try to access files outside of the build context using relative paths in your Dockerfile.

BuildKit on the other hand strips leading relative paths that traverse outside of the build context. Re-using the previous example, the path COPY ../../some-dir . evaluates to COPY some-dir . with BuildKit.

Specify isolation technology for container (--isolation)

This option is useful in situations where you are running Docker containers on Windows. The --isolation=<value> option sets a container's isolation technology. On Linux, the only supported is the default option which uses Linux namespaces. On Microsoft Windows, you can specify these values:

Optional security options (--security-opt)

This flag is only supported on a daemon running on Windows, and only supports the credentialspec option. The credentialspec must be in the formatfile://spec.txt or registry://keyname.

Squash an image's layers (--squash) (experimental)

Overview

The --squash option is an experimental feature, and should not be considered stable.

Once the image is built, this flag squashes the new layers into a new image with a single new layer. Squashing doesn't destroy any existing image, rather it creates a new image with the content of the squashed layers. This effectively makes it look like all Dockerfile commands were created with a single layer. The --squash flag preserves the build cache.

Squashing layers can be beneficial if your Dockerfile produces multiple layers modifying the same files. For example, files created in one step and removed in another step. For other use-cases, squashing images may actually have a negative impact on performance. When pulling an image consisting of multiple layers, the daemon can pull layers in parallel and allows sharing layers between images (saving space).

For most use cases, multi-stage builds are a better alternative, as they give more fine-grained control over your build, and can take advantage of future optimizations in the builder. Refer to theMulti-stage buildssection for more information.

Known limitations

The --squash option has a number of known limitations:

• When squashing layers, the resulting image can't take advantage of layer sharing with other images, and may use significantly more space. Sharing the base image is still supported.
• When using this option you may see significantly more space used due to storing two copies of the image, one for the build cache with all the cache layers intact, and one for the squashed version.
• While squashing layers may produce smaller images, it may have a negative impact on performance, as a single layer takes longer to extract, and you can't parallelize downloading a single layer.
• When attempting to squash an image that doesn't make changes to the filesystem (for example, the Dockerfile only contains ENV instructions), the squash step will fail (see issue #33823).

Prerequisites

The example on this page is using experimental mode in Docker 23.03.

You can enable experimental mode by using the --experimental flag when starting the Docker daemon or setting experimental: true in the daemon.json configuration file.

By default, experimental mode is disabled. To see the current configuration of the Docker daemon, use the docker version command and check the Experimentalline in the Engine section:

Build an image with the --squash flag

The following is an example of a build with the --squash flag. Below is theDockerfile:

Next, build an image named test using the --squash flag.

After the build completes, the history looks like the below. The history could show that a layer's name is <missing>, and there is a new layer with COMMENT merge.

Test the image, check for /remove_me being gone, make sure hello\nworld is in /hello, make sure the HELLO environment variable's value is world.