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..b6dd8f7406f 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 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} diff --git a/content/manuals/build/concepts/dockerfile.md b/content/manuals/build/concepts/dockerfile.md index 18601a9b15d..e8def781709 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,22 +10,20 @@ 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 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 @@ -33,21 +31,16 @@ 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 `.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 @@ a delta representing the 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 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 @@ 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! -> [!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 @@ 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 +191,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: