From 2ebb347f83a4d2fc6a11751844c6bac1f92877a6 Mon Sep 17 00:00:00 2001 From: Arthur Date: Mon, 28 Jul 2025 14:47:29 +0200 Subject: [PATCH 01/11] touch up prompts --- .github/prompts/freshness-tier1.prompt.md | 1 + .github/prompts/freshness-tier2.prompt.md | 3 ++- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/.github/prompts/freshness-tier1.prompt.md b/.github/prompts/freshness-tier1.prompt.md index a26490a177d..194df8238fc 100644 --- a/.github/prompts/freshness-tier1.prompt.md +++ b/.github/prompts/freshness-tier1.prompt.md @@ -12,5 +12,6 @@ how fresh and up to date it is. Apply the following: 5. Ensure all the components formatted correctly. 6. Improve the SEO keywords. 7. If you find numbered lists, make sure their numbering only uses 1's. +8. Keep line length to a maximum of 90 characters, and do not add a space character at the end of lines. Do your best and don't be lazy. \ No newline at end of file diff --git a/.github/prompts/freshness-tier2.prompt.md b/.github/prompts/freshness-tier2.prompt.md index e2935f12e4a..6457ea9990f 100644 --- a/.github/prompts/freshness-tier2.prompt.md +++ b/.github/prompts/freshness-tier2.prompt.md @@ -17,6 +17,7 @@ how fresh and up to date it is. Apply the following: 4. If appropriate, follow the document from start to finish to see if steps make sense in sequence 5. Try to add some helpful next steps to the end of the document, but only if there are no *Next steps* or *Related pages* section, already. 6. Try to clarify, shorten or improve the efficiency of some sentences. -7. Check for LLM readibility. +7. Check for LLM readability. +8. Keep line length to a maximum of 90 characters. Do your best and don't be lazy. \ No newline at end of file From 785c459af4c02045e2feb7dff4054a4b159d7aae Mon Sep 17 00:00:00 2001 From: Arthur Date: Mon, 28 Jul 2025 14:47:35 +0200 Subject: [PATCH 02/11] apply freshness touch ups --- content/manuals/build/_index.md | 13 +- content/manuals/build/concepts/context.md | 38 +++--- content/manuals/build/concepts/dockerfile.md | 136 ++++++++----------- content/manuals/build/concepts/overview.md | 80 ++++++----- 4 files changed, 124 insertions(+), 143 deletions(-) diff --git a/content/manuals/build/_index.md b/content/manuals/build/_index.md index c4af3ceb1af..8eb8ed57411 100644 --- a/content/manuals/build/_index.md +++ b/content/manuals/build/_index.md @@ -47,14 +47,13 @@ aliases: - /develop/develop-images/build_enhancements/ --- -Docker Build is one of Docker Engine's most used features. Whenever you are -creating an image you are using Docker Build. Build is a key part of your -software development life cycle allowing you to package and bundle your code and -ship it anywhere. +Docker Build is one of Docker Engine's most used features. Every time you +create an image, you use Docker Build. Build is a key part of your software +development lifecycle that lets you package and bundle your code and ship it +anywhere. -Docker Build is more than a command for building images, and it's not only about -packaging your code. It's a whole ecosystem of tools and features that support -not only common workflow tasks but also provides support for more complex and +Docker Build is more than a command for building images. It's a complete +ecosystem of tools and features that supports common workflow tasks and advanced scenarios. {{< grid >}} diff --git a/content/manuals/build/concepts/context.md b/content/manuals/build/concepts/context.md index 2818bec9b7b..667a28c0ff3 100644 --- a/content/manuals/build/concepts/context.md +++ b/content/manuals/build/concepts/context.md @@ -337,13 +337,11 @@ $ docker build http://server/context.tar.gz ... ``` -The download operation will be performed on the host where the BuildKit daemon -is running. Note that if you're using a remote Docker context or a remote -builder, that's not necessarily the same machine as where you issue the build -command. BuildKit fetches the `context.tar.gz` and uses it as the build -context. Tarball contexts must be tar archives conforming to the standard `tar` -Unix format and can be compressed with any one of the `xz`, `bzip2`, `gzip` or -`identity` (no compression) formats. +The download operation runs on the host where the BuildKit daemon is running. If you +use a remote Docker context or a remote builder, that might not be the same machine +where you issue the build command. BuildKit fetches the `context.tar.gz` and uses it +as the build context. Tarball contexts must be tar archives in the standard `tar` Unix +format and can be compressed with `xz`, `bzip2`, `gzip`, or `identity` (no compression) formats. ## Empty context @@ -437,14 +435,14 @@ improving build speed, especially when using a remote builder. ### Filename and location When you run a build command, the build client looks for a file named -`.dockerignore` in the root directory of the context. If this file exists, the -files and directories that match patterns in the files are removed from the -build context before it's sent to the builder. +`.dockerignore` in the root directory of the context. If this file exists, files +and directories that match patterns in the file are removed from the build context +before Docker sends them to the builder. -If you use multiple Dockerfiles, you can use different ignore-files for each -Dockerfile. You do so using a special naming convention for the ignore-files. -Place your ignore-file in the same directory as the Dockerfile, and prefix the -ignore-file with the name of the Dockerfile, as shown in the following example. +If you use multiple Dockerfiles, you can use different ignore files for each +Dockerfile. Use a special naming convention for these ignore files. Place your +ignore file in the same directory as the Dockerfile, and prefix the ignore file +with the name of the Dockerfile, as shown in the following example. ```text . @@ -520,14 +518,14 @@ Lines that are blank after preprocessing are ignored. > For historical reasons, the pattern `.` is ignored. Beyond Go's `filepath.Match` rules, Docker also supports a special wildcard -string `**` that matches any number of directories (including zero). For -example, `**/*.go` excludes all files that end with `.go` found anywhere in the +string `**` that matches any number of directories, including zero. For +example, `**/*.go` excludes all files ending with `.go` found anywhere in the build context. You can use the `.dockerignore` file to exclude the `Dockerfile` and -`.dockerignore` files. These files are still sent to the builder as they're -needed for running the build. But you can't copy the files into the image using -`ADD`, `COPY`, or bind mounts. +`.dockerignore` files. These files are still sent to the builder because they are +needed for running the build. However, you can't copy these files into the image +using `ADD`, `COPY`, or bind mounts. #### Negating matches @@ -717,7 +715,7 @@ where you have two Dockerfiles: - `base.Dockerfile`: for building a base image - `app.Dockerfile`: for building an application image -The `app.Dockerfile` uses the image produced by `base.Dockerfile` as it's base +The `app.Dockerfile` uses the image produced by its `base.Dockerfile` as its base image: ```dockerfile {title=app.Dockerfile} diff --git a/content/manuals/build/concepts/dockerfile.md b/content/manuals/build/concepts/dockerfile.md index 18601a9b15d..0abde87a501 100644 --- a/content/manuals/build/concepts/dockerfile.md +++ b/content/manuals/build/concepts/dockerfile.md @@ -1,8 +1,8 @@ --- title: Dockerfile overview weight: 20 -description: Learn about Dockerfiles and how to use them with Docker Images to build and package your software -keywords: build, buildx, buildkit, getting started, dockerfile +description: Learn how to use Dockerfiles to build and package your software into Docker images. +keywords: dockerfile, docker build, buildx, buildkit, container image, getting started, image layers, dockerfile instructions aliases: - /build/hellobuild/ - /build/building/packaging/ @@ -10,57 +10,49 @@ aliases: ## Dockerfile -It all starts with a Dockerfile. - -Docker builds images by reading the instructions from a Dockerfile. A -Dockerfile is a text file containing instructions for building your source -code. The Dockerfile instruction syntax is defined by the specification -reference in the [Dockerfile reference](/reference/dockerfile.md). +Docker builds images by reading instructions from a Dockerfile. A +Dockerfile is a text file that contains instructions for building your source +code. The Dockerfile instruction syntax is defined in the +[Dockerfile reference](/reference/dockerfile.md). Here are the most common types of instructions: -| Instruction | Description | -| ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [`FROM `](/reference/dockerfile.md#from) | Defines a base for your image. | -| [`RUN `](/reference/dockerfile.md#run) | Executes any commands in a new layer on top of the current image and commits the result. `RUN` also has a shell form for running commands. | -| [`WORKDIR `](/reference/dockerfile.md#workdir) | Sets the working directory for any `RUN`, `CMD`, `ENTRYPOINT`, `COPY`, and `ADD` instructions that follow it in the Dockerfile. | -| [`COPY `](/reference/dockerfile.md#copy) | Copies new files or directories from `` and adds them to the filesystem of the container at the path ``. | -| [`CMD `](/reference/dockerfile.md#cmd) | Lets you define the default program that is run once you start the container based on this image. Each Dockerfile only has one `CMD`, and only the last `CMD` instance is respected when multiple exist. | +| Instruction | Description | +|-----------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------| +| [`FROM `](/reference/dockerfile.md#from) | Defines a base for your image. | +| [`RUN `](/reference/dockerfile.md#run) | Executes commands in a new layer on top of the current image and commits the result. `RUN` also has a shell form for running commands. | +| [`WORKDIR `](/reference/dockerfile.md#workdir) | Sets the working directory for any `RUN`, `CMD`, `ENTRYPOINT`, `COPY`, and `ADD` instructions that follow it in the Dockerfile. | +| [`COPY `](/reference/dockerfile.md#copy) | Copies new files or directories from `` and adds them to the container at the path ``. | +| [`CMD `](/reference/dockerfile.md#cmd) | Defines the default program that runs when you start the container. Only the last `CMD` in the Dockerfile is used if multiple exist. | -Dockerfiles are crucial inputs for image builds and can facilitate automated, -multi-layer image builds based on your unique configurations. Dockerfiles can -start simple and grow with your needs to support more complex scenarios. +Dockerfiles are essential for image builds and can automate multi-layer image builds +based on your configuration. Dockerfiles can start simple and grow to support more +complex scenarios. ### Filename -The default filename to use for a Dockerfile is `Dockerfile`, without a file -extension. Using the default name allows you to run the `docker build` command -without having to specify additional command flags. +The default filename for a Dockerfile is `Dockerfile`, without a file extension. Using +the default name lets you run the `docker build` command without extra flags. -Some projects may need distinct Dockerfiles for specific purposes. A common +Some projects need different Dockerfiles for specific purposes. A common convention is to name these `.Dockerfile`. You can specify the -Dockerfile filename using the `--file` flag for the `docker build` command. -Refer to the -[`docker build` CLI reference](/reference/cli/docker/buildx/build.md#file) -to learn about the `--file` flag. +Dockerfile filename using the `--file` flag with the `docker build` command. See the +[`docker build` CLI reference](/reference/cli/docker/buildx/build.md#file) for details. > [!NOTE] -> -> We recommend using the default (`Dockerfile`) for your project's primary -> Dockerfile. +> We recommend using the default (`Dockerfile`) for your project's main Dockerfile. ## Docker images -Docker images consist of layers. Each layer is the result of a build -instruction in the Dockerfile. Layers are stacked sequentially, and each one is -a delta representing the changes applied to the previous layer. +Docker images consist of layers. Each layer results from a build instruction in the +Dockerfile. Layers are stacked in order, and each one represents changes applied to +the previous layer. ### Example -Here's what a typical workflow for building applications with Docker looks like. +A typical workflow for building applications with Docker: -The following example code shows a small "Hello World" application written in -Python, using the Flask framework. +The following example shows a small "Hello World" application in Python using Flask. ```python from flask import Flask @@ -71,15 +63,14 @@ def hello(): return "Hello World!" ``` -In order to ship and deploy this application without Docker Build, you would -need to make sure that: +Without Docker Build, you need to: -- The required runtime dependencies are installed on the server -- The Python code gets uploaded to the server's filesystem -- The server starts your application, using the necessary parameters +- Install the required runtime dependencies on the server. +- Upload the Python code to the server's filesystem. +- Start your application on the server with the necessary parameters. -The following Dockerfile creates a container image, which has all the -dependencies installed and that automatically starts your application. +The following Dockerfile creates a container image with all dependencies installed and +automatically starts your application. ```dockerfile # syntax=docker/dockerfile:1 @@ -98,7 +89,7 @@ EXPOSE 8000 CMD ["flask", "run", "--host", "0.0.0.0", "--port", "8000"] ``` -Here's a breakdown of what this Dockerfile does: +This Dockerfile does the following: - [Dockerfile syntax](#dockerfile-syntax) - [Base image](#base-image) @@ -112,46 +103,40 @@ Here's a breakdown of what this Dockerfile does: ### Dockerfile syntax -The first line to add to a Dockerfile is a [`# syntax` parser directive](/reference/dockerfile.md#syntax). -While optional, this directive instructs the Docker builder what syntax to use -when parsing the Dockerfile, and allows older Docker versions with [BuildKit enabled](../buildkit/_index.md#getting-started) -to use a specific [Dockerfile frontend](../buildkit/frontend.md) before -starting the build. [Parser directives](/reference/dockerfile.md#parser-directives) -must appear before any other comment, whitespace, or Dockerfile instruction in -your Dockerfile, and should be the first line in Dockerfiles. +The first line is a [`# syntax` parser directive](/reference/dockerfile.md#syntax). +This optional directive tells Docker which syntax to use when parsing the Dockerfile. +It lets older Docker versions with [BuildKit enabled](../buildkit/_index.md#getting-started) +use a specific [Dockerfile frontend](../buildkit/frontend.md) before starting the +build. [Parser directives](/reference/dockerfile.md#parser-directives) must appear +before any other comment, whitespace, or instruction, and should be the first line. ```dockerfile # syntax=docker/dockerfile:1 ``` > [!TIP] -> -> We recommend using `docker/dockerfile:1`, which always points to the latest -> release of the version 1 syntax. BuildKit automatically checks for updates of -> the syntax before building, making sure you are using the most current version. +> Use `docker/dockerfile:1` to always get the latest version 1 syntax. BuildKit +> checks for updates before building, so you use the most current version. ### Base image -The line following the syntax directive defines what base image to use: +The next line defines the base image: ```dockerfile FROM ubuntu:22.04 ``` The [`FROM` instruction](/reference/dockerfile.md#from) sets your base -image to the 22.04 release of Ubuntu. All instructions that follow are executed -in this base image: an Ubuntu environment. The notation `ubuntu:22.04`, follows -the `name:tag` standard for naming Docker images. When you build images, you -use this notation to name your images. There are many public images you can -leverage in your projects, by importing them into your build steps using the -Dockerfile `FROM` instruction. +image to Ubuntu 22.04. All following instructions run in this Ubuntu environment. The +`ubuntu:22.04` notation follows the `name:tag` standard for Docker images. You can +use many public images in your projects by importing them with the `FROM` instruction. [Docker Hub](https://hub.docker.com/search?image_filter=official&q=&type=image) -contains a large set of official images that you can use for this purpose. +offers many official images you can use. ### Environment setup -The following line executes a build command inside the base image. +This line runs a build command inside the base image. ```dockerfile # install app dependencies @@ -164,23 +149,17 @@ the container. ### Comments -Note the `# install app dependencies` line. This is a comment. Comments in -Dockerfiles begin with the `#` symbol. As your Dockerfile evolves, comments can -be instrumental to document how your Dockerfile works for any future readers -and editors of the file, including your future self! +The `# install app dependencies` line is a comment. Comments in Dockerfiles start +with `#`. Comments help document your Dockerfile for future readers and editors. > [!NOTE] -> -> You might've noticed that comments are denoted using the same symbol as the -> [syntax directive](#dockerfile-syntax) on the first line of the file. -> The symbol is only interpreted as a directive if the pattern matches a -> directive and appears at the beginning of the Dockerfile. Otherwise, it's -> treated as a comment. +> Comments use the same symbol as the [syntax directive](#dockerfile-syntax) on the +> first line. The symbol is only a directive if it matches a directive pattern and is +> at the start of the Dockerfile. Otherwise, it is a comment. ### Installing dependencies -The second `RUN` instruction installs the `flask` dependency required by the -Python application. +The second `RUN` instruction installs the `flask` dependency for the Python app. ```dockerfile RUN pip install flask==3.0.* @@ -194,7 +173,7 @@ use the command to install the flask web framework. The next instruction uses the [`COPY` instruction](/reference/dockerfile.md#copy) to copy the -`hello.py` file from the local build context into the root directory of our image. +`hello.py` file from the local build context into the root directory of our image. ```dockerfile COPY hello.py / @@ -215,9 +194,8 @@ in your Docker build using the [`ENV` instruction](/reference/dockerfile.md#env) ENV FLASK_APP=hello ``` -This sets a Linux environment variable we'll need later. Flask, the framework -used in this example, uses this variable to start the application. Without this, -flask wouldn't know where to find our application to be able to run it. +This sets a Linux environment variable needed by Flask to start the app. Without this, +Flask cannot find the app to run it. ### Exposed ports diff --git a/content/manuals/build/concepts/overview.md b/content/manuals/build/concepts/overview.md index e8a101e649f..727ee752806 100644 --- a/content/manuals/build/concepts/overview.md +++ b/content/manuals/build/concepts/overview.md @@ -8,65 +8,71 @@ aliases: - /build/architecture/ --- -Docker Build implements a client-server architecture, where: +Docker Build uses a client-server architecture with two main components: -- Client: Buildx is the client and the user interface for running and managing builds. -- Server: BuildKit is the server, or builder, that handles the build execution. +- **Client**: Buildx serves as the user interface for running and managing builds +- **Server**: BuildKit handles the actual build execution -When you invoke a build, the Buildx client sends a build request to the -BuildKit backend. BuildKit resolves the build instructions and executes the -build steps. The build output is either sent back to the client or uploaded to -a registry, such as Docker Hub. +## How Docker Build works -Buildx and BuildKit are both installed with Docker Desktop and Docker Engine -out-of-the-box. When you invoke the `docker build` command, you're using Buildx -to run a build using the default BuildKit bundled with Docker. +When you invoke a build: + +1. Buildx (client) sends a build request to BuildKit (backend). +2. BuildKit resolves build instructions and executes build steps. +3. Build output returns to the client or uploads to a registry like Docker Hub. + +Both Buildx and BuildKit come pre-installed with Docker Desktop and Docker Engine. +The `docker build` command uses the default BuildKit bundled with Docker. ## Buildx -Buildx is the CLI tool that you use to run builds. The `docker build` command -is a wrapper around Buildx. When you invoke `docker build`, Buildx interprets -the build options and sends a build request to the BuildKit backend. +Buildx is the CLI tool for running builds. The `docker build` command +is a wrapper around Buildx functionality. + +When you run `docker build`, Buildx: + +- Interprets your build options +- Sends build requests to BuildKit backend +- Manages build execution + +Beyond running builds, Buildx enables you to: + +- Create and manage BuildKit backends (builders) +- Manage images in registries +- Run multiple builds concurrently +- Access advanced build features + -The Buildx client can do more than just run builds. You can also use Buildx to -create and manage BuildKit backends, referred to as builders. It also supports -features for managing images in registries, and for running multiple builds -concurrently. +Docker Buildx comes installed by default with Docker Desktop. For manual installation, you can: -Docker Buildx is installed by default with Docker Desktop. You can also build -the CLI plugin from source, or grab a binary from the GitHub repository and -install it manually. See [Buildx README](https://github.com/docker/buildx#manual-download) -on GitHub for more information. +- Build the CLI plugin from source. +- Download a binary from the [GitHub repository](https://github.com/docker/buildx#manual-download). > [!NOTE] -> While `docker build` invokes Buildx under the hood, there are subtle -> differences between this command and the canonical `docker buildx build`. -> For details, see [Difference between `docker build` and `docker buildx build`](../builders/_index.md#difference-between-docker-build-and-docker-buildx-build). +> The `docker build` command differs slightly from `docker buildx build`. +> See [build command differences](../builders/_index.md#difference-between-docker-build-and-docker-buildx-build) for details. ## BuildKit -BuildKit is the daemon process that executes the build workloads. +BuildKit is the daemon process that executes build workloads. -A build execution starts with the invocation of a `docker build` command. -Buildx interprets your build command and sends a build request to the BuildKit -backend. The build request includes: +A build execution starts when you run a `docker build` command. Buildx interprets +your command and sends a build request to BuildKit. The build request includes: - The Dockerfile - Build arguments - Export options - Caching options -BuildKit resolves the build instructions and executes the build steps. While -BuildKit is executing the build, Buildx monitors the build status and prints -the progress to the terminal. +BuildKit resolves the build instructions and executes the build steps. While BuildKit +executes the build, Buildx monitors the build status and prints progress to the terminal. -If the build requires resources from the client, such as local files or build -secrets, BuildKit requests the resources that it needs from Buildx. +If the build needs resources from the client, such as local files or build secrets, +BuildKit requests only the resources it needs from Buildx. -This is one way in which BuildKit is more efficient compared to the legacy -builder used in earlier versions of Docker. BuildKit only requests the -resources that the build needs when they're needed. The legacy builder, in -comparison, always takes a copy of the local filesystem. +BuildKit is more efficient than the legacy builder used in earlier Docker versions. +BuildKit requests resources only when needed. The legacy builder always copies the +local filesystem. Examples of resources that BuildKit can request from Buildx include: From f69abf1741f0d1f91677401ffc29be5365cfe3ec Mon Sep 17 00:00:00 2001 From: Arthur Date: Mon, 28 Jul 2025 17:14:15 +0200 Subject: [PATCH 03/11] Update content/manuals/build/concepts/context.md Co-authored-by: CrazyMax <1951866+crazy-max@users.noreply.github.com> --- content/manuals/build/concepts/context.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/manuals/build/concepts/context.md b/content/manuals/build/concepts/context.md index 667a28c0ff3..245e9142e7c 100644 --- a/content/manuals/build/concepts/context.md +++ b/content/manuals/build/concepts/context.md @@ -437,7 +437,7 @@ improving build speed, especially when using a remote builder. When you run a build command, the build client looks for a file named `.dockerignore` in the root directory of the context. If this file exists, files and directories that match patterns in the file are removed from the build context -before Docker sends them to the builder. +before it sends them to the builder. If you use multiple Dockerfiles, you can use different ignore files for each Dockerfile. Use a special naming convention for these ignore files. Place your From 1cc93cae460c68285e995e27b78cf4c4844fe8c0 Mon Sep 17 00:00:00 2001 From: Arthur Date: Mon, 28 Jul 2025 17:14:29 +0200 Subject: [PATCH 04/11] Update content/manuals/build/concepts/context.md Co-authored-by: CrazyMax <1951866+crazy-max@users.noreply.github.com> --- content/manuals/build/concepts/context.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/manuals/build/concepts/context.md b/content/manuals/build/concepts/context.md index 245e9142e7c..1e84fd975fb 100644 --- a/content/manuals/build/concepts/context.md +++ b/content/manuals/build/concepts/context.md @@ -439,7 +439,7 @@ When you run a build command, the build client looks for a file named and directories that match patterns in the file are removed from the build context before it sends them to the builder. -If you use multiple Dockerfiles, you can use different ignore files for each +If you use multiple Dockerfiles, you can use different ignore-files for each Dockerfile. Use a special naming convention for these ignore files. Place your ignore file in the same directory as the Dockerfile, and prefix the ignore file with the name of the Dockerfile, as shown in the following example. From 34d85d27df4c9565af40c34d82af3ff3a6c40056 Mon Sep 17 00:00:00 2001 From: Arthur Date: Mon, 28 Jul 2025 17:14:43 +0200 Subject: [PATCH 05/11] Update content/manuals/build/concepts/context.md Co-authored-by: CrazyMax <1951866+crazy-max@users.noreply.github.com> --- content/manuals/build/concepts/context.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/manuals/build/concepts/context.md b/content/manuals/build/concepts/context.md index 1e84fd975fb..b6dd8f7406f 100644 --- a/content/manuals/build/concepts/context.md +++ b/content/manuals/build/concepts/context.md @@ -715,7 +715,7 @@ where you have two Dockerfiles: - `base.Dockerfile`: for building a base image - `app.Dockerfile`: for building an application image -The `app.Dockerfile` uses the image produced by its `base.Dockerfile` as its base +The `app.Dockerfile` uses the image produced by `base.Dockerfile` as its base image: ```dockerfile {title=app.Dockerfile} From f1a67bbabbc7b1cb411bc7a94446604dae9c87f9 Mon Sep 17 00:00:00 2001 From: Arthur Date: Mon, 28 Jul 2025 17:15:02 +0200 Subject: [PATCH 06/11] Update content/manuals/build/concepts/dockerfile.md Co-authored-by: CrazyMax <1951866+crazy-max@users.noreply.github.com> --- content/manuals/build/concepts/dockerfile.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/manuals/build/concepts/dockerfile.md b/content/manuals/build/concepts/dockerfile.md index 0abde87a501..8a66967581e 100644 --- a/content/manuals/build/concepts/dockerfile.md +++ b/content/manuals/build/concepts/dockerfile.md @@ -2,7 +2,7 @@ title: Dockerfile overview weight: 20 description: Learn how to use Dockerfiles to build and package your software into Docker images. -keywords: dockerfile, docker build, buildx, buildkit, container image, getting started, image layers, dockerfile instructions +keywords: dockerfile, docker build, buildx, buildkit, container image, getting started, image layers, dockerfile, instructions aliases: - /build/hellobuild/ - /build/building/packaging/ From c08360da795bfeded6cd5525413711aa7cd3bf8a Mon Sep 17 00:00:00 2001 From: Arthur Date: Mon, 28 Jul 2025 17:15:17 +0200 Subject: [PATCH 07/11] Update content/manuals/build/concepts/dockerfile.md Co-authored-by: CrazyMax <1951866+crazy-max@users.noreply.github.com> --- content/manuals/build/concepts/dockerfile.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/manuals/build/concepts/dockerfile.md b/content/manuals/build/concepts/dockerfile.md index 8a66967581e..0e31162e6ab 100644 --- a/content/manuals/build/concepts/dockerfile.md +++ b/content/manuals/build/concepts/dockerfile.md @@ -34,7 +34,7 @@ complex scenarios. The default filename for a Dockerfile is `Dockerfile`, without a file extension. Using the default name lets you run the `docker build` command without extra flags. -Some projects need different Dockerfiles for specific purposes. A common +Some projects may need distinct Dockerfiles for specific purposes. A common convention is to name these `.Dockerfile`. You can specify the Dockerfile filename using the `--file` flag with the `docker build` command. See the [`docker build` CLI reference](/reference/cli/docker/buildx/build.md#file) for details. From 00ac5d0828e39b44d2f2f37a7ae2341454db8d7b Mon Sep 17 00:00:00 2001 From: Arthur Date: Mon, 28 Jul 2025 17:19:58 +0200 Subject: [PATCH 08/11] Update content/manuals/build/concepts/dockerfile.md Co-authored-by: CrazyMax <1951866+crazy-max@users.noreply.github.com> --- content/manuals/build/concepts/dockerfile.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/manuals/build/concepts/dockerfile.md b/content/manuals/build/concepts/dockerfile.md index 0e31162e6ab..2c609d271e5 100644 --- a/content/manuals/build/concepts/dockerfile.md +++ b/content/manuals/build/concepts/dockerfile.md @@ -127,7 +127,7 @@ FROM ubuntu:22.04 ``` The [`FROM` instruction](/reference/dockerfile.md#from) sets your base -image to Ubuntu 22.04. All following instructions run in this Ubuntu environment. The +image to the 22.04 release of Ubuntu. All following instructions run in this Ubuntu environment. The `ubuntu:22.04` notation follows the `name:tag` standard for Docker images. You can use many public images in your projects by importing them with the `FROM` instruction. From b6ec4c16caec8e35015de730f23a855f0cb47b63 Mon Sep 17 00:00:00 2001 From: Arthur Date: Mon, 28 Jul 2025 17:25:51 +0200 Subject: [PATCH 09/11] feedback --- content/manuals/build/concepts/dockerfile.md | 23 +++++++++----------- 1 file changed, 10 insertions(+), 13 deletions(-) diff --git a/content/manuals/build/concepts/dockerfile.md b/content/manuals/build/concepts/dockerfile.md index 2c609d271e5..0670f7d5ea8 100644 --- a/content/manuals/build/concepts/dockerfile.md +++ b/content/manuals/build/concepts/dockerfile.md @@ -25,9 +25,9 @@ Here are the most common types of instructions: | [`COPY `](/reference/dockerfile.md#copy) | Copies new files or directories from `` and adds them to the container at the path ``. | | [`CMD `](/reference/dockerfile.md#cmd) | Defines the default program that runs when you start the container. Only the last `CMD` in the Dockerfile is used if multiple exist. | -Dockerfiles are essential for image builds and can automate multi-layer image builds -based on your configuration. Dockerfiles can start simple and grow to support more -complex scenarios. +Dockerfiles are crucial inputs for image builds and can facilitate automated, +multi-layer image builds based on your unique configurations. Dockerfiles can +start simple and grow with your needs to support more complex scenarios. ### Filename @@ -44,9 +44,9 @@ Dockerfile filename using the `--file` flag with the `docker build` command. See ## Docker images -Docker images consist of layers. Each layer results from a build instruction in the -Dockerfile. Layers are stacked in order, and each one represents changes applied to -the previous layer. +Docker images consist of layers. Each layer is the result of a build +instruction in the Dockerfile. Layers are stacked sequentially, and each one is +a delta representing the changes applied to the previous layer. ### Example @@ -149,13 +149,10 @@ the container. ### Comments -The `# install app dependencies` line is a comment. Comments in Dockerfiles start -with `#`. Comments help document your Dockerfile for future readers and editors. - -> [!NOTE] -> Comments use the same symbol as the [syntax directive](#dockerfile-syntax) on the -> first line. The symbol is only a directive if it matches a directive pattern and is -> at the start of the Dockerfile. Otherwise, it is a comment. +Note the `# install app dependencies` line. This is a comment. Comments in +Dockerfiles begin with the `#` symbol. As your Dockerfile evolves, comments can +be instrumental to document how your Dockerfile works for any future readers +and editors of the file, including your future self! ### Installing dependencies From c2a03f8c20d396309f912c5825509dd4fabb8937 Mon Sep 17 00:00:00 2001 From: Arthur Date: Mon, 28 Jul 2025 17:26:13 +0200 Subject: [PATCH 10/11] Apply suggestion from @crazy-max Co-authored-by: CrazyMax <1951866+crazy-max@users.noreply.github.com> --- content/manuals/build/concepts/dockerfile.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/manuals/build/concepts/dockerfile.md b/content/manuals/build/concepts/dockerfile.md index 0670f7d5ea8..e8def781709 100644 --- a/content/manuals/build/concepts/dockerfile.md +++ b/content/manuals/build/concepts/dockerfile.md @@ -23,7 +23,7 @@ Here are the most common types of instructions: | [`RUN `](/reference/dockerfile.md#run) | Executes commands in a new layer on top of the current image and commits the result. `RUN` also has a shell form for running commands. | | [`WORKDIR `](/reference/dockerfile.md#workdir) | Sets the working directory for any `RUN`, `CMD`, `ENTRYPOINT`, `COPY`, and `ADD` instructions that follow it in the Dockerfile. | | [`COPY `](/reference/dockerfile.md#copy) | Copies new files or directories from `` and adds them to the container at the path ``. | -| [`CMD `](/reference/dockerfile.md#cmd) | Defines the default program that runs when you start the container. Only the last `CMD` in the Dockerfile is used if multiple exist. | +| [`CMD `](/reference/dockerfile.md#cmd) | Defines the default program that runs when you start the container based on this image. Only the last `CMD` in the Dockerfile is used if multiple exist. | Dockerfiles are crucial inputs for image builds and can facilitate automated, multi-layer image builds based on your unique configurations. Dockerfiles can From a5452985c229d17c617bf9c4e1275c7bfb20bfb7 Mon Sep 17 00:00:00 2001 From: Arthur Date: Mon, 28 Jul 2025 17:29:15 +0200 Subject: [PATCH 11/11] update line length --- .github/prompts/freshness-tier1.prompt.md | 2 +- .github/prompts/freshness-tier2.prompt.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/prompts/freshness-tier1.prompt.md b/.github/prompts/freshness-tier1.prompt.md index 194df8238fc..23c7d893502 100644 --- a/.github/prompts/freshness-tier1.prompt.md +++ b/.github/prompts/freshness-tier1.prompt.md @@ -12,6 +12,6 @@ how fresh and up to date it is. Apply the following: 5. Ensure all the components formatted correctly. 6. Improve the SEO keywords. 7. If you find numbered lists, make sure their numbering only uses 1's. -8. Keep line length to a maximum of 90 characters, and do not add a space character at the end of lines. +8. Keep line length to a maximum of approximately 80 characters and do not add a space character at the end of lines. Do your best and don't be lazy. \ No newline at end of file diff --git a/.github/prompts/freshness-tier2.prompt.md b/.github/prompts/freshness-tier2.prompt.md index 6457ea9990f..604df049c0f 100644 --- a/.github/prompts/freshness-tier2.prompt.md +++ b/.github/prompts/freshness-tier2.prompt.md @@ -18,6 +18,6 @@ how fresh and up to date it is. Apply the following: 5. Try to add some helpful next steps to the end of the document, but only if there are no *Next steps* or *Related pages* section, already. 6. Try to clarify, shorten or improve the efficiency of some sentences. 7. Check for LLM readability. -8. Keep line length to a maximum of 90 characters. +8. Keep line length to a maximum of approximately 80 characters. Do your best and don't be lazy. \ No newline at end of file