build: freshness

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 >}}

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 it 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.
+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 `base.Dockerfile` as its base
 image:
 
 ```dockerfile {title=app.Dockerfile}

content/manuals/build/concepts/dockerfile.md

@@ -1,53 +1,46 @@
 ---
 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/
 ---
 
 ## 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 <image>`](/reference/dockerfile.md#from)           | Defines a base for your image.                                                                                                                                                                           |
-| [`RUN <command>`](/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 <directory>`](/reference/dockerfile.md#workdir) | Sets the working directory for any `RUN`, `CMD`, `ENTRYPOINT`, `COPY`, and `ADD` instructions that follow it in the Dockerfile.                                                                          |
-| [`COPY <src> <dest>`](/reference/dockerfile.md#copy)      | Copies new files or directories from `<src>` and adds them to the filesystem of the container at the path `<dest>`.                                                                                      |
-| [`CMD <command>`](/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 <image>`](/reference/dockerfile.md#from)           | Defines a base for your image.                                                                                                         |
+| [`RUN <command>`](/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 <directory>`](/reference/dockerfile.md#workdir) | Sets the working directory for any `RUN`, `CMD`, `ENTRYPOINT`, `COPY`, and `ADD` instructions that follow it in the Dockerfile.        |
+| [`COPY <src> <dest>`](/reference/dockerfile.md#copy)      | Copies new files or directories from `<src>` and adds them to the container at the path `<dest>`.                                      |
+| [`CMD <command>`](/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
 start simple and grow with your needs 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
 convention is to name these `<something>.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
 
@@ -57,10 +50,9 @@
 
 ### 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 @@
     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 @@
 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 @@
 
 ### 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 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.
 
 [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
@@ -169,18 +154,9 @@
 be instrumental to document how your Dockerfile works for any future readers
 and editors of the file, including your future self!
 
-> [!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.
-
 ### 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 +170,7 @@
 
 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 +191,8 @@
 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