diff --git a/_config.yml b/_config.yml index ae86b4f36b16..1d3e91f27158 100644 --- a/_config.yml +++ b/_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" diff --git a/_data/toc.yaml b/_data/toc.yaml index ab70cbcc2bbe..aca96b9059c9 100644 --- a/_data/toc.yaml +++ b/_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: diff --git a/_layouts/landing.html b/_layouts/landing.html index 12671d7520c3..69a09e267e32 100644 --- a/_layouts/landing.html +++ b/_layouts/landing.html @@ -134,7 +134,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/build/buildx/index.md b/build/buildx/index.md index 4dab0bb66329..d8f6107a8532 100644 --- a/build/buildx/index.md +++ b/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). diff --git a/develop/develop-images/multistage-build.md b/build/guides/multi-stage-build.md similarity index 88% rename from develop/develop-images/multistage-build.md rename to build/guides/multi-stage-build.md index 611b6aea1350..0934eafc1e61 100644 --- a/develop/develop-images/multistage-build.md +++ b/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. diff --git a/compose/compose-file/compose-file-v2.md b/compose/compose-file/compose-file-v2.md index d3b97f5a9a21..18d3cb344a69 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/guides/multi-stage-build.md) for details. ```yaml diff --git a/compose/compose-file/compose-file-v3.md b/compose/compose-file/compose-file-v3.md index 473661658618..65f90fe5368d 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/guides/multi-stage-build.md) for details. ```yaml diff --git a/develop/dev-best-practices.md b/develop/dev-best-practices.md index d9945e158e2f..328dfebf271d 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/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 diff --git a/develop/develop-images/dockerfile_best-practices.md b/develop/develop-images/dockerfile_best-practices.md index 7f90775c7b3c..17e9f3d7dc69 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/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 diff --git a/develop/index.md b/develop/index.md index bdde70f6d48b..41be4e580a54 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/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="_"} diff --git a/develop/scan-images/index.md b/develop/scan-images/index.md index 8b1ae373bcc4..634f2a438f51 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/guides/multi-stage-build.md). ### Rebuild images diff --git a/language/golang/build-images.md b/language/golang/build-images.md index cddbc85caab2..d7ce1f7dcd7b 100644 --- a/language/golang/build-images.md +++ b/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. diff --git a/storage/storagedriver/index.md b/storage/storagedriver/index.md index 7d63b058bc66..c9af4ad0ea33 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/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,