build: add guides

_config.yml

@@ -163,6 +163,17 @@ fetch-remote:
           - "!docs/README.md" # readme to make things nice in the compose-cli repo, but meaningless here
           - "!docs/architecture.md" # Compose-CLI architecture, unrelated to cloud integration
 
+  - repo: "https://github.com/docker/buildx"
+    ref: "master"
+    paths:
+      - dest: "build/guides"
+        src:
+          - "docs/guides/*.md"
+          - "!docs/guides/cicd.md" # CI/CD documentation is already handled in ci-cd/github-actions
+      - dest: "build/bake"
+        src:
+          - "docs/guides/bake/**"
+
   - repo: "https://github.com/distribution/distribution"
     default_branch: "main"
     ref: "release/2.7"

_data/toc.yaml

@@ -125,8 +125,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/
@@ -1396,6 +1394,40 @@ manuals:
           title: Working with Buildx
         - path: /build/buildx/install/
           title: Install Buildx
+    - sectiontitle: Bake
+      section:
+        - path: /build/bake/
+          title: Overview
+        - path: /build/bake/file-definition/
+          title: File definition
+        - path: /build/bake/configuring-build/
+          title: Configuring builds
+        - path: /build/bake/hcl-funcs/
+          title: User defined HCL functions
+        - path: /build/bake/build-contexts/
+          title: Build contexts and linking targets
+        - path: /build/bake/compose-file/
+          title: Building from Compose file
+    - sectiontitle: Guides
+      section:
+        - path: /build/guides/cni-networking/
+          title: CNI networking
+        - path: /build/guides/custom-network/
+          title: Using a custom network
+        - path: /build/guides/custom-registry-config/
+          title: Using a custom registry config
+        - path: /build/guides/kubernetes-builder/
+          title: Kubernetes builder
+        - path: /build/guides/multi-stage-build/
+          title: Multi-stage builds
+        - path: /build/guides/opentelemetry/
+          title: OpenTelemetry support
+        - path: /build/guides/registry-mirror/
+          title: Define a registry mirror
+        - path: /build/guides/remote-builder/
+          title: Remote builder
+        - path: /build/guides/resource-limiting/
+          title: Resource limiting
 
 - sectiontitle: Docker Compose
   section:

_layouts/landing.html

@@ -134,7 +134,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/guides/multi-stage-build/">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>

build/buildx/index.md

@@ -157,25 +157,7 @@ FROM alpine
 COPY --from=build /log /log
 ```
 
-## High-level build options
-
-Buildx also aims to provide support for high-level build concepts that go beyond
-invoking a single build command.
-
-BuildKit efficiently handles multiple concurrent build requests and de-duplicating
-work. The build commands can be combined with general-purpose command runners
-(for example, `make`). However, these tools generally invoke builds in sequence
-and therefore cannot leverage the full potential of BuildKit parallelization,
-or combine BuildKit’s output for the user. For this use case, we have added a
-command called [`docker buildx bake`](../../engine/reference/commandline/buildx_bake.md).
-
-The `bake` command supports building images from compose files, similar to
-[`docker-compose build`](../../engine/reference/commandline/compose_build.md),
-but allowing all the services to be built concurrently as part of a single
-request.
-
-There is also support for custom build rules from HCL/JSON files allowing
-better code reuse and different target groups. The design of bake is in very
-early stages, and we are looking for feedback from users. Let us know your
-feedback by creating an issue in the [Docker Buildx](https://github.com/docker/buildx/issues){:target="_blank" rel="noopener" class="_"}
-GitHub repository.
+## High-level build options with Bake
+
+Check out our guide about [Bake](../bake/index.md) to get started with the
+[`docker buildx bake` command](../../engine/reference/commandline/buildx_bake.md).

develop/develop-images/multistage-build.md → build/guides/multi-stage-build.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
@@ -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
 ```
@@ -143,7 +141,7 @@ Dockerfile are re-ordered later, the `COPY` doesn't break.
 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    ./
+COPY app.go ./
 RUN CGO_ENABLED=0 GOOS=linux go build -a -installsuffix cgo -o app .
 
 FROM alpine:latest  
@@ -186,7 +184,8 @@ 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
@@ -204,4 +203,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/guides/multi-stage-build.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/guides/multi-stage-build.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/guides/multi-stage-build.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/guides/multi-stage-build.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/guides/multi-stage-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.
 
 ### 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/guides/multi-stage-build.md){: target="_blank" rel="noopener" class="_"} 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/guides/multi-stage-build.md).
 
 ### Rebuild images
 

language/golang/build-images.md

@@ -484,7 +484,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/guides/multi-stage-build.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/guides/multi-stage-build.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,