diff --git a/_data/toc.yaml b/_data/toc.yaml index ef228ddfcef6..11b8ca1d34cd 100644 --- a/_data/toc.yaml +++ b/_data/toc.yaml @@ -128,8 +128,6 @@ guides: title: Dockerfile best practices - path: /develop/develop-images/build_enhancements/ title: Build images with BuildKit - - path: /develop/develop-images/multistage-build/ - title: Use multi-stage builds - path: /develop/develop-images/image_management/ title: Manage images - path: /develop/develop-images/baseimages/ @@ -1403,6 +1401,8 @@ manuals: title: Kubernetes driver - path: /build/building/drivers/remote/ title: Remote driver + - path: /build/building/multi-stage/ + title: Multi-stage builds - path: /build/building/multi-platform/ title: Multi-platform images - sectiontitle: Customizing builds diff --git a/_layouts/landing.html b/_layouts/landing.html index 2f64045f7642..a62902a9136e 100644 --- a/_layouts/landing.html +++ b/_layouts/landing.html @@ -135,7 +135,7 @@
How do I?
Configure the Docker daemon
Build and run an image
Manage Docker objects
-
Use multi-stage builds
+
Multi-stage builds
Scale apps using Swarm
diff --git a/develop/develop-images/multistage-build.md b/build/building/multi-stage.md similarity index 83% rename from develop/develop-images/multistage-build.md rename to build/building/multi-stage.md index 611b6aea1350..e5d1eba545c9 100644 --- a/develop/develop-images/multistage-build.md +++ b/build/building/multi-stage.md @@ -1,18 +1,19 @@ --- -description: Keeping your images small with multi-stage images -keywords: images, containers, best practices, multi-stage, multistage -title: Use multi-stage builds +title: Multi-stage builds +description: Keeping your images small with multi-stage builds +keywords: build, best practices redirect_from: - /engine/userguide/eng-image/multistage-build/ +- /develop/develop-images/multistage-build/ --- -Multistage builds are useful to anyone who has struggled to optimize Dockerfiles -while keeping them easy to read and maintain. +Multi-stage builds are useful to anyone who has struggled to optimize +Dockerfiles while keeping them easy to read and maintain. -> **Acknowledgment**: +> **Acknowledgment** +> > Special thanks to [Alex Ellis](https://twitter.com/alexellisuk) for granting -> permission to use his blog post -> [Builder pattern vs. Multi-stage builds in Docker](https://blog.alexellis.io/mutli-stage-docker-builds/) +> permission to use his blog post [Builder pattern vs. Multi-stage builds in Docker](https://blog.alexellis.io/mutli-stage-docker-builds/) > as the basis of the examples below. ## Before multi-stage builds @@ -31,10 +32,10 @@ to use for production, which only contained your application and exactly what was needed to run it. This has been referred to as the "builder pattern". Maintaining two Dockerfiles is not ideal. -Here's an example of a `Dockerfile.build` and `Dockerfile` which adhere to the +Here's an example of a `build.Dockerfile` and `Dockerfile` which adhere to the builder pattern above: -**`Dockerfile.build`**: +**`build.Dockerfile`**: ```dockerfile # syntax=docker/dockerfile:1 @@ -42,7 +43,7 @@ FROM golang:1.16 WORKDIR /go/src/github.com/alexellis/href-counter/ COPY app.go ./ RUN go get -d -v golang.org/x/net/html \ - && CGO_ENABLED=0 GOOS=linux go build -a -installsuffix cgo -o app . + && CGO_ENABLED=0 go build -a -installsuffix cgo -o app . ``` Notice that this example also artificially compresses two `RUN` commands together @@ -58,7 +59,7 @@ FROM alpine:latest RUN apk --no-cache add ca-certificates WORKDIR /root/ COPY app ./ -CMD ["./app"] +CMD ["./app"] ``` **`build.sh`**: @@ -66,16 +67,13 @@ CMD ["./app"] ```bash #!/bin/sh echo Building alexellis2/href-counter:build - -docker build --build-arg https_proxy=$https_proxy --build-arg http_proxy=$http_proxy \ - -t alexellis2/href-counter:build . -f Dockerfile.build +docker build -t alexellis2/href-counter:build . -f build.Dockerfile docker container create --name extract alexellis2/href-counter:build docker container cp extract:/go/src/github.com/alexellis/href-counter/app ./app docker container rm -f extract echo Building alexellis2/href-counter:latest - docker build --no-cache -t alexellis2/href-counter:latest . rm ./app ``` @@ -93,24 +91,23 @@ With multi-stage builds, you use multiple `FROM` statements in your Dockerfile. Each `FROM` instruction can use a different base, and each of them begins a new stage of the build. You can selectively copy artifacts from one stage to another, leaving behind everything you don't want in the final image. To show -how this works, let's adapt the Dockerfile from the previous section to use +how this works, let's adapt the `Dockerfile` from the previous section to use multi-stage builds. -**`Dockerfile`**: - ```dockerfile # syntax=docker/dockerfile:1 + FROM golang:1.16 WORKDIR /go/src/github.com/alexellis/href-counter/ RUN go get -d -v golang.org/x/net/html COPY app.go ./ -RUN CGO_ENABLED=0 GOOS=linux go build -a -installsuffix cgo -o app . +RUN CGO_ENABLED=0 go build -a -installsuffix cgo -o app . FROM alpine:latest RUN apk --no-cache add ca-certificates WORKDIR /root/ COPY --from=0 /go/src/github.com/alexellis/href-counter/app ./ -CMD ["./app"] +CMD ["./app"] ``` You only need the single Dockerfile. You don't need a separate build script, @@ -122,7 +119,7 @@ $ docker build -t alexellis2/href-counter:latest . The end result is the same tiny production image as before, with a significant reduction in complexity. You don't need to create any intermediate -images and you don't need to extract any artifacts to your local system at all. +images, and you don't need to extract any artifacts to your local system at all. How does it work? The second `FROM` instruction starts a new build stage with the `alpine:latest` image as its base. The `COPY --from=0` line copies just the @@ -140,11 +137,12 @@ Dockerfile are re-ordered later, the `COPY` doesn't break. ```dockerfile # syntax=docker/dockerfile:1 + FROM golang:1.16 AS builder WORKDIR /go/src/github.com/alexellis/href-counter/ RUN go get -d -v golang.org/x/net/html -COPY app.go ./ -RUN CGO_ENABLED=0 GOOS=linux go build -a -installsuffix cgo -o app . +COPY app.go ./ +RUN CGO_ENABLED=0 go build -a -installsuffix cgo -o app . FROM alpine:latest RUN apk --no-cache add ca-certificates @@ -186,10 +184,12 @@ COPY --from=nginx:latest /etc/nginx/nginx.conf /nginx.conf ## Use a previous stage as a new stage -You can pick up where a previous stage left off by referring to it when using the `FROM` directive. For example: +You can pick up where a previous stage left off by referring to it when using +the `FROM` directive. For example: ```dockerfile # syntax=docker/dockerfile:1 + FROM alpine:latest AS builder RUN apk --no-cache add build-base @@ -204,4 +204,4 @@ RUN g++ -o /binary source.cpp ## Version compatibility -Multistage build syntax was introduced in Docker Engine 17.05. +Multi-stage build syntax was introduced in Docker Engine 17.05. diff --git a/compose/compose-file/compose-file-v2.md b/compose/compose-file/compose-file-v2.md index d3b97f5a9a21..2c526f8caa38 100644 --- a/compose/compose-file/compose-file-v2.md +++ b/compose/compose-file/compose-file-v2.md @@ -357,7 +357,7 @@ build: > Added in [version 2.3](compose-versioning.md#version-23) file format Build the specified stage as defined inside the `Dockerfile`. See the -[multi-stage build docs](../../develop/develop-images/multistage-build.md) for +[multi-stage build docs](../../build/building/multi-stage.md) for details. ```yaml diff --git a/compose/compose-file/compose-file-v3.md b/compose/compose-file/compose-file-v3.md index 323426c64f54..0d780c34bca7 100644 --- a/compose/compose-file/compose-file-v3.md +++ b/compose/compose-file/compose-file-v3.md @@ -392,7 +392,7 @@ build: > Added in [version 3.4](compose-versioning.md#version-34) file format Build the specified stage as defined inside the `Dockerfile`. See the -[multi-stage build docs](../../develop/develop-images/multistage-build.md) for +[multi-stage build docs](../../build/building/multi-stage.md) for details. ```yaml diff --git a/develop/dev-best-practices.md b/develop/dev-best-practices.md index d9945e158e2f..c01283006a40 100644 --- a/develop/dev-best-practices.md +++ b/develop/dev-best-practices.md @@ -20,7 +20,7 @@ keep image size small: starting with a generic `ubuntu` image and installing `openjdk` as part of the Dockerfile. -- [Use multistage builds](develop-images/multistage-build.md). For +- [Use multistage builds](../build/building/multi-stage.md). For instance, you can use the `maven` image to build your Java application, then reset to the `tomcat` image and copy the Java artifacts into the correct location to deploy your app, all in the same Dockerfile. This means that your diff --git a/develop/develop-images/dockerfile_best-practices.md b/develop/develop-images/dockerfile_best-practices.md index 7f90775c7b3c..569d6f9ba170 100644 --- a/develop/develop-images/dockerfile_best-practices.md +++ b/develop/develop-images/dockerfile_best-practices.md @@ -252,9 +252,9 @@ similar to `.gitignore` files. For information on creating one, see the ### Use multi-stage builds -[Multi-stage builds](multistage-build.md) allow you to drastically reduce the -size of your final image, without struggling to reduce the number of intermediate -layers and files. +[Multi-stage builds](../../build/building/multi-stage.md) allow you to +drastically reduce the size of your final image, without struggling to reduce +the number of intermediate layers and files. Because an image is built during the final stage of the build process, you can minimize image layers by [leveraging build cache](#leverage-build-cache). @@ -334,10 +334,10 @@ were added to reduce this limitation: - Only the instructions `RUN`, `COPY`, `ADD` create layers. Other instructions create temporary intermediate images, and do not increase the size of the build. -- Where possible, use [multi-stage builds](multistage-build.md), and only copy - the artifacts you need into the final image. This allows you to include tools - and debug information in your intermediate build stages without increasing the - size of the final image. +- Where possible, use [multi-stage builds](../../build/building/multi-stage.md), + and only copy the artifacts you need into the final image. This allows you to + include tools and debug information in your intermediate build stages without + increasing the size of the final image. ### Sort multi-line arguments diff --git a/develop/index.md b/develop/index.md index bdde70f6d48b..6e7c4c5f939a 100644 --- a/develop/index.md +++ b/develop/index.md @@ -17,7 +17,7 @@ these resources to understand some of the most common patterns for getting the most benefits from Docker. - Learn how to [build an image](../engine/reference/builder/){: target="_blank" rel="noopener" class="_"} using a Dockerfile -- Use [multi-stage builds](develop-images/multistage-build.md){: target="_blank" rel="noopener" class="_"} to keep your images lean +- Use [multi-stage builds](../build/building/multi-stage.md) to keep your images lean - Manage application data using [volumes](../storage/volumes.md) and [bind mounts](../storage/bind-mounts.md){: target="_blank" rel="noopener" class="_"} - [Scale your app with Kubernetes](../get-started/kube-deploy.md){: target="_blank" rel="noopener" class="_"} - [Scale your app as a Swarm service](../get-started/swarm-deploy.md){: target="_blank" rel="noopener" class="_"} diff --git a/develop/scan-images/index.md b/develop/scan-images/index.md index e3d96b433251..d44cd5bef4e7 100644 --- a/develop/scan-images/index.md +++ b/develop/scan-images/index.md @@ -91,7 +91,7 @@ You can use multiple `FROM` statements in your Dockerfile, and you can use a dif This method of creating a tiny image does not only significantly reduce complexity, but also the change of implementing vulnerable artifacts in your image. Therefore, instead of images that are built on images, that again are built on other images, multi-stage builds allow you to 'cherry pick' your artifacts without inheriting the vulnerabilities from the base images on which they rely on. -For detailed information on how to configure multi-stage builds, see [multi-stage builds](../develop-images/multistage-build.md). +For detailed information on how to configure multi-stage builds, see [multi-stage builds](../../build/building/multi-stage.md). ### Rebuild images diff --git a/language/golang/build-images.md b/language/golang/build-images.md index 5d2a7f4a9f8e..58a11f7f6be3 100644 --- a/language/golang/build-images.md +++ b/language/golang/build-images.md @@ -480,7 +480,7 @@ that we have used to deploy our Go application is very barebones and is meant for lean deployments of static binaries. For more information on multi-stage builds, please feel free to check out -[other parts](../../develop/develop-images/multistage-build.md) of the Docker +[other parts](../../build/building/multi-stage.md) of the Docker documentation. This is, however, not essential for our progress here, so we'll leave it at that. diff --git a/storage/storagedriver/index.md b/storage/storagedriver/index.md index caae29b0c1e8..8715427ef8b7 100644 --- a/storage/storagedriver/index.md +++ b/storage/storagedriver/index.md @@ -62,7 +62,7 @@ _adding_, and _removing_ files will result in a new layer. In the example above, the `$HOME/.cache` directory is removed, but will still be available in the previous layer and add up to the image's total size. Refer to the [Best practices for writing Dockerfiles](../../develop/develop-images/dockerfile_best-practices.md) -and [use multi-stage builds](../../develop/develop-images/multistage-build.md) +and [use multi-stage builds](../../build/building/multi-stage.md) sections to learn how to optimize your Dockerfiles for efficient images. The layers are stacked on top of each other. When you create a new container,