Sync from docker/docs@90cab2e by PCIT

SUMMARY.md

@@ -998,13 +998,12 @@
     * [Swarm Mode](content/includes/swarm-mode.md)
   - Language
     - Dotnet
-      * [What Will You Learn In This Module](content/language/dotnet/_index.md)
-      * [Build your .NET image](content/language/dotnet/build-images.md)
-      * [Configure CI CD For Your Application](content/language/dotnet/configure-ci-cd.md)
+      * [.NET language-specific guide](content/language/dotnet/_index.md)
+      * [Configure CI/CD for your .NET application](content/language/dotnet/configure-ci-cd.md)
+      * [Containerize a .NET application](content/language/dotnet/containerize.md)
       * [Deploy Your App](content/language/dotnet/deploy.md)
-      * [Use Containers For Development](content/language/dotnet/develop.md)
-      * [Run Your Image As A Container](content/language/dotnet/run-containers.md)
-      * [Run Your Tests](content/language/dotnet/run-tests.md)
+      * [Use containers for .NET development](content/language/dotnet/develop.md)
+      * [Run .NET tests in a container](content/language/dotnet/run-tests.md)
     - Golang
       * [What Will You Learn In This Module](content/language/golang/_index.md)
       * [Build Your Go Image](content/language/golang/build-images.md)

content/build/building/multi-platform.md

@@ -55,9 +55,8 @@ loads it through a binary registered in the `binfmt_misc` handler.
 
 > **Note**
 >
-> QEMU performs full-system emulation of non-native platforms, which is much
-> slower than native builds. Compute-heavy tasks like compilation and
-> compression or decompression likely results in a large performance hit.
+> Emulation with QEMU can be much slower than native builds, especially for
+> compute-heavy tasks like compilation and compression or decompression.
 >
 > Use [cross-compilation](#cross-compilation) instead, if possible.
 
@@ -257,4 +256,4 @@ Linux architectures such as `arm`, `mips`, `ppc64le`, and even `s390x`.
 This does not require any special configuration in the container itself as it
 uses [qemu-static](https://wiki.qemu.org/Main_Page)
 from the Docker Desktop VM. Because of this, you can run an ARM container,
-like the `arm32v7` or `ppc64le` variants of the busybox image.
+like the `arm32v7` or `ppc64le` variants of the busybox image.

content/build/drivers/docker-container.md

@@ -135,11 +135,10 @@ $ docker buildx build \
   --push .
 ```
 
-> **Warning**
+> **Note**
 >
-> QEMU performs full-system emulation of non-native platforms, which is much
-> slower than native builds. Compute-heavy tasks like compilation and
-> compression/decompression will likely take a large performance hit.
+> Emulation with QEMU can be much slower than native builds, especially for
+> compute-heavy tasks like compilation and compression or decompression.
 
 ## Custom network
 

content/build/hydrobuild.md

@@ -54,58 +54,103 @@ Docker Desktop 4.23.0 and later versions ship with a Hydrobuild-compatible
 Buildx binary. Alternatively, you can download and install the binary manually
 from [this repository](https://github.com/docker/buildx-desktop).
 
-## Connecting to Hydrobuild
+## Connect to Hydrobuild
 
-To start building with Hydrobuild, you must create a new builder using the
-`docker buildx create` command. The builder is connected to Hydrobuild through
-an endpoint that you specify. The endpoint represents a single, isolated
-builder. Builder endpoints have the following format:
+To start using Hydrobuild, you must first add the builder's endpoint to your
+local Docker configuration.
 
-cloud://<org>/default
+{{< tabs group="ui" >}}
+{{< tab name="CLI" >}}
 
-`<org>` is the Docker organization that the builder is provisioned for.
+1. Sign in to your Docker account
 
-The builders have native support for the `linux/amd64` and `linux/arm64`
-architectures by default. This gives you a high-performance build cluster for
-building multi-platform images natively.
+   ```console
+   $ docker login
+   ```
 
-You can omit the `cloud://` protocol prefix from the endpoint when you create a
-builder using the `cloud` driver.
+2. Add the Hydrobuild endpoint.
+
+   ```console
+   $ docker buildx create --driver cloud <ORG>/default
+   ```
 
-### Create a builder
+   Replace `<ORG>` with the Docker Hub namespace of your Docker organization.
 
-1. Sign in to your Docker ID using the Docker Desktop UI or the `docker login`
-   command.
+This creates a builder named `cloud-<org>-default`.
 
-2. Create a builder that uses the `cloud` driver.
+{{< /tab >}}
+{{< tab name="GUI" >}}
 
-   ```console
-   $ docker buildx create --driver cloud <org>/default
-   ```
+Enable the [Builds view](../desktop/use-desktop/builds.md) in Docker Desktop
+and complete the following steps:
 
-   Replace `<org>` with the Docker organization.
+1. Sign in to your Docker account using the **Sign in** button in Docker Desktop.
 
-   This creates a builder named `cloud-<org>-default`.
+2. Open the Docker Desktop settings and navigate to the **Builders** tab.
+
+3. Under **Available builders**, select **Create builder**.
+
+   ![Create builder GUI screenshot](./images/create-builder-gui.webp)
+
+{{< /tab >}}
+{{< /tabs >}}
+
+The builder has native support for the `linux/amd64` and `linux/arm64`
+architectures. This gives you a high-performance build cluster for building
+multi-platform images natively.
 
 ## Use Hydrobuild from the CLI
 
-To run a build using Hydrobuild, invoke a build command and specify the
-name of the builder using the `--builder` flag.
+To build using Hydrobuild, invoke a build command and specify the name of the
+builder using the `--builder` flag.
 
 ```console
 $ docker buildx build --builder cloud-<org>-default --tag <org>/<image> .
 ```
 
-> **Note**
->
-> Building with `--tag` loads the build result to the local image store
-> automatically when the build finishes. To build without a tag and load the
-> result, you must pass the `--load` flag.
->
-> If you use the containerd image store, you must always pass `--load` to
-> download the results, even if you build with a tag.
+If you want to use Hydrobuild without having to specify the `--builder` flag
+each time, you can set it as the default builder.
+
+{{< tabs group="ui" >}}
+{{< tab name="CLI" >}}
+
+Run the following command:
+
+```console
+$ docker buildx use cloud-<org>-default --global
+```
+
+{{< /tab >}}
+{{< tab name="GUI" >}}
+
+1. Open the Docker Desktop settings and navigate to the **Builders** tab.
+2. Find the Hydrobuild builder under **Available builders**.
+3. Open the drop-down menu and select **Use**.
+
+   ![Selecting Hydrobuild as default using the GUI](./images/set-default-builder-gui.webp)
+
+{{< /tab >}}
+{{< /tabs >}}
+
+Changing your default builder with `docker buildx use` only changes the default
+builder for the `docker buildx build` command. The `docker build` command still
+uses the `default` builder, unless you specify the `--builder` flag explicitly.
 
-To build a multi-platform image and push it to a registry:
+If you use build scripts, such as `make`, we recommend that you update your
+build commands from `docker build` to `docker buildx build`, to avoid any
+confusion with regards to builder selection. Alternatively, you can run `docker
+buildx install` to make the default `docker build` command behave like `docker
+buildx build`, without discrepancies.
+
+## Loading build results
+
+Building with `--tag` loads the build result to the local image store
+automatically when the build finishes. To build without a tag and load the
+result, you must pass the `--load` flag.
+
+Loading the build result for multi-platform images is not supported. Use the
+`docker buildx build --push` flag when building multi-platform images to push
+the output to a registry.
 
 ```console
 $ docker buildx build --builder cloud-<org>-default \
@@ -114,40 +159,33 @@ $ docker buildx build --builder cloud-<org>-default \
   --push .
 ```
 
-> **Note**
->
-> If you build multi-platform images, you won't be able to load the images back
-> to your local image store unless you turn on the containerd image store
-> feature, and use the `--load` flag.
->
-> Using the containerd image store with Hydrobuild currently results in slower
-> transfers of build output to the client, compared to when you use the default
-> image store.
->
-> When building multi-platform images, consider pushing the resulting image to
-> a registry directly, using the `docker buildx build --push` flag.
+If you want to build with a tag, but you don't want to load the results to your
+local image store, you export the build results to the build cache only:
+
+```console
+$ docker buildx build --builder cloud-<org>-default \
+  --platform linux/amd64,linux/arm64 \
+  --tag <org>/<image> \
+  --output type=cacheonly .
+```
 
-### Use by default
+## Multi-platform builds
 
-If you want to use Hydrobuild by default, you can run the following command to
-make it the selected builder:
+To run multi-platform builds, you must specify all of the platforms that you
+want to build for using the `--platform` flag.
 
 ```console
-$ docker buildx use cloud-<org>-default --global
+$ docker buildx build --builder cloud-<org>-default \
+  --platform linux/amd64,linux/arm64 \
+  --tag <org>/<image> \
+  --push .
 ```
 
-> **Note**
->
-> Changing your default builder with `docker buildx use` only changes the
-> default builder for the `docker buildx build` command. The `docker build`
-> command still uses the `default` builder, unless you specify the `--builder`
-> flag explicitly.
->
-> If you use build scripts, such as `make`, we recommend that you update your
-> build commands from `docker build` to `docker buildx build`, to avoid any
-> confusion with regards to builder selection. Alternatively, you can run
-> `docker buildx install` to make the default `docker build` command behave
-> like `docker buildx build`, without discrepancies.
+If you don't specify the platform, Hydrobuild automatically builds for the
+architecture matching your local environment.
+
+To learn more about building for multiple platforms, refer to [Multi-platform
+builds](./building/multi-platform.md).
 
 ## Use Hydrobuild in CI
 
@@ -166,8 +204,9 @@ registry directly, rather than loading the image and then pushing it. Pushing
 directly speeds up your builds and avoids unnecessary file transfers.
 
 If you just want to build and discard the output, export the results to the
-build cache using `--output type=cacheonly`, or build without a `tag`.
-Hydrobuild automatically loads the build result if you build a tagged image.
+build cache or build without tagging the image. Hydrobuild automatically loads
+the build result if you build a tagged image. See [Loading build
+results](#loading-build-results) for details.
 
 {{< tabs >}}
 {{< tab name="GitHub Actions" >}}
@@ -451,3 +490,27 @@ default `docker` builder, run the following command:
 ```console
 $ docker context use default
 ```
+
+### How do I manage the build cache with Hydrobuild?
+
+You don't need to manage the builder's cache manually. The system manages it
+for you through [garbage collection](./cache/garbage-collection.md).
+
+Hydrobuild uses the following garbage collection limits:
+
+- Size: 90% of 1TB
+- Age: cache not used in the past 180 days
+- Number of build history records: 10 000
+
+Old cache is automatically removed if you hit any of these limits. You can
+check your current cache state using the [`docker buildx du`
+command](../engine/reference/commandline/buildx_du.md).
+
+To clear the builder's cache manually, you can use the [`docker buildx prune`
+command](../engine/reference/commandline/buildx_prune.md) command. This works
+like pruning the cache for any other builder.
+
+> **Note**
+>
+> Pruning Hydrobuild cache also removes the cache for other team members using
+> the same builder.

content/compose/environment-variables/set-environment-variables.md

@@ -78,9 +78,20 @@ web:
     - DEBUG
 ```
 
-The value of the `DEBUG` variable in the container is taken from the value for the same variable in the shell in which Compose is run.
+The value of the `DEBUG` variable in the container is taken from the value for the same variable in the shell in which Compose is run. 
+Note that in this case no warning will be issued if the `DEBUG` variable in the shell environment is not set. 
 
-See [`environment` attribute](../compose-file/05-services.md#environment) for more information.
+You can also explicitly assign a variable using a Bash-like syntax `${DEBUG}`:
+
+```yaml
+web:
+  environment:
+    - DEBUG=${DEBUG}
+```
+
+The result is similar to the one above but Compose will give you a warning if the `DEBUG` variable is not set in the shell environment.
+
+See [`environment` attribute](../compose-file/05-services.md#environment) and [variable interpolation](../compose-file/12-interpolation.md) for more information.
 
 ### Use the `env_file` attribute
 

content/compose/profiles.md

@@ -170,7 +170,7 @@ db:
   profiles: ["debug", "dev"]
 ```
 
-or start a profile of `db` explicitly:
+or start the `dev` profile explicitly:
 
 ```console
 # Profiles "debug" is started automatically by targeting phpmyadmin
@@ -180,4 +180,4 @@ $ COMPOSE_PROFILES=dev docker compose up phpmyadmin
 
 ## Reference information
 
-[`profiles`](compose-file/05-services.md#profiles)
+[`profiles`](compose-file/05-services.md#profiles)

content/language/dotnet/_index.md

@@ -1,24 +1,21 @@
 ---
-description: Containerize .NET apps using Docker
-keywords: Docker, getting started, .net, language
-title: What will you learn in this module?
+description: Containerize and develop .NET apps using Docker
+keywords: getting started, .net
+title: .NET language-specific guide
 toc_min: 1
 toc_max: 2
 ---
 
 The .NET getting started guide teaches you how to create a containerized .NET application using Docker. In this guide, you'll learn how to:
 
-* Create a sample .NET application
-* Create a new Dockerfile which contains instructions required to build a .NET image
-* Build an image and run the newly built image as a container
-* Set up volumes and networking
-* Orchestrate containers using Compose
-* Use containers for development
-* Configure a CI/CD pipeline for your application using GitHub Actions
+* Containerize and run a .NET application
+* Set up a local environment to develop a .NET application using containers
+* Run tests for a .NET application using containers
+* Configure a CI/CD pipeline for a containerized .NET application using GitHub Actions
 * Deploy your application to the cloud
 
 After completing the .NET getting started modules, you should be able to containerize your own .NET application based on the examples and instructions provided in this guide.
 
-Let's get started!
+Start by containerizing an existing .NET application.
 
-{{< button text="Build your first .NET image" url="build-images.md" >}}
+{{< button text="Containerize a .NET app" url="containerize.md" >}}