Merge pull request #19287 from dvdksn/build-building-freshness-tier2

freshness(tier2): /build/building/**

Author: dvdksn

content/build/building/context.md

@@ -411,7 +411,7 @@ ERROR: failed to solve: failed to compute cache key: failed to calculate checksu
 You can use a `.dockerignore` file to exclude files or directories from the
 build context.
 
-```gitignore
+```text
 # .dockerignore
 node_modules
 bar
@@ -471,7 +471,7 @@ on GitHub, which contains the source code.
 
 The following code snippet shows an example `.dockerignore` file.
 
-```gitignore
+```text
 # comment
 */temp*
 */*/temp*
@@ -514,7 +514,7 @@ You can prepend lines with a `!` (exclamation mark) to make exceptions to
 exclusions. The following is an example `.dockerignore` file that uses this
 mechanism:
 
-```gitignore
+```text
 *.md
 !README.md
 ```
@@ -527,7 +527,7 @@ The placement of `!` exception rules influences the behavior: the last line of
 the `.dockerignore` that matches a particular file determines whether it's
 included or excluded. Consider the following example:
 
-```gitignore
+```text
 *.md
 !README*.md
 README-secret.md
@@ -538,7 +538,7 @@ No markdown files are included in the context except README files other than
 
 Now consider this example:
 
-```gitignore
+```text
 *.md
 README-secret.md
 !README*.md

content/build/building/multi-platform.md

@@ -61,6 +61,19 @@ loads it through a binary registered in the `binfmt_misc` handler.
 > Use [multiple native nodes](#multiple-native-nodes) or
 > [cross-compilation](#cross-compilation) instead, if possible.
 
+## Support on Docker Desktop
+
+[Docker Desktop](../../desktop/index.md) provides `binfmt_misc`
+multi-architecture support, which means you can run containers for different
+Linux architectures such as `arm`, `mips`, `ppc64le`, and even `s390x`.
+
+This doesn't 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.
+
+#### QEMU without Docker Desktop
+
 For QEMU binaries registered with `binfmt_misc` on the host OS to work
 transparently inside containers, they must be statically compiled and
 registered with the `fix_binary` flag. This requires a kernel version 4.8 or
@@ -180,7 +193,7 @@ cURL installed for multiple architectures:
 
 ```dockerfile
 # syntax=docker/dockerfile:1
-FROM alpine:3.16
+FROM alpine:{{% param "example_alpine_version" %}}
 RUN apk add curl
 ```
 
@@ -266,14 +279,3 @@ armv7l
 
 In the above example, `uname -m` returns `aarch64` and `armv7l` as expected,
 even when running the commands on a native macOS or Windows developer machine.
-
-## Support on Docker Desktop
-
-[Docker Desktop](../../desktop/index.md) provides `binfmt_misc`
-multi-architecture support, which means you can run containers for different
-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.

content/build/building/multi-stage.md

@@ -1,10 +1,8 @@
 ---
 title: Multi-stage builds
-description: 'Learn about multi-stage builds and how you can use
-
+description: |
+  Learn about multi-stage builds and how you can use
   them to improve your builds and get smaller images
-
-  '
 keywords: build, best practices
 aliases:
 - /engine/userguide/eng-image/multistage-build/
@@ -22,11 +20,11 @@ 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.
 
 The following Dockerfile has two separate stages: one for building a binary,
-and another where we copy the binary into.
+and another where the binary gets copied from the first stage into the next stage.
 
 ```dockerfile
 # syntax=docker/dockerfile:1
-FROM golang:1.21
+FROM golang:{{% param "example_go_version" %}}
 WORKDIR /src
 COPY <<EOF ./main.go
 package main
@@ -71,7 +69,7 @@ Dockerfile are re-ordered later, the `COPY` doesn't break.
 
 ```dockerfile
 # syntax=docker/dockerfile:1
-FROM golang:1.21 as build
+FROM golang:{{% param "example_go_version" %}} as build
 WORKDIR /src
 COPY <<EOF /src/main.go
 package main

content/build/building/packaging.md

@@ -84,15 +84,15 @@ FROM ubuntu:22.04
 
 # install app dependencies
 RUN apt-get update && apt-get install -y python3 python3-pip
-RUN pip install flask==2.1.*
+RUN pip install flask==3.0.*
 
 # install app
 COPY hello.py /
 
 # final configuration
 ENV FLASK_APP=hello
 EXPOSE 8000
-CMD flask run --host 0.0.0.0 --port 8000
+CMD ["flask", "run", "--host", "0.0.0.0", "--port", "8000"]
 ```
 
 Here's a breakdown of what this Dockerfile does:
@@ -181,7 +181,7 @@ The second `RUN` instruction installs the `flask` dependency required by the
 Python application.
 
 ```dockerfile
-RUN pip install flask==2.1.*
+RUN pip install flask==3.0.*
 ```
 
 A prerequisite for this instruction is that `pip` is installed into the build
@@ -234,12 +234,22 @@ team members understand what this application is doing.
 Finally, [`CMD` instruction](../../engine/reference/builder.md#cmd) sets the
 command that is run when the user starts a container based on this image.
 
+```dockerfile
+CMD ["flask", "run", "--host", "0.0.0.0", "--port", "8000"]
+```
+
+This command starts the flask development server listening on all addresses
+on port `8000`. The example here uses the "exec form" version of `CMD`.
+It's also possible to use the "shell form":
+
 ```dockerfile
 CMD flask run --host 0.0.0.0 --port 8000
 ```
 
-In this case we'll start the flask development server listening on all addresses
-on port `8000`.
+There are subtle differences between these two versions,
+for example in how they trap signals like `SIGTERM` and `SIGKILL`.
+For more information about these differences, see
+[Shell and exec form](../../engine/reference/builder.md#shell-and-exec-form)
 
 ## Building
 

content/build/ci/github-actions/named-contexts.md

@@ -42,7 +42,7 @@ jobs:
         with:
           context: .
           build-contexts: |
-            alpine=docker-image://alpine:3.16
+            alpine=docker-image://alpine:{{% param "example_alpine_version" %}}
           tags: myimage:latest
 ```
 

hugo.yaml

@@ -100,6 +100,7 @@ params:
 
   example_go_version: "1.21"
   example_golangci_lint_version: "v1.52"
+  example_alpine_version: "1.19"
 
   min_api_threshold: 1.41