diff --git a/_data/toc.yaml b/_data/toc.yaml index fb8f1c6eee..d25dce2561 100644 --- a/_data/toc.yaml +++ b/_data/toc.yaml @@ -1563,6 +1563,8 @@ manuals: title: Multi-stage builds - path: /build/building/multi-platform/ title: Multi-platform images + - path: /build/building/env-vars/ + title: Environment variables - path: /build/building/opentelemetry/ title: OpenTelemetry support - path: /build/building/base-images/ @@ -1681,8 +1683,6 @@ manuals: title: Configure - path: /build/buildkit/toml-configuration/ title: TOML configuration - - path: /build/buildkit/color-output-controls/ - title: Color output controls - path: /build/release-notes/ title: Release notes - sectiontitle: Docker Compose diff --git a/build/building/env-vars.md b/build/building/env-vars.md new file mode 100644 index 0000000000..d9290fc1fc --- /dev/null +++ b/build/building/env-vars.md @@ -0,0 +1,185 @@ +--- +title: Environment variables for Docker Build +description: Use environment variables to configure builds +keywords: docker build, buildx, buildkit, env, environment variables, config +redirect_from: + - /build/buildkit/color-output-controls/ +--- + +You can set the following environment variables to enable, disable, or change +the behavior of features related to building: + +| Variable | Type | Description | +| ----------------------------------------------------------------- | ----------------- | ---------------------------------------------------- | +| [BUILDKIT_COLORS](#buildkit_colors) | String | Configure text color for the terminal output. | +| [BUILDKIT_HOST](#buildkit_host) | String | Specify host to use for remote builders. | +| [BUILDKIT_PROGRESS](#buildkit_progress) | String | Configure type of progress output. | +| [BUILDX_BUILDER](#buildx_builder) | String | Specify the builder instance to use. | +| [BUILDX_CONFIG](#buildx_config) | String | Specify location for configuration, state, and logs. | +| [BUILDX_EXPERIMENTAL](#buildx_experimental) | Boolean | Turn on experimental features. | +| [BUILDX_GIT_INFO](#buildx_git_info) | Boolean | Remove Git information in provenance attestations. | +| [BUILDX_GIT_LABELS](#buildx_git_labels) | String \| Boolean | Add Git provenance labels to images. | +| [BUILDX_NO_DEFAULT_ATTESTATIONS](#buildx_no_default_attestations) | Boolean | Turn off default provenance attestations. | +| [BUILDX_NO_DEFAULT_LOAD](#buildx_no_default_load) | Boolean | Turn off loading images to image store by default. | + +See also +[BuildKit built-in build args](../../engine/reference/builder.md#buildkit-built-in-build-args). + +You can express Boolean values for environment variables in different ways. For +example, `true`, `1`, and `T` all evaluate to true. Evaluation is done using the +`strconv.ParseBool` function in the Go standard library. See the +[reference documentation](https://pkg.go.dev/strconv#ParseBool){: target="_blank" rel="noopener" class="_" } +for details. + +## BUILDKIT_COLORS + +Changes the colors of the terminal output. Set `BUILDKIT_COLORS` to a CSV string +in the following format: + +```console +$ export BUILDKIT_COLORS="run=123,20,245:error=yellow:cancel=blue:warning=white" +``` + +Color values can be any valid RGB hex code, or one of the +[BuildKit predefined colors](https://github.com/moby/buildkit/blob/master/util/progress/progressui/colors.go){: target="_blank" rel="noopener" class="_" }. + +Setting `NO_COLOR` to anything turns off colorized output, as recommended by +[no-color.org](https://no-color.org/){: target="_blank" rel="noopener" class="_" }. + +## BUILDKIT_HOST + +_Introduced in [Buildx v0.9.0](../release-notes.md#090)_ + +You use the `BUILDKIT_HOST` to specify the address of a BuildKit daemon to use +as a remote builder. This is the same as specifying the address as a positional +argument to `docker buildx create`. + +Usage: + +```console +$ export BUILDKIT_HOST=tcp://localhost:1234 +$ docker buildx create --name=remote --driver=remote +``` + +If you specify both the `BUILDKIT_HOST` environment variable and a positional +argument, the argument takes priority. + +## BUILDKIT_PROGRESS + +Sets the type of the BuildKit progress output. Valid values are: + +- `auto` (default) +- `plain` +- `tty` + +Usage: + +```console +$ export BUILDKIT_PROGRESS=plain +``` + +## BUILDX_BUILDER + +Overrides the configured builder instance. Same as the `docker buildx --builder` +CLI flag. + +Usage: + +```console +$ export BUILDX_BUILDER=my-builder +``` + +## BUILDX_CONFIG + +You can use `BUILDX_CONFIG` to specify the directory to use for build +configuration, state, and logs. The lookup order for this directory is as +follows: + +- `$BUILDX_CONFIG` +- `$DOCKER_CONFIG/buildx` +- `~/.docker/buildx` (default) + +Usage: + +```console +$ export BUILDX_CONFIG=/usr/local/etc +``` + +## BUILDX_EXPERIMENTAL + +Enables experimental build features. + +Usage: + +```console +$ export BUILDX_EXPERIMENTAL=1 +``` + +## BUILDX_GIT_INFO + +_Introduced in [Buildx v0.10.0](../release-notes.md#0100)_ + +When set to false, removes source control information from +[provenance attestations](../attestations/slsa-provenance.md). + +Usage: + +```console +$ export BUILDX_GIT_INFO=0 +``` + +## BUILDX_GIT_LABELS + +_Introduced in [Buildx v0.10.0](../release-notes.md#0100)_ + +Adds provenance labels, based on Git information, to images that you build. The +labels are: + +- `com.docker.image.source.entrypoint`: Location of the Dockerfile relative to + the project root +- `org.opencontainers.image.revision`: Git commit revision +- `org.opencontainers.image.source`: SSH or HTTPS address of the repository + +Example: + +```json + "Labels": { + "com.docker.image.source.entrypoint": "Dockerfile", + "org.opencontainers.image.revision": "5734329c6af43c2ae295010778cd308866b95d9b", + "org.opencontainers.image.source": "git@github.com:foo/bar.git" + } +``` + +Usage: + +- Set `BUILDX_GIT_LABELS=1` to include the `entrypoint` and `revision` labels. +- Set `BUILDX_GIT_LABELS=full` to include all labels. + +If the repository is in a dirty state, the `revision` gets a `-dirty` suffix. + +## BUILDX_NO_DEFAULT_ATTESTATIONS + +_Introduced in Buildx v0.10.4_ + +By default, BuildKit v0.11 and later adds +[provenance attestations](../attestations/slsa-provenance.md) to images you +build. Set `BUILDX_NO_DEFAULT_ATTESTATIONS=1` to disable the default provenance +attestations. + +Usage: + +```console +$ export BUILDX_NO_DEFAULT_ATTESTATION=1 +``` + +## BUILDX_NO_DEFAULT_LOAD + +When you build an image using the `docker` driver, the image is automatically +loaded to the image store when the build finishes. Set `BUILDX_NO_DEFAULT_LOAD` +to disable automatic loading of images to the local container store. + +Usage: + +```console +$ export BUILDX_NO_DEFAULT_LOAD=1 +``` diff --git a/build/buildkit/color-output-controls.md b/build/buildkit/color-output-controls.md deleted file mode 100644 index 16ee35d534..0000000000 --- a/build/buildkit/color-output-controls.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Color output controls -description: Learn how to control the color of BuildKit progress output. -keywords: build, buildx buildkit, color, terminal -redirect_from: - - /build/customize/color-output-controls/ ---- - -BuildKit and Buildx have support for modifying the colors that are used to -output information to the terminal. You can set the environment variable -`BUILDKIT_COLORS` to something like `run=123,20,245:error=yellow:cancel=blue:warning=white` -to set the colors that you would like to use: - -![Progress output custom colors](../images/buildkit-progress-colors.png) - -Setting `NO_COLOR` to anything will disable any colorized output as recommended -by [no-color.org](https://no-color.org/){:target="blank" rel="noopener" class=""}: - -![Progress output no color](../images/buildkit-progress-nocolor.png) - -> **Note** -> -> Parsing errors will be reported but ignored. This will result in default -> color values being used where needed. - -See also [the list of pre-defined colors](https://github.com/moby/buildkit/blob/master/util/progress/progressui/colors.go){:target="blank" rel="noopener" class=""}. diff --git a/build/images/buildkit-progress-colors.png b/build/images/buildkit-progress-colors.png deleted file mode 100644 index 56c8ea15d7..0000000000 Binary files a/build/images/buildkit-progress-colors.png and /dev/null differ diff --git a/build/images/buildkit-progress-nocolor.png b/build/images/buildkit-progress-nocolor.png deleted file mode 100644 index dcde131d73..0000000000 Binary files a/build/images/buildkit-progress-nocolor.png and /dev/null differ