Merge pull request docker#15392 from crazy-max/build-multi-stage

build: multi-stage builds

_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/
@@ -1401,6 +1399,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

_layouts/landing.html

@@ -135,7 +135,7 @@ <h5 class="title">How do I?</h5>
             <div class="col-xs-12 col-md-6"><a href="/config/daemon/">Configure the Docker daemon</a></div>
             <div class="col-xs-12 col-md-6"><a href="/get-started/02_our_app/">Build and run an image</a></div>
             <div class="col-xs-12 col-md-6"><a href="/config/labels-custom-metadata/">Manage Docker objects</a></div>
-            <div class="col-xs-12 col-md-6"><a href="/develop/develop-images/multistage-build/">Use multi-stage builds</a></div>
+            <div class="col-xs-12 col-md-6"><a href="/build/building/multi-stage/">Multi-stage builds</a></div>
             <div class="col-xs-12 col-md-6"><a href="/get-started/swarm-deploy/">Scale apps using Swarm</a></div>
           </div>
         </div>

develop/develop-images/multistage-build.md → 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,18 +32,18 @@ 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
 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,24 +59,21 @@ FROM alpine:latest
 RUN apk --no-cache add ca-certificates
 WORKDIR /root/
 COPY app ./
-CMD ["./app"]  
+CMD ["./app"]
 ```
 
 **`build.sh`**:
 
 ```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.

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

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

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

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
 

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="_"} 

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
 

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.
 

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,