azure Documentation

1. Project Overview & Quickstart (docker/azure) Copy Chapter

azure

Open-source repository docker/azure

Repository Details Copy Section

• Repository: docker/azure
• Primary Language: Code

Note: High-volume repository documentation is actively indexed and synchronized by YakaAI.

2. Official Technical Reference & Guides (docker/docs) Copy Chapter

File: README.md Copy Chapter

Docs @ Docker

Welcome to the Docker Documentation repository. This is the source for the Docker Docs Website.

Feel free to open pull requests or issues. Our docs are completely open source, and we deeply appreciate contributions from the Docker community!

Provide feedback Copy Chapter

We’d love to hear your feedback! To submit feedback:

• Click New issue on the docs repository, or
• Click Request changes in the right column of every page on
  docs.docker.com, or
• Click Give feedback on every page in the docs.

To get community support, use the Docker Community Slack. Personalized support is available
through the Docker Pro, Team, and Business subscriptions. See Docker
Pricing for details.

If you have an idea for a new feature or behavior change in a specific aspect of
Docker or have found a product bug, file an issue in the project's
repository.

Contribute to Docker docs Copy Chapter

We welcome contributions! To get started:

• CONTRIBUTING.md - Contribution workflow and setup
• STYLE.md - Writing style and content guidelines
• COMPONENTS.md - Component and shortcode usage

Copyright and license Copy Chapter

Copyright 2013-2026 Docker, Inc., released under the Apache 2.0 license.

File: AGENTS.md Copy Chapter

AGENTS.md

Instructions for AI agents working on Docker documentation.
This site builds https://docs.docker.com/ using Hugo.

Project structure Copy Chapter

content/          # Documentation source (Markdown + Hugo front matter)
├── manuals/      # Product docs (Engine, Desktop, Hub, etc.)
├── guides/       # Task-oriented guides
├── reference/    # API and CLI reference
└── includes/     # Reusable snippets
layouts/          # Hugo templates and shortcodes
data/             # YAML data files (CLI reference, etc.)
assets/           # CSS (Tailwind v4) and JS (Alpine.js)
static/           # Images, fonts
_vendor/          # Vendored Hugo modules (read-only)

URL prefix stripping Copy Chapter

The /manuals prefix is stripped from published URLs:
content/manuals/desktop/install.md becomes /desktop/install/ on the live
site.

When writing internal cross-references in source files, keep the /manuals/
prefix in the path — Hugo requires the full source path. The stripping only
affects the published URL, not the internal link target. Anchor links must
exactly match the generated heading ID (Hugo lowercases and slugifies
headings).

Vendored content (do not edit) Copy Chapter

Content in _vendor/ and CLI reference data in data/cli/ are vendored
from upstream repos. Content pages under content/reference/cli/ are
generated from data/cli/ YAML. Do not edit any of these files — changes
must go to the source repository:

If a validation failure or broken link traces back to vendored content, note
the upstream repo that needs fixing. Do not attempt to fix it locally.

content/reference/api/ai-governance/api.yaml is a verbatim copy of the
upstream openapi.yaml — do not edit it by hand. Re-vendor it with
hack/sync-governance-api.sh, which fetches the latest spec from the private
docker/governor-services repo (using your own gh auth).

Writing guidelines Copy Chapter

Read and follow STYLE.md and COMPONENTS.md.
These contain all style rules, shortcode syntax, and front matter requirements.

Style violations to avoid Copy Section

Every piece of writing must avoid these words and patterns (enforced by Vale):

• Hedge words: "simply", "easily", "just", "seamlessly"
• Meta-commentary: "it's worth noting", "it's important to understand"
• "allows you to" or "enables you to" — use "lets you" or rephrase
• "we" — use "you" or "Docker"
• "click" — use "select"
• Bold for emphasis or product names — only bold UI elements
• Time-relative language: "currently", "new", "recently", "now"

Version-introduction notes Copy Section

Explicit version anchors ("Starting with Docker Desktop version X...") are
different from time-relative language — they mark when a feature was
introduced, which is permanently true.

• Recent releases (~6 months): leave version callouts in place
• Old releases: consider removing if the callout adds little value
• When in doubt, keep the callout and flag for maintainer review

Vale gotchas Copy Section

• Use lowercase "config" in prose — vale.Terms flags a capital-C "Config"

Updating the vocabulary Copy Section

If Vale flags a legitimate tech term, product name, or compound identifier
as a misspelling, add it to _vale/config/vocabularies/Docker/accept.txt.
This is optional — only update when a real new term is missing, not to
silence individual violations.

• Use the canonical form for case-sensitive product names (PyTorch,
  GitHub, Kubernetes, BuildKit). Vale.Terms enforces that exact
  case across the docs.
• Use [Aa]bcd character-class regex for words that legitimately appear
  in multiple cases (e.g., sentence-starting capitalization, or a name
  that's also a generic noun). This covers spelling without enforcing
  a single canonical form.
• Avoid broad regex patterns — entries that match many words at once
  (especially with (?i)) suppress other rule checks on every match.
• Don't add a wrong-cased entry to silence one false positive — it
  cascades into Vale.Terms violations on every correct usage.

Human-readable prose Copy Chapter

For PR titles and descriptions, documentation, release notes, design documents,
comments, and other reader-facing prose:

• Write so readers understand the meaning on the first read
• Use wording that an experienced colleague would plausibly say aloud
• Prefer verbs and clauses over invented nouns and compressed noun phrases
• Treat correct grammar as necessary but insufficient for clear writing
• Before returning prose, silently rewrite wording that is technically
  interpretable but unnatural or hard to decode

Keep established technical terms and qualifications needed for accuracy.
Use the write skill's prose review to catch patterns that lint cannot detect.

Alpine.js patterns Copy Chapter

Do not combine Alpine's x-show with the HTML hidden attribute on the
same element. x-show toggles inline display styles, but hidden applies
display: none via the user-agent stylesheet — the element stays hidden
regardless of x-show state. Use x-cloak for pre-Alpine hiding instead.
The site defines [x-cloak=""] { display: none !important } in global.css.

Front matter requirements Copy Chapter

Every content page under content/ requires:

• title: — page title
• description: — short description for SEO/previews
• keywords: — list of search keywords

Additional common fields:

• linkTitle: — sidebar label (keep under 30 chars)
• weight: — ordering within a section

Sidebar navigation Copy Chapter

The section sidebar is rendered by
layouts/_partials/sidebar/sections.html. It starts at .FirstSection and
recursively walks each section's .Pages. Page weight controls the default
order. Section front matter can group entries with sidebar.groups, reverse
their order with sidebar.reverse, override a link with sidebar.goto, and
add a badge with sidebar.badge.

The sidebar expands the current page's ancestor sections and marks the current
page with aria-current. When changing the recursive templates, pass all
navigation state through both renderChildren and renderList. Keep the page
filter and the $hasChildren calculation aligned so an expand control never
points to an empty list or disappears for a rendered list.

Hidden pages Copy Chapter

Set sitemap: false to hide a page from site-wide discovery. This setting:

• Excludes the page from sitemap.xml, metadata.json, and llms-full.txt
• Excludes the page body from the site search index
• Adds a noindex robots meta tag

The page is still built and remains available through direct links. This is
not an access control mechanism.

Hugo does not automatically apply sitemap: false from a section page to its
descendants. To hide an entire subtree, cascade the value from the section's
_index.md:

sitemap: false
cascade:
  sitemap: false

Hidden sections in the sidebar Copy Chapter

The sidebar uses sitemap as a navigation visibility filter. A hidden page is
absent from the sidebar outside its active navigation path. The current page
and its ancestors remain visible so direct links to hidden pages do not produce
an empty navigation path.

When the active path enters a hidden section, revealHidden propagates down
that branch and renders the whole hidden subtree. This keeps the section's
navigation available while you are in it. The state must remain scoped to that
branch so unrelated hidden pages stay hidden.

Hugo shortcodes Copy Chapter

Shortcodes are defined in layouts/shortcodes/. Syntax reference is in
COMPONENTS.md. Wrong shortcode syntax fails silently during build but
produces broken HTML — always check COMPONENTS.md for correct syntax.

Commands Copy Chapter

npx --no-install rumdl fmt <file>  # Format Markdown before committing
npx prettier --write <file>        # Format non-Markdown files
scripts/lint.sh <markdown-file>... # Lint specific files (rumdl + Vale)
docker buildx bake validate        # Run all validation checks
docker buildx bake lint            # Markdown linting only
docker buildx bake vale            # Style guide checks only
docker buildx bake test            # HTML and link checking

npx --no-install uses the repository-pinned rumdl binary and never downloads
a replacement. If the binary is unavailable, run npm ci to install the
repository dependencies. Install Vale separately.

For incremental work, prefer scripts/lint.sh over the bake targets. Pass
only the Markdown files you changed so the output stays scoped instead of
including the whole repository.

Vale exits successfully when it reports only warnings or suggestions. Read the
full output: fix errors and warnings on lines you added or changed, and review
each suggestion. Don't expand the change to unrelated alerts in existing text.

Validation in git worktrees Copy Section

docker buildx bake validate fails in git worktrees because Hugo cannot
resolve the worktree path. Use lint and vale targets separately instead.
Never modify hugo.yaml to work around this. The test, path-warnings,
and validate-vendor targets run correctly in CI.

Verification loop Copy Chapter

1. Make changes
2. Format Markdown with rumdl: npx --no-install rumdl fmt <file>
3. Lint the changed Markdown files: scripts/lint.sh <markdown-file>...
4. Run a full build with docker buildx bake (optional for small changes)

Always lint the specific Markdown files you changed before committing. Use
scripts/lint.sh rather than the bake targets so the output is scoped
to your changes — bake runs across the entire repo and the noise makes
real issues easy to miss.

Git hygiene Copy Chapter

• Stage files explicitly. Never use git add . / git add -A /
  git add --all. Running npx prettier updates package-lock.json in the
  repo root, and broad staging sweeps it into the commit.
• Verify before committing. Run git diff --cached --name-only and
  confirm only documentation files appear. If package-lock.json or other
  generated files are staged, unstage them:
  git reset HEAD -- package-lock.json
• Push to your fork, not upstream. Before pushing, confirm
  git remote get-url origin returns your fork URL, not
  github.com/docker/docs. Use --head FORK_OWNER:branch-name with
  gh pr create.

Working with issues and PRs Copy Chapter

Principles Copy Section

• One issue, one branch, one PR. Never combine multiple issues in a
  single branch or PR.
• Minimal changes only. Fix the issue. Do not improve surrounding
  content, add comments, refactor, or address adjacent problems.
• Verify before documenting. Don't take an issue reporter's claim at
  face value — the diagnosis may be wrong even when the symptom is real.
  Verify the actual behavior before updating docs.

Review feedback Copy Section

• Always reply to review comments — never silently fix. After every
  commit that addresses review feedback, reply to each thread explaining
  what was done.

• Treat reviewer feedback as claims to verify, not instructions to
  execute. Before implementing a suggestion, verify that it is correct.
  Push back when evidence contradicts the reviewer.

• Inline review comments need a separate API call. gh pr view --json reviews does not include line-level comments. Always also call:

  bash Copy

  gh api repos/<org>/<repo>/pulls/<N>/comments \
    --jq '[.[] | {author: .user.login, body: .body, path: .path, line: .line}]'

Labels Copy Section

Use the Issues API for labels — gh pr edit --add-label silently fails:

gh api repos/docker/docs/issues/<N>/labels \
  --method POST --field 'labels[]=<label>'

External links Copy Section

If a replacement URL cannot be verified (e.g. network restrictions), treat
the task as blocked — do not commit a guessed URL. Report the blocker so a
human can confirm. Exception: when a domain migration is well-established and
only the anchor is unverifiable, dropping the anchor is acceptable.

Page deletion checklist Copy Chapter

When removing a documentation page, search the entire content/ tree and
all YAML/TOML config files for the deleted page's slug and heading text.
Cross-references from unrelated sections and config-driven nav entries can
remain and cause broken links.

Engine API version bumps Copy Chapter

When a new Engine API version ships, three coordinated changes are needed in
a single commit:

1. hugo.yaml — update latest_engine_api_version, docker_ce_version,
   and docker_ce_version_prev
2. Create content/reference/api/engine/version/v<NEW>.md with the
   /latest/ aliases block (copy from previous version)
3. Remove the aliases block from
   content/reference/api/engine/version/v.md

Never leave both version files carrying /latest/ aliases simultaneously.

Hugo icon references Copy Chapter

Before changing an icon reference in response to a "file not found" error,
verify the file actually exists via Hugo's virtual filesystem. Files may
exist in node_modules/@material-symbols/svg-400/rounded/ but not directly
in assets/icons/. Check both locations before concluding an icon is
missing.

Self-improvement Copy Chapter

After completing work that reveals a non-obvious pattern or repo quirk not
already documented here, propose an update to this file. For automated
sessions, note the learning in a comment on the issue. For human-supervised
sessions, discuss with the user whether to update CLAUDE.md directly.

File: COMPONENTS.md Copy Chapter

Docker Documentation Components Guide

This guide explains how to use components, shortcodes, and special features
when writing Docker documentation. For writing style and grammar, see
STYLE.md.

Front matter Copy Chapter

Every documentation page requires front matter at the top of the file.

Required fields Copy Section

---
title: Install Docker Engine on Ubuntu
description: Instructions for installing Docker Engine on Ubuntu
keywords: requirements, apt, installation, ubuntu
---

Optional fields Copy Section

Example with optional fields Copy Section

---
title: Install Docker Engine on Ubuntu
linkTitle: Install on Ubuntu
description: Instructions for installing Docker Engine on Ubuntu
keywords: requirements, apt, installation, ubuntu, install, uninstall
weight: 10
aliases:
  - /engine/installation/linux/ubuntu/
  - /install/linux/ubuntu/
toc_max: 4
params:
  sidebar:
    badge:
      color: blue
      text: Beta
---

Series (guide) pages Copy Section

Section pages under content/guides/ automatically use the series layout
(via a Hugo cascade in hugo.yaml). Series pages support additional front
matter parameters for the metadata card:

---
title: Getting started
description: Learn the basics of Docker
summary: |
  A longer summary shown on the series landing page.
params:
  proficiencyLevel: Beginner
  time: 15 minutes
  prerequisites: None
---

Catalog navigation Copy Section

Set params.sidebar.activeChildrenOnly: true on a section to show only its
active child in the sidebar. Other children remain available in search and
the sitemap. Sidebar group headings are omitted in this mode.

For a recipe catalog, set params.recipeCatalog: true on the section to add
a Browse all recipes link to each recipe page.

Shortcodes Copy Chapter

Shortcodes are reusable components that add rich functionality to your
documentation.

Tabs Copy Section

Use tabs for platform-specific instructions or content variations.

Example:

{{< tabs >}}
{{< tab name="Linux" >}}

$ docker run hello-world

{{< /tab >}}
{{< tab name="macOS" >}}

$ docker run hello-world

{{< /tab >}}
{{< tab name="Windows" >}}

docker run hello-world

{{< /tab >}}
{{< /tabs >}}

Syntax:

{{</* tabs */>}}
{{</* tab name="Linux" */>}}
Content for Linux
{{</* /tab */>}}
{{</* tab name="macOS" */>}}
Content for macOS
{{</* /tab */>}}
{{</* /tabs */>}}

Tab groups (synchronized selection):

Use the group attribute to synchronize tab selection across multiple tab
sections:

{{</* tabs group="os" */>}}
{{</* tab name="Linux" */>}}
Linux content for first section
{{</* /tab */>}}
{{</* tab name="macOS" */>}}
macOS content for first section
{{</* /tab */>}}
{{</* /tabs */>}}

{{</* tabs group="os" */>}}
{{</* tab name="Linux" */>}}
Linux content for second section
{{</* /tab */>}}
{{</* tab name="macOS" */>}}
macOS content for second section
{{</* /tab */>}}
{{</* /tabs */>}}

When a user selects "Linux" in the first section, all tabs in the "os" group
switch to "Linux".

Accordion Copy Section

Use accordions for collapsible content like optional steps or advanced
configuration.

Example:

{{< accordion title="Advanced configuration" >}}

version: "3.8"
services:
  web:
    build: .
    ports:
      - "8000:8000"

{{< /accordion >}}

Syntax:

{{</* accordion title="Advanced configuration" */>}}
Content inside the accordion
{{</* /accordion */>}}

Include Copy Section

Reuse content across multiple pages using the include shortcode. Include
files must be in the content/includes/ directory.

Syntax:

{{</* include "filename.md" */>}}

Example:

{{</* include "install-prerequisites.md" */>}}

Badges Copy Section

Use badges to highlight new, beta, experimental, or deprecated content.

Example:

{{< badge color=blue text="Beta" >}}
{{< badge color=violet text="Experimental" >}}
{{< badge color=green text="New" >}}
{{< badge color=gray text="Deprecated" >}}

Syntax:

Inline badge:

{{</* badge color=blue text="Beta" */>}}

Badge as link:

[{{</* badge color=blue text="Beta feature" */>}}](link-to-page.md)

Sidebar badge (in front matter):

---
title: Page title
params:
  sidebar:
    badge:
      color: violet
      text: Experimental
---

Color options:

• blue - Beta content
• violet - Experimental or early access
• green - New GA content
• amber - Warning or attention
• red - Critical
• gray - Deprecated

Usage guidelines:

• Use badges for no longer than 2 months post-release
• Use violet for experimental/early access features
• Use blue for beta features
• Use green for new GA features
• Use gray for deprecated features

Setting metadata Copy Section

Use setting-metadata below a setting's heading to display its type, default,
and optional environment variable. Keep explanations and examples in the page
body. The component uses a definition list with wrapping values and preserves
the metadata in Markdown output.

{{</* setting-metadata
  type="boolean"
  default="false"
  env="DOCKER_SANDBOXES_CLIPBOARD_IMAGE_PASTE"
*/>}}

The type and default parameters are required. Omit env when the setting
has no environment variable equivalent. Use default="Empty string" for an
empty string default.

Summary bars Copy Section

Summary bars indicate subscription requirements, version requirements, or
administrator-only features at the top of a page.

Example:

{{< summary-bar feature_name="Docker Scout" >}}

Setup:

1. Add feature to /data/summary.yaml:

features:
  Docker Scout:
    subscription: Business
    availability: GA
    requires: "Docker Desktop 4.17 or later"

2. Add shortcode to page:

{{</* summary-bar feature_name="Docker Scout" */>}}

Attributes in summary.yaml:

Buttons Copy Section

Create styled buttons for calls to action.

Syntax:

{{</* button text="Download Docker Desktop" url="/get-docker/" */>}}

Copy as prompt Copy Section

Wrap a section with copy-as-prompt to add a Copy as prompt button. The
button copies the instruction followed by the section's source Markdown.
The section remains visible and appears in the page's Markdown output.

{{</* copy-as-prompt instruction="Update this project using the migration reference below." */>}}
Migration reference content
{{</* /copy-as-prompt */>}}

Cards Copy Section

Create card layouts for organizing content.

Syntax:

{{</* card
  title="Get started"
  description="Learn Docker basics"
  link="/get-started/"
*/>}}

Recipe lists Copy Section

List a section's recipes by their params.sidebar.group value:

{{</* recipe-list group="Working in a sandbox" */>}}

The list uses each page's sidebar title and description, ordered by page
weight. It renders in two columns on larger screens and one column on smaller
screens. The Markdown output includes the same links and descriptions.

Icons Copy Section

Use Material Symbols icons in your content.

Syntax:

{{</* icon name="check_circle" */>}}

Browse available icons at
Material Symbols.

Callouts Copy Chapter

Use GitHub-style callouts to emphasize important information. Use sparingly -
only when information truly deserves special emphasis.

Syntax:

> [!NOTE]
> This is a note with helpful context.

> [!TIP]
> This is a helpful suggestion or best practice.

> [!IMPORTANT]
> This is critical information users must understand.

> [!WARNING]
> This warns about potential issues or consequences.

> [!CAUTION]
> This is for dangerous operations requiring extreme care.

When to use each type:

Code blocks Copy Chapter

Format code with syntax highlighting using triple backticks and language
hints.

Language hints Copy Section

Common language hints:

• console - Interactive shell with $ prompt
• bash - Bash scripts
• dockerfile - Dockerfiles
• yaml - YAML files
• json - JSON data
• go, python, javascript - Programming languages
• powershell - PowerShell commands

Interactive shell example:

```console
$ docker run hello-world
```

Bash script example:

```bash
#!/usr/bin/bash
echo "Hello from Docker"
```

Variables in code Copy Section

Use <VARIABLE_NAME> format for placeholder values:

```console
$ docker tag  <REGISTRY>/:<TAG>
```

This syntax renders variables in a special color and font style.

Highlighting lines Copy Section

Highlight specific lines with hl_lines:

```go {hl_lines=[3,4]}
func main() {
    fmt.Println("Hello")
    fmt.Println("This line is highlighted")
    fmt.Println("This line is highlighted")
}
```

Collapsible code blocks Copy Section

Make long code blocks collapsible:

```dockerfile {collapse=true}
# syntax=docker/dockerfile:1
FROM golang:1.21-alpine
RUN apk add --no-cache git
# ... more lines
```

Images Copy Chapter

Add images using standard Markdown syntax with optional query parameters for
sizing and borders.

Basic syntax:

![Alt text description](/assets/images/image.png)

With size parameters:

![Alt text](/assets/images/image.png?w=600&h=400)

With border:

![Alt text](/assets/images/image.png?border=true)

Combined parameters:

![Alt text](/assets/images/image.png?w=600&h=400&border=true)

Best practices:

• Store images in /static/assets/images/
• Use descriptive alt text for accessibility
• Compress images before adding to repository
• Capture only relevant UI, avoid unnecessary whitespace
• Use realistic text, not lorem ipsum
• Remove unused images from repository

Videos Copy Chapter

Embed videos using HTML video tags or platform-specific embeds.

Local video:

<video controls width="100%">
  <source src="/assets/videos/demo.mp4" type="video/mp4" />
</video>

YouTube embed:

<iframe
  width="560"
  height="315"
  src="https://www.youtube.com/embed/VIDEO_ID"
  frameborder="0"
  allow="autoplay; encrypted-media"
  allowfullscreen
>
</iframe>

Links Copy Chapter

Use standard Markdown link syntax. For internal links, use relative paths
with source filenames.

External link:

[Docker Hub](https://hub.docker.com/)

Internal link (same section):

[Installation guide](install.md)

Internal link (different section):

[Get started](/get-started/overview.md)

Link to heading:

[Prerequisites](#prerequisites)

Best practices:

• Use descriptive link text (around 5 words)
• Front-load important terms
• Avoid generic text like "click here" or "learn more"
• Don't include end punctuation in link text
• Use relative paths for internal links

Lists Copy Chapter

Unordered lists Copy Section

- First item
- Second item
- Third item
  - Nested item
  - Another nested item

Ordered lists Copy Section

1. First step
2. Second step
3. Third step
   1. Nested step
   2. Another nested step

Best practices Copy Section

• Limit bulleted lists to 5 items when possible
• Don't add commas or semicolons to list item ends
• Capitalize list items for ease of scanning
• Make all list items parallel in structure
• For nested sequential lists, use lowercase letters (a, b, c)

Tables Copy Chapter

Use standard Markdown table syntax with sentence case for headings.

Example:

| Feature        | Description                     | Availability |
| -------------- | ------------------------------- | ------------ |
| Docker Compose | Multi-container orchestration   | All          |
| Docker Scout   | Security vulnerability scanning | Business     |
| Build Cloud    | Remote build service            | Pro, Team    |

Best practices:

• Use sentence case for table headings
• Don't leave cells empty - use "N/A" or "None"
• Align decimals on the decimal point
• Keep tables scannable - avoid dense content

Quick reference Copy Chapter

File structure Copy Section

content/
├── manuals/              # Product documentation
│   ├── docker-desktop/
│   ├── docker-hub/
│   └── ...
├── guides/               # Learning guides
├── reference/            # API and CLI reference
└── includes/             # Reusable content snippets

Common patterns Copy Section

Platform-specific instructions:

Use tabs with consistent names: Linux, macOS, Windows

Optional content:

Use accordions for advanced or optional information

Version/subscription indicators:

Use badges or summary bars

Important warnings:

Use callouts (NOTE, WARNING, CAUTION)

Code examples:

Use console for interactive shells, appropriate language hints for code

File: compose.yaml Copy Chapter

services:
server:
build:
context: .
target: build-base
ports:
- "1313:1313"
entrypoint: ["hugo", "server", "--bind", "0.0.0.0"]
develop:
watch:
- action: sync
path: .
target: /project

File: CONTRIBUTING.md Copy Chapter

Contributing to Docker Documentation

We value documentation contributions from the Docker community. We'd like to
make it as easy as possible for you to work in this repository.

Before contributing, review our documentation standards:

• STYLE.md - Writing style, voice, grammar, and formatting
  guidelines
• COMPONENTS.md - How to use Hugo shortcodes, front matter,
  and components

The following guidelines describe how to contribute to the
Docker documentation at https://docs.docker.com/, and how to get started.

Reporting issues Copy Chapter

If you encounter a problem with the content, or the site in general, feel free
to submit an issue in our
GitHub issue tracker. You can also use
the issue tracker to raise requests on improvements, or suggest new content
that you think is missing or that you would like to see.

Editing content Copy Chapter

The website is built using Hugo. The content is primarily
Markdown files in the /content directory of this repository (with a few
exceptions, see Content not edited here).

The structure of the sidebar navigation on the site is defined by the site's
section hierarchy in the contents directory. The titles of the pages are
defined in the front matter of the Markdown files. You can use title and
linkTitle to define the title of the page. title is used for the page
title, and linkTitle is used for the sidebar title. If linkTitle is not
defined, the title is used for both.

You must fork this repository to create a pull request to propose changes. For more details, see Local setup.

General guidelines Copy Section

Help make reviewing easier by following these guidelines:

• Try not to touch a large number of files in a single PR if possible.
• Don't change whitespace or line wrapping in parts of a file you aren't
  editing for other reasons. Make sure your text editor isn't configured to
  automatically reformat the whole file when saving.
• We use GitHub Actions for testing and creating preview deployments for each
  pull request. The URL of the preview deployment is added as a comment on the
  pull request. Check the staging site to verify how your changes look and fix
  issues, if necessary.

Local setup Copy Section

You can use Docker (surprise) to build and serve the files locally.

[!IMPORTANT]
This requires Docker Desktop version 4.24 or later, or Docker Engine with Docker
Compose version 2.22 or later.

1. Fork the docker/docs repository.

2. Clone your forked docs repository:

   console Copy

   $ git clone https://github.com/<your-username>/docs
   $ cd docs

3. Configure Git to sync your docs fork with the upstream docker/docs
   repository and prevent accidental pushes to the upstream repository:

   console Copy

   $ git remote add upstream https://github.com/docker/docs.git
   $ git remote set-url --push upstream no_pushing

4. Check out a branch:

   console Copy

   $ git checkout -b <branch>

5. Start the local development server:

   console Copy

   $ docker compose watch

The site will be served for local preview at http://localhost:1313. The
development server watches for changes and automatically rebuilds your site.

To stop the development server:

1. In your terminal, press <Ctrl+C> to exit the file watch mode of Compose.
2. Stop the Compose service with the docker compose down command.

[!NOTE]
Alternatively, if you have installed Hugo, you can build with hugo serve.

Testing Copy Section

Before you push your changes and open a pull request, we recommend that you
test your site locally first. Local tests check for broken links, incorrectly
formatted markup, and other things. To run the tests:

$ docker buildx bake validate

If this command doesn't result in any errors, you're good to go!

Content not edited here Copy Chapter

CLI reference documentation is maintained in upstream repositories and
generated from YAML data files in data/cli/. A Hugo content adapter
(content/reference/cli/_content.gotmpl) turns these data files into pages
automatically. To update the CLI reference docs, refer to the corresponding

• docker/cli
• docker/buildx
• docker/compose
• docker/model-runner
• docker/mcp-gateway

Feel free to raise an issue on this repository if you're not sure how to
proceed, and we'll help out.

Other content that appears on the site, but that's not edited here, includes:

• Dockerfile reference
• Docker Engine API reference
• Compose specification
• Buildx Bake reference

If you spot an issue in any of these pages, feel free to raise an issue here
and we'll make sure it gets fixed in the upstream source.

File: hugo.yaml Copy Chapter

title: Docker Docs
baseURL: https://docs.docker.com
refLinksErrorLevel: ERROR
enableGitInfo: true
disablePathToLower: true
enableInlineShortcodes: true
disableHugoGeneratorInject: true
ignoreLogs:

• cascade-pattern-with-extension

taxonomies: {}

security:
exec:
allow:
- ^(dart-)?sass$
- ^go$
- ^git$
- ^node$
- ^postcss$
- ^tailwindcss$

Cascade layout and type settings to content subtrees.

See https://gohugo.io/configuration/cascade/#target

cascade:

Sample pages use the samples type (routes to layouts/samples/)

• target:
  path: /reference/samples/**
  kind: page
  type: samples

CLI reference pages use the cli layout (data-driven from YAML)

• target:
  path: /reference/cli/docker
  layout: cli
• target:
  path: /reference/cli/docker/**
  layout: cli

sbx CLI reference pages use the sbx-cli layout (cobra/doc YAML)

• target:
  path: /reference/cli/sbx
  layout: sbx-cli
• target:
  path: /reference/cli/sbx/**
  layout: sbx-cli

Docker Agent section indexes are mounted navigation stubs; skip

rendering them so they don't produce empty pages (same pattern as

gordon/concepts and other render:never section indexes)

• target:
  path: /manuals/ai/docker-agent/**
  kind: section
  build:
  render: never

Remove the /manuals prefix for content in the manuals section

permalinks:
page:
manuals: /:sections[1:]/:slugorcontentbasename/
section:
manuals: /:sections[1:]/

markup:
tableOfContents:
startLevel: 2
endLevel: 3
goldmark:
extensions:
typographer: false
parser:
wrapStandAloneImageWithinParagraph: false
attribute:
# Allow setting attributes on block-level elements
block: true
renderer:
# Allow inline HTML
unsafe: true
highlight:
# Use custom CSS for syntax highlighting
noClasses: false

build:

Generate hugo_stats.json - Tailwind uses this to detect classes

buildStats:
enable: true
disableIDs: true
disableTags: true

Ensure that CSS/assets changes trigger a dev server rebuild

cachebusters:
- source: assets/notwatching/hugo_stats.json
target: css
- source: (postcss|tailwind).config.js
target: css
- source: assets/..js
target: js
- source: (assets|layouts)/..(.*)$
target: "$2"

Additional output formats (e.g. custom JSON files)

outputFormats:

File containing all redirects, see: layouts/index.redirects.json

redirects:
baseName: redirects
isPlainText: true
mediaType: "application/json"
notAlternative: true

Metadata file used by DD global search, see: layouts/index.metadata.json

metadata:
baseName: metadata
isPlainText: true
mediaType: "application/json"
notAlternative: true

llms.txt

llms:
baseName: llms
isPlainText: true
mediaType: "text/plain"
notAlternative: true
permalinkable: false
llmsfull:
baseName: llms-full
isPlainText: true
mediaType: "text/plain"
notAlternative: true
permalinkable: false

Enable custom output formats

(only generate the custom output files once)

outputs:
home:
- html
- markdown
- redirects
- metadata
- robots
- llms
- llmsfull
page:
- html
- markdown
section:
- html
- markdown

languages:
en:
label: English

Site-wide parameters

Can be accessed in content with {{% param "param_name" %}}

Or in layouts/partials with site.Params.param_name

params:
analytics:
hotjar:
prod: 3169877
stage: 3218181
google: GTM-WL2QLG5
onetrust: 65425fb0-7b36-4317-9f10-7b3e08039af0
marlin:
# Public-write API keys for the Marlin analytics SDK.
apiKey:
prod: mrl_2nuEKUo5bzRv8GcDKeYjij4J4U--OLdN
stage: mrl_W14SGEQ7nYmBsAyjZPyOM-nlgE53E-vX
endpoint:
prod: https://marlin-2.docker.com
stage: https://marlin-2-stage.docker.com

Docs repository URL

repo: https://github.com/docker/docs

=== Example versions ===

The following parameters are used in various ways in content and templates.

Mostly as examples in code snippets, but also in other exotic ways.

Use `grep` to figure out how they might be used.

Latest version of the Docker Engine API

latest_engine_api_version: "1.56"

Latest version of Docker Engine

docker_ce_version: "29.8.2"

Previous version of the Docker Engine

(Used to show e.g., "latest" and "latest"-1 in engine install examples

docker_ce_version_prev: "29.8.1"

Latest Docker Compose version

compose_version: "v5.6.0"

Latest BuildKit version

buildkit_version: "0.32.0"

Latest actions version

bake_action_version: "v7"
build_push_action_version: "v7"
login_action_version: "v4"
metadata_action_version: "v6"
setup_buildx_action_version: "v4"
setup_compose_action_version: "v2"
setup_docker_action_version: "v5"
setup_qemu_action_version: "v4"
github_builder_version: "v1"

Generic actions

checkout_action_version: "v6"
cache_action_version: "v5"

Example runtime/library/os versions

example_go_version: "1.26"
example_alpine_version: "3.23"
example_node_version: "24"

menus:

Site header menu

main:
- name: Get started
pageRef: /get-started/
weight: 1
- name: Guides
pageRef: /guides/
weight: 2
- name: Manuals
pageRef: /manuals/
weight: 3
- name: Reference
pageRef: /reference/
weight: 4

Footer links

footer:
- url: https://www.docker.com/products
name: Product offerings
- url: https://www.docker.com/products/personal
name: Docker Personal
parent: Product offerings
- url: https://www.docker.com/products/pro
name: Docker Pro
parent: Product offerings
- url: https://www.docker.com/products/team
name: Docker Team
parent: Product offerings
- url: https://www.docker.com/products/business
name: Docker Business
parent: Product offerings
- url: https://www.docker.com/pricing?ref=Docs&refAction=DocsFooter
name: Pricing FAQs
parent: Product offerings
- url: https://www.docker.com/partners/programs
name: Docker Verified Publisher
parent: Product offerings
- url: https://www.docker.com/partners
name: Partners
parent: Product offerings

- url: https://www.docker.com/
  name: Features
- url: https://www.docker.com/products/docker-desktop
  name: Docker Desktop
  parent: Features
- url: https://www.docker.com/products/docker-hub
  name: Docker Hub
  parent: Features
- url: https://www.docker.com/products/secure-software-supply-chain
  name: Secure Software Supply Chain
  parent: Features
- url: https://www.docker.com/products/container-runtime
  name: Container Runtime
  parent: Features
- url: https://www.docker.com/products/developer-tools
  name: Developer Tools
  parent: Features
- url: https://www.docker.com/partners
  name: Trusted Content
  parent: Features
- url: https://www.docker.com/roadmap
  name: Docker Product Roadmap
  parent: Features

- name: Developers
- url: https://www.docker.com/use-cases
  name: Use cases
  parent: Developers
- url: /get-started/
  name: Get started
  parent: Developers
- url: https://www.docker.com/blog/
  name: Blog
  parent: Developers
- url: https://www.docker.com/docker-community
  name: Community
  parent: Developers
- url: https://www.docker.com/open-source
  name: Open Source
  parent: Developers
- url: https://www.docker.com/community/get-involved/developer-preview
  name: Preview Program
  parent: Developers

- url: https://www.docker.com/company
  name: About us
- url: https://www.docker.com/what-container
  name: What is a container?
  parent: About us
- url: https://www.docker.com/why-docker
  name: Why Docker?
  parent: About us
- url: https://www.docker.com/events
  name: Virtual events
  parent: About us
- url: https://www.docker.com/swag
  name: Swag store
  parent: About us
- url: https://www.docker.com/company/newsroom
  name: Newsroom
  parent: About us
- url: https://www.docker.com/careers
  name: Careers
  parent: About us
- url: https://www.docker.com/company/contact
  name: Contact us
  parent: About us
- url: https://www.docker.com/customers
  name: Customers
  parent: About us
- url: https://www.docker.com/newsletter-subscription
  name: Newsletter
  parent: About us

Hugo modules - for fetching docs from upstream repos

NOTE: we always vendor upstream docs in _vendor/

Versions are declared in go.mod

module:
proxy: https://proxy.golang.org,direct
hugoVersion:
extended: false
min: "0.156.0"
mounts:
- source: data
target: data
# Mount the assets directory so it doesn't get overwritten
- source: assets
target: assets
# Mount hugo_stats.json to the assets dir to trigger cachebust
- disableWatch: true
source: hugo_stats.json
target: assets/notwatching/hugo_stats.json
# Mount the icon files to assets so we can access them with resources.Get
- source: node_modules/heroicons/24/solid
target: assets/icons
# Mount highlight.js theme for Gordon chat syntax highlighting
- source: node_modules/highlight.js/styles/github-dark.css
target: assets/css/highlight-github-dark.css

imports:
# Docker Engine API
- path: github.com/moby/moby/api
mounts:
- source: docs/CHANGELOG.md
target: content/reference/api/engine/version-history.md
- source: docs
target: content/reference/api/engine/version
files: ["*.yaml"]

# BuildKit
- path: github.com/moby/buildkit
  mounts:
    - source: frontend/dockerfile/docs/reference.md
      target: content/reference/dockerfile.md
    - source: frontend/dockerfile/docs/rules
      target: content/reference/build-checks
      files: ["*.md"]
    - source: docs/buildkitd.toml.md
      target: content/manuals/build/buildkit/toml-configuration.md
    - source: docs/attestations/slsa-definitions.md
      target: content/manuals/build/metadata/attestations/slsa-definitions.md
    - source: docs/attestations/attestation-storage.md
      target: content/manuals/build/metadata/attestations/attestation-storage.md

# Buildx CLI plugin
- path: github.com/docker/buildx
  mounts:
    - source: docs/bake-reference.md
      target: content/manuals/build/bake/reference.md
    - source: docs/bake-stdlib.md
      target: content/manuals/build/bake/stdlib.md

# Docker CLI
- path: github.com/docker/cli
  mounts:
    - source: docs/extend
      target: content/manuals/engine/extend
      files:
        - "! EBS_volume.md"
        - "! plugins_metrics.md"
        - "! plugins_services.md"
    - source: docs/deprecated.md
      target: content/manuals/engine/deprecated.md
    - source: docs/reference/run.md
      target: content/manuals/engine/containers/run.md
    - source: docs/reference/dockerd.md
      target: content/reference/cli/dockerd.md

# Compose
- path: github.com/docker/compose/v5
  mounts:
    - source: docs/reference
      target: data/cli/compose
      files: ["*.yaml"]

# Model CLI
- path: github.com/docker/model-runner
  mounts:
    - source: cmd/cli/docs/reference
      target: data/cli/model
      files: ["*.yaml"]

# Docker Agent
# Single-sources https://docker.github.io/docker-agent/ content;
# bumped on each docker-agent release by sync-docker-agent-docs.yml.
# Sections are mounted individually so hugo mod vendor does not
# vendor the upstream Jekyll site files that also live in docs/.
- path: github.com/docker/docker-agent
  mounts:
    - source: docs/getting-started
      target: content/manuals/ai/docker-agent/getting-started
    - source: docs/concepts
      target: content/manuals/ai/docker-agent/concepts
    - source: docs/configuration
      target: content/manuals/ai/docker-agent/configuration
    - source: docs/tools
      target: content/manuals/ai/docker-agent/tools
    - source: docs/providers
      target: content/manuals/ai/docker-agent/providers
    - source: docs/features
      target: content/manuals/ai/docker-agent/features
    - source: docs/guides
      target: content/manuals/ai/docker-agent/guides
    - source: docs/community
      target: content/manuals/ai/docker-agent/community
    - source: docs/demo.gif
      target: content/manuals/ai/docker-agent/demo.gif

File: package.json Copy Chapter

{
"name": "docker/docs",
"version": "0.0.1",
"description": "",
"repository": {
"type": "git",
"url": "git+https://github.com/docker/docs.git"
},
"keywords": [],
"author": "dvdksn",
"license": "Apache License 2.0",
"bugs": {
"url": "https://github.com/docker/docs/issues"
},
"homepage": "https://docs.docker.com/",
"dependencies": {
"@alpinejs/collapse": "3.15.8",
"@alpinejs/focus": "3.15.8",
"@alpinejs/persist": "3.15.8",
"@docker/marlin-sdk-web-public": "0.6.0",
"@floating-ui/dom": "1.7.6",
"@tailwindcss/cli": "4.2.1",
"@tailwindcss/typography": "0.5.19",
"alpinejs": "3.15.8",
"heroicons": "2.2.0",
"highlight.js": "11.11.1",
"marked": "17.0.4",
"mermaid": "11.15.0",
"micromark": "4.0.2",
"tailwindcss": "4.2.1"
},
"devDependencies": {
"prettier": "3.8.1",
"prettier-plugin-go-template": "0.0.15",
"prettier-plugin-tailwindcss": "0.7.2",
"rumdl": "0.2.49"
}
}

File: pagefind.yml Copy Chapter

output_subdir: pagefind
site: public
exclude_selectors:

• "table"
• ".md-dropdown"

File: STYLE.md Copy Chapter

Docker Documentation Style Guide

This guide consolidates voice, grammar, formatting, and terminology
standards for Docker documentation. Follow these guidelines to create
clear, consistent, and helpful content. For instructions on how to use
components, shortcodes, and other features, see COMPONENTS.md.

Voice and tone Copy Chapter

Write like a knowledgeable colleague explaining something useful. We're
developers writing for developers.

Core principles: The 4Cs Copy Section

1. Correct - Information is accurate
2. Concise - Succinct without unnecessary words
3. Complete - Includes enough detail to complete the task
4. Clear - Easy to understand

Writing approach Copy Section

• Be honest. Give all the facts. Don't use misdirection or
  ambiguous statements.
• Be concise. Don't bulk up communication with fluffy words or
  complex metaphors. Get to the point.
• Be relaxed. Casual but not lazy, smart but not arrogant, focused
  but not cold. Be welcoming and warm.
• Be inclusive. Every person is part of our community, regardless
  of experience level.

Tone guidelines Copy Section

• Use a natural, friendly, and respectful tone
• Use contractions to sound conversational (it's, you're, don't)
• Avoid overdoing politeness - skip "please" in most technical documentation
• Be clear over comical
• Use positive language - emphasize what users can do, not what they can't

Positive language example:

Instead of: "Features such as Single Sign-on (SSO), Image Access
Management, Registry Access Management are not available in Docker Team
subscription."

Use: "Features such as Single Sign-on (SSO), Image Access Management,
Registry Access Management are available in Docker Business subscription."

Avoiding marketing language Copy Section

Documentation should be factual and direct, not promotional.

Avoid hedge words that overstate ease or capability:

• ❌ simply, just, easily, seamlessly (implies ease when it may not be
  easy)
• ❌ robust, powerful (marketing language)
• ✅ Instead: describe what it actually does

Avoid excessive enthusiasm:

• ❌ "powerful feature", "game-changing", "revolutionary", "amazing"
• ✅ Instead: describe the feature and its benefits factually

Avoid meta-commentary:

These phrases add no value - state the fact directly:

• ❌ "It's worth noting that..."
• ❌ "It's important to understand that..."
• ❌ "Keep in mind that..."
• ✅ Instead: state the information directly

Voice and perspective Copy Section

• Use "you" not "we": Focus on what the user can do, not what "we"
  created
  • ❌ "We provide a feature that helps you deploy"
  • ✅ "Deploy your applications with..."
• Avoid "please": Don't use in normal explanations or "please note"
  phrases
• Write timelessly: Avoid "currently" or "as of this writing" - the
  documentation describes the product as it is today

Explain technical behavior Copy Section

Explain behavior from the reader's perspective. Lead with the observable
outcome, then add the implementation details needed to explain it.

Prefer:

Changes made by the agent stay inside the sandbox until you fetch them. The
agent works in a separate Git clone inside the sandbox.

Avoid:

A session that works directly in the sandbox clone still can't modify your
host repository.

The preferred version tells readers where changes happen and when they become
visible. The second version makes readers reconstruct the relationship between
the session, sandbox clone, and host repository.

Separate guarantees from variable behavior. Don't present behavior controlled
by another tool as a product default or guarantee. When behavior varies,
structure the explanation in this order:

1. State what always happens
2. State what the product doesn't control
3. Tell the reader what to do

For example:

The --clone flag creates the clone, but it doesn't separate one task from
another. To keep parallel tasks isolated, instruct your agent tool to create
a separate branch or worktree for each task.

Avoid chains of qualifications such as "may," "can," and "depends" that leave
the reader without a conclusion. Keep qualifiers that are needed for accuracy.
State what controls the behavior and what the reader should do.

Scope preservation Copy Section

When updating existing documentation, resist the urge to expand
unnecessarily. Users value brevity.

Understand the current document:
Read it fully to grasp its scope, length, and character. Is it a minimal
how-to or a comprehensive reference?

Match the existing character:
If the document is brief and direct (90 lines), keep it that way. Don't
transform a focused guide into an exhaustive tutorial.

Add only what's genuinely missing:
Fill gaps, don't elaborate. If the document already covers a topic
adequately, don't expand it.

Value brevity:
Say what needs to be said, then stop. Not every topic needs
prerequisites, troubleshooting, best practices, and examples sections.

Respect the original intent:
The document exists in its current form for a reason. Improve it, don't
remake it.

Good additions fill genuine gaps. Bad additions change the document's
character. When in doubt, add less rather than more.

Include caveats, failure scenarios, and fallback behavior only when they affect
a decision or action. Don't turn a clarification into a catalog of edge
cases.

Grammar and style Copy Chapter

Write in US English with US grammar.

Acronyms and initialisms Copy Section

• Spell out lesser-known acronyms on first use, then follow with the
  acronym in parentheses: "single sign-on (SSO)"
• Don't spell out common acronyms like URL, HTML, API
• Use all caps for file type acronyms: JPEG, PNG
• Don't use apostrophes for plurals: URLs not URL's
• Avoid introducing acronyms in headings - introduce them in the body
  text that follows

Capitalization Copy Section

Use sentence case for almost everything: headings, titles, links, buttons,
navigation labels.

• Capitalize Docker solutions: Docker Desktop, Docker Hub, Docker Extensions
• Capitalize job titles only when they immediately precede a name:
  "Chief Executive Officer Scott Johnston" but "Scott Johnston, chief
  executive officer"
• Follow company capitalization preferences: DISH, bluecrux
• Match UI capitalization when referring to specific interface elements

Contractions Copy Section

Use contractions to maintain a conversational tone, but don't overdo it.

• Stay consistent - don't switch between "you are" and "you're" in the
  same content
• Avoid negative contractions when possible (can't, don't, won't) -
  rewrite to be positive
• Never contract a noun with a verb (your container is ready, not your
  container's ready)

Clear subjects and modifiers Copy Section

Name the actor when a system includes multiple tools or components. Repeat the
noun instead of using an ambiguous pronoun. For example, distinguish between
what a CLI creates, what an agent edits, and what remains on the host.

Avoid unclear subjects:

• ❌ After enabling auto-log-out, your users are logged out
• ✅ When you enable auto-log-out, your users are logged out

Dates and numbers Copy Section

• Use US date format: June 26, 2021 or Jun. 26, 2021
• Spell out numbers one through nine, except in units: 4 MB
• Use numerals for 10 and above: 10, 625, 1000
• Use decimals instead of fractions: 0.5 not ½
• For numbers with five or more digits, use spaces instead of commas:
  14 586 not 14,586
• For version numbers: version 4.8.2, v1.0, Docker Hub API v2

Punctuation Copy Section

• Commas: Use the Oxford comma (serial comma) in lists
• Colons: Use to introduce lists or provide explanations
• Semicolons: Don't use - write two sentences instead
• Em dashes: Use sparingly with spaces on either side: "text - like
  this - text"
• Hyphens: Use for compound adjectives before nouns:
  "up-to-date documentation"
• Exclamation marks: Avoid
• Parentheses: Avoid in technical documentation - they reduce
  readability

Conciseness and redundant phrases Copy Section

Remove unnecessary words to make documentation clearer and more direct.

Keep an adjective or qualifier only when it changes how readers understand the
behavior or complete the task. If removing it doesn't change an outcome,
decision, or next step, remove it. Apply the same test to implementation
details.

Eliminate redundant phrases:

• ❌ "in order to" → ✅ "to"
• ❌ "serves the purpose of" → ✅ state what it does directly
• ❌ "allows you to" → ✅ "lets you" or state what it does
• ❌ "enables you to" → ✅ "lets you" or state what it does

Bold and italics Copy Section

Use bold only for UI elements (buttons, menus, field labels). Never
use bold for emphasis, product names, or feature names.

• ✅ Select Save (UI button - use bold)
• ✅ Docker Hub provides storage (product name - no bold)
• ✅ This is important to understand (emphasis - no bold)
• ❌ Docker Desktop is a tool (product name - don't bold)
• ❌ This is very important (emphasis - don't bold)
• ❌ The build command (command name - don't bold)

Italics:
Use italics sparingly, as this formatting can be difficult to read in
digital experiences. Notable exceptions are titles of articles, blog
posts, or specification documents.

Formatting Copy Chapter

Content types and detail balance Copy Section

Different content types require different writing approaches. Match your
style and detail level to the content type.

Getting Started / Tutorials:

• Step-by-step instructions
• Assume beginner knowledge
• Explain why at each step
• Include more context and explanation

How-to Guides:

• Task-focused and goal-oriented
• Assume intermediate knowledge
• Focus on how efficiently
• Less explanation, more direct steps

Reference Documentation:

• Comprehensive and exhaustive
• Assume advanced knowledge
• Focus on what precisely
• Complete parameter lists and options

Concept Explanations:

• Educational and foundational
• Any skill level
• Focus on understanding over doing
• Theory before practice

Match detail to context:

• First mention of a concept: explain it
• Subsequent mentions: link to the explanation or use the term
  directly if recently explained
• Common knowledge (to your audience): state it, don't explain it
• Edge cases: mention them but don't let them dominate the main flow

Headings Copy Section

• Keep headings short (no more than eight words)
• Front-load the most important words
• Use descriptive, action-oriented language
• Skip leading articles (a, the)
• Avoid puns, teasers, and cultural references
• Page titles should be action-oriented: "Install Docker Desktop",
  "Enable SCIM"

Page structure and flow Copy Section

Every page should answer two questions in the first paragraph:

1. What will I learn? - State what the page covers
2. Why does this matter? - Explain the benefit or use case

Good opening:

Docker Compose Watch automatically updates your running containers when
you change code. This eliminates the manual rebuild-restart cycle during
development.

Weak opening:

Docker Compose Watch is a powerful feature that enables developers to
streamline their development workflow by providing automatic
synchronization capabilities.

Transitions and flow:
Connect ideas naturally. Each section should flow logically from the
previous one. Save detailed discussions for after showing basic usage -
don't front-load complexity.

Good flow:

1. Prerequisites
2. Basic usage (show the simple case first)
3. Advanced options (add complexity after basics are clear)

Jarring flow:

1. Prerequisites
2. Overview of all capabilities (too much before seeing it work)
3. Basic usage

Avoid structural problems:

• Don't start multiple sentences or sections with the same structure
  (varies pacing and improves readability)
• Don't over-explain obvious things (trust the reader's competence)
• Don't use "Bold: format" for subsection labels (use plain text
  with colon)

Guide structure Copy Section

Guides are single-page - don't split a guide into multiple sub-pages
(for example, separate "overview", "configure", and "deploy" pages for
one guide). Cover the full task on one page and use headings to
organize sections.

Store each guide as a single Markdown file directly under
content/guides/ (for example, content/guides/django.md), not
wrapped in its own directory with an index.md. Guide images belong in
the shared content/guides/images/ folder, prefixed with the guide's
slug, not in a per-guide directory - see Images.

Lists Copy Section

• Limit bulleted lists to five items when possible
• Don't add commas or semicolons to list item ends
• Capitalize list items for ease of scanning
• Make all list items parallel in structure
• Start each item with a capital letter unless it's a parameter or
  command
• For nested sequential lists, use lowercase letters: 1. Top level,
  a. Child step

Avoid marketing-style list formatting:

Don't use "Term - Description" format, which reads like marketing
copy:

❌ Bad example:

• Build - Creates images from Dockerfiles
• Run - Starts containers from images
• Push - Uploads images to registries

✅ Good alternatives:

Use simple descriptive bullets:

• Build images from Dockerfiles
• Start containers from images
• Upload images to registries

Or use proper prose when appropriate:
"Docker lets you build images from Dockerfiles, start containers from
images, and upload images to registries."

Code and commands Copy Section

Format Docker commands, instructions, filenames, and package names as
inline code using backticks: docker build

Code example pattern:

Follow this three-step pattern for code examples:

1. State what you're doing (brief)
2. Show the command or code
3. Explain the result or key parts (if not obvious)

Example:

Build your image:

```console
$ docker build -t my-app .
```

This creates an image tagged `my-app` using the Dockerfile in the
current directory.

When to show command output:

• Show output when it helps understanding
• Show output when users need to verify results
• Don't show output for commands with obvious results
• Don't show output when it's not relevant to the point

For code block syntax, language hints, variables, and advanced features
(line highlighting, collapsible blocks), see
COMPONENTS.md.

Links Copy Section

• Use plain, descriptive language (around five words)
• Front-load important terms at the beginning
• Avoid generic calls to action like "click here" or "find out more"
• Don't include end punctuation in link text
• Use relative links with source filenames for internal links
• Don't make link text bold or italic unless it would be in normal
  body copy

Images Copy Section

Best practices:

• Capture only relevant UI - don't include unnecessary white space
• Use realistic text, not lorem ipsum
• Keep images small and focused
• Compress images before adding to repository
• Remove unused images from repository

File organization:

• Store guide images in the shared content/guides/images/ folder,
  not in a per-guide directory
• Prefix filenames with the guide's slug to avoid collisions (for
  example, kafka-architecture.webp)

For image syntax and parameters (sizing, borders), see
COMPONENTS.md.

Callouts Copy Section

Use callouts sparingly to emphasize important information. Use them only
when information truly deserves special emphasis - for warnings, critical
notes, or important context that affects how users approach a task.

Callout types: Note (informational), Tip (helpful suggestion), Important
(moderate issue), Warning (potential damage/loss), Caution (serious risk).

For syntax and detailed usage guidelines, see
COMPONENTS.md.

Tables Copy Section

• Use sentence case for table headings
• Don't leave cells empty - use "N/A" or "None" if needed
• Align decimals on the decimal point

Navigation instructions Copy Section

• Use location, then action: "From the Visibility drop-down list, select Public"
• Be brief and specific: "Select Save"
• Start with the reason if a step needs one: "To view changes, select the link"

Optional steps Copy Section

Start optional steps with "Optional." followed by the instruction:

1. Optional. Enter a description for the job.

File types and units Copy Section

• Use formal file type names: "a PNG file" not "a .png file"
• Use abbreviated units with spaces: "10 GB" not "10GB" or
  "10 gigabytes"

Word list Copy Chapter

Recommended terms Copy Section

Use "turn on" and "turn off" for UI toggles, switches, and settings a user
flips in the interface. In general prose, "enable" and "disable" are
acceptable when describing a feature or capability becoming available — for
example, "When you enable auto-log-out, your users are logged out." Don't
treat every "enable" or "disable" as a violation.

Version numbers Copy Section

• Use "earlier" not "lower": Docker Desktop 4.1 and earlier
• Use "later" not "higher" or "above": Docker Desktop 4.1 and later

Quick transformations Copy Section

Common phrases to transform for clearer, more direct writing:

UI elements Copy Section

• tab vs view - Use "view" for major UI sections, "tab" for
  sub-sections
• toggle - You "turn on" or "turn off" a toggle

Docker terminology Copy Chapter

Products and features Copy Section

• Docker Compose - The application or all functionality associated
  with it
• docker compose - Use code formatting for commands
• Docker Compose CLI - The family of Compose commands from
  Docker CLI
• Compose plugin - The add-on for Docker CLI that can be
  enabled/disabled
• compose.yaml - Current designation for the Compose file (use
  code formatting)

Technical terms Copy Section

• Digest - Long string automatically created when you push an
  image
• Member - A user of Docker Hub who is part of an organization
• Namespace - Organization or user name; every image needs a
  namespace
• Node - Physical or virtual machine running Docker Engine in
  swarm mode
  • Manager nodes: Perform swarm management and orchestration
  • Worker nodes: Execute tasks
• Registry - Online storage for Docker images
• Repository - Lets users share container images with team,
  customers, or community

Platform terminology Copy Section

• Multi-platform - Broad: Mac/Linux/Windows; Narrow: Linux/amd64
  and Linux/arm64
• Multi-architecture (multi-arch) - CPU architecture or
  hardware-architecture-based; don't use as synonym for multi-platform

Quick reference Copy Chapter

Voice checklist Copy Section

• ✅ Direct and practical
• ✅ Conversational with active voice
• ✅ Specific and actionable
• ✅ Lead with observable outcomes
• ❌ Corporate-speak
• ❌ Condescending
• ❌ Overly formal

Structure checklist Copy Section

• ✅ Answer "What will I learn?" in the first paragraph
• ✅ Answer "Why does this matter?" in the first paragraph
• ✅ Front-load important information in headings and lists
• ✅ Connect ideas naturally between sections
• ✅ Use examples to clarify concepts
• ✅ Match content type (tutorial vs how-to vs reference vs concept)
• ✅ Follow code example pattern: state → show → explain
• ✅ Preserve document scope (don't unnecessarily expand)

Common mistakes Copy Section

• ❌ Using "click" instead of "select"
• ❌ Using "below" instead of "following"
• ❌ Starting sentences with numbers (recast the sentence)
• ❌ Using apostrophes in plural acronyms
• ❌ Leaving table cells empty
• ❌ Using commas in large numbers (use spaces)
• ❌ Referring to file types by extension (.png file)
• ❌ Using bold for product names or emphasis (only for UI elements)
• ❌ Using "Term - Description" format in lists
• ❌ Using hedge words (simply, easily, just, seamlessly)
• ❌ Using meta-commentary (it's worth noting that...)
• ❌ Using "we" instead of "you" or "Docker"
• ❌ Showing command output when it's not needed
• ❌ Not explaining what users will learn in first paragraph

File: .htmltest.yml Copy Chapter

DirectoryPath: "public"
EnforceHTTPS: false
CheckDoctype: false
CheckExternal: false
IgnoreAltMissing: true
IgnoreAltEmpty: true
IgnoreEmptyHref: true
IgnoreDirectoryMissingTrailingSlash: true
IgnoreURLs:

• "^/reference/api/engine/v.+/#.*$"
• "^/pagefind/.*$"
  IgnoreDirs:
• "registry/configuration"
• "compose/compose-file" # temporarily ignore until upstream is fixed
  CacheExpires: "6h"

File: _vale/config/vocabularies/Docker/accept.txt Copy Chapter

(?i)[A-Z]{2,}'?s
jq
zstd
Zstandard
untracked
ripgrep
exfiltration
sandboxing
Adreno
Aleksandrov
Awaitility
Amazon
Anchore
Ansible
Apple
Artifactory
armhf
[Aa]uditability
auditable
[Aa]utoconfiguration
autolock
[Aa]llowlist(ing)?
Azure
Azure AD
[Bb]ackport
[Bb]enchmarked
bootup
Bitnami
Btrfs
Bugsnag
buildkitd
cagent
CD
CentOS
Ceph
cgroup
Chrome
Chrome DevTools
CI
CI/CD
Citrix
classpath
cli
CLI
CloudFront
composable
Codefresh
Codespaces
config
containerd
Couchbase
CouchDB
CrowdStrike
[Cc]ybersecurity
datacenter
datasource
Datadog
DBeaver
Ddosify
Debootstrap
denylist
deprovisioning
deserialization
deserialize[d]?
Dev
Dev Environments?
Dex
displayName
Django
DMR
Docker Dashboard
Docker Extension
Docker-Sponsored Open Source
Docker's
dockerignore
Dockerize
Dockerized
Dockerizing
Dependabot
DuckDuckGo
Dynatrace
Entra
EPERM
ESXi
Ethernet
[Ee]xploitability
[Ff]ailover
Fargate
Fedora
Filebeat
firewalld
Flink
Fluentd
g?libc
GeoNetwork
GGUF
Git
Gitea
Google
Gradle
Grafana
Gravatar
gRPC
Groq
Grype
Gunicorn
HyperKit
inferencing
initializer
Initializr
inotify
Intel
Intune
IPsec
iptables
IPv[46]
IPvlan
isort
Jamf
JetBrains
JFrog
JUnit
Kata
Keycloak
Kerberos
Kiro
Kitematic
Kubeadm
kubectl
kubefwd
kubelet
Laradock
Laravel
libseccomp
Linux
Liquibase
LinuxKit
logback
Loggly
Logstash
lookup
macvlan
Mail(chimp|gun)
mfsymlinks
Micronaut
Microsoft
minikube
misconfiguration
[Mm]ixins?
monorepos?
musl
nameserver
namespaced?
namespacing
Neovim
Npgsql
netfilter
netlabel
netlink
Netplan
NFSv\d
npm
nvm
Nutanix
Nuxeo
OAuth
Okta
Ollama
osquery
osxfs
OTel
Paketo
PAT
perl
pgAdmin
pgx
PKG
plaintext
plist
pluggable
Postgres
psycopg
pytest
Python
Qualcomm
Quickview
rebalance
reimplement
reloader
repinning
Rego
Rekor
ROCm
rollback
rootful
rqt
runc
RViz
Ryuk
S3
scrollable
SELinux
Slack
snapshotters?
Sigstore
Snyk
Solr
SonarQube
Sonatype
Sonoma
Splunk
SQLite
stargz
eStargz
stdin
stdout
subfolder
sudo
[Ss]ubvolume
Syft
syntaxes
Sysbox
sysctl
sysctls
Sysdig
systemd
teleop
tmpfs
Traefik
Trivy
Trixie
Turtlesim
typesafe
Ubuntu
ufw
uv
umask
[Uu]ncaptured
unconfigured
undeterminable
Unix
unmarshalling
unmanaged
upsert
VMware
VPNKit
vSphere
Vulkan
Vue
Wasm
Wasmtime
Windows
windowsfilter
WireMock
workdir
WORKDIR
[Ww]orktrees?
[Pp]assthrough
[Pp]reconfigured
Xdebug
xUnit
XQuartz
youki
Yubikey
Zscaler
Zsh
[Aa]nonymized?
[Aa]utobuild
[Aa]llowlist
[Aa]gentic
[Aa]utobuilds?
[Aa]utotests?
[Aa]utoscaling
[Bb]uildpack(s)?
[Cc]odenames?
[Cc]ompose
[Cc]onfigs
[dD]eduplicate
[Dd]enylist
[Dd]ev
[Dd]iscoverability
[Dd]istroless
[Ff]ilepaths?
[Ff]iletypes?
[GgCc]oroutine
[Hh]ealthcheck
[Hh]eredoc
[Hh]ostname
[Ii]nfosec
[Ii]nline
[Kk]eyrings?
[Ll]oopback
[Mm]emcached
[Mm]oby
[Mm]ountpoint
[Nn]amespace
[Oo]nboarding
[Pp]aravirtualization
[Pp]repend
[Pp]rocfs
[Pp]roxied
[Pp]roxying
[pP]yright
README
[Rr]eal-time
[Rr]egex(es)?
[Rr]uleset(s)?
[Rr]untimes?
[Ss]andbox(ed)?
[Ss]eccomp
[Ss]ubmounts?
[Ss]ubnet
[Ss]ubpaths?
[Ss]ubtrees?
[Ss]wappable
[Ss]wappable
[Ss]warm
[Ss]warm
[Ss]yscalls?
[Ss]ysfs
[Tt]eardown
[Tt]echnographic
[Tt]odo
[Tt]oolchains?
[Uu]narchived?
[Uu]ngated
[Uu]ntrusted
[Uu]serland
[Uu]serspace
[Vv]irtiofs
[Vv]irtualize
[Ww]alkthrough
[Tt]oolsets?
[Rr]eachability
[Rr]erank(ing|ed)?
[Ee]vals?
[Ll]abspaces?
[Uu]nsloth
[Aa]utolocking
[Bb]oolean
[Bb]reakpoint
CMD
[Dd]eno
[Dd]evicemapper
[Dd]ockerbot
[Dd]ockerd
docker_ce_version
[Ee]nv
ESLint
gzip
HAProxy
[Ii]nlined
journald
JSON
keypair
Kustomize
latest_engine_api_version
[Mm]iddleware
[Nn]onroot
param
[Pp]erformant
Pinecone
Qdrant
[Rr]outable
[Ss]emver
setuid
SHA
spaCy
src
stderr
Streamlit
[Ss]ubcommand
syslog
TCP
thinpool
[Tt]runked
UID
[Uu]nencrypted
[Uu]nmount
URL
VM
Vite
Vitest
Wolfi
[Aa]utoextend
[Bb]ackoff
[Bb]crypt
[Bb]undler
copy_up
[Dd]eclaratively
[Dd]eduplication
dnf
docker_gwbridge
[Gg]lobbing
GPG
KVM
[Mm]ulticast
[Mm]isconfigured
oldstable
OpenSSL
[Ss]tringified
SwarmKit
[Uu]ncomment
bootloader
Buildkite
crypto
Graylog
Heartbleed
Kubuntu
Libnetwork
lockfile
Lubuntu
multimodal
multithreading
Log4Shell
NLP
Nodemon
oldoldstable
parallelizable
PHPUnit
pnpm
Shellshock
Spring4Shell
superset
tokenization
WebGL
Xubuntu
Netlify

File: _vendor/modules.txt Copy Chapter

github.com/moby/moby/api v1.56.1

github.com/moby/buildkit v0.34.0

github.com/docker/buildx v0.38.1

github.com/docker/cli v29.8.2+incompatible

github.com/docker/compose/v5 v5.6.1

github.com/docker/model-runner v1.1.36

github.com/docker/docker-agent v1.126.0

File: _vendor/github.com/docker/buildx/docs/bake-reference.md Copy Chapter

title: Bake file reference Copy Chapter

The Bake file is a file for defining workflows that you run using docker buildx bake.

File format Copy Chapter

You can define your Bake file in the following file formats:

• HashiCorp Configuration Language (HCL)
• JSON
• YAML (Compose file)

By default, Bake uses the following lookup order to find the configuration file:

1. compose.yaml
2. compose.yml
3. docker-compose.yml
4. docker-compose.yaml
5. docker-bake.json
6. docker-bake.hcl
7. docker-bake.override.json
8. docker-bake.override.hcl

You can specify the file location explicitly using the --file flag:

$ docker buildx bake --file ../docker/bake.hcl --print

If you don't specify a file explicitly, Bake searches for the file in the
current working directory. If more than one Bake file is found, all files are
merged into a single definition. Files are merged according to the lookup
order. That means that if your project contains both a compose.yaml file and
a docker-bake.hcl file, Bake loads the compose.yaml file first, and then
the docker-bake.hcl file.

If merged files contain duplicate attribute definitions, those definitions are
either merged or overridden by the last occurrence, depending on the attribute.
The following attributes are overridden by the last occurrence:

• target.cache-to
• target.dockerfile-inline
• target.dockerfile
• target.output
• target.platforms
• target.pull
• target.tags
• target.target

For example, if compose.yaml and docker-bake.hcl both define the tags
attribute, the docker-bake.hcl is used.

$ cat compose.yaml
services:
  webapp:
    build:
      context: .
      tags:
        - bar
$ cat docker-bake.hcl
target "webapp" {
  tags = ["foo"]
}
$ docker buildx bake --print webapp
{
  "group": {
    "default": {
      "targets": [
        "webapp"
      ]
    }
  },
  "target": {
    "webapp": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "tags": [
        "foo"
      ]
    }
  }
}

All other attributes are merged. For example, if compose.yaml and
docker-bake.hcl both define unique entries for the labels attribute, all
entries are included. Duplicate entries for the same label are overridden.

$ cat compose.yaml
services:
  webapp:
    build:
      context: .
      labels: 
        com.example.foo: "foo"
        com.example.name: "Alice"
$ cat docker-bake.hcl
target "webapp" {
  labels = {
    "com.example.bar" = "bar"
    "com.example.name" = "Bob"
  }
}
$ docker buildx bake --print webapp
{
  "group": {
    "default": {
      "targets": [
        "webapp"
      ]
    }
  },
  "target": {
    "webapp": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "labels": {
        "com.example.foo": "foo",
        "com.example.bar": "bar",
        "com.example.name": "Bob"
      }
    }
  }
}

Syntax Copy Chapter

The Bake file supports the following property types:

• target: build targets
• group: collections of build targets
• variable: build arguments and variables
• function: custom Bake functions

You define properties as hierarchical blocks in the Bake file.
You can assign one or more attributes to a property.

The following snippet shows a JSON representation of a simple Bake file.
This Bake file defines three properties: a variable, a group, and a target.

{
  "variable": {
    "TAG": {
      "default": "latest"
    }
  },
  "group": {
    "default": {
      "targets": ["webapp"]
    }
  },
  "target": {
    "webapp": {
      "dockerfile": "Dockerfile",
      "tags": ["docker.io/username/webapp:${TAG}"]
    }
  }
}

In the JSON representation of a Bake file, properties are objects,
and attributes are values assigned to those objects.

The following example shows the same Bake file in the HCL format:

variable "TAG" {
  default = "latest"
}

group "default" {
  targets = ["webapp"]
}

target "webapp" {
  dockerfile = "Dockerfile"
  tags = ["docker.io/username/webapp:${TAG}"]
}

HCL is the preferred format for Bake files.
Aside from syntactic differences,
HCL lets you use features that the JSON and YAML formats don't support.

The examples in this document use the HCL format.

Target Copy Chapter

A target reflects a single docker build invocation.
Consider the following build command:

$ docker build \
  --file=Dockerfile.webapp \
  --tag=docker.io/username/webapp:latest \
  https://github.com/username/webapp

You can express this command in a Bake file as follows:

target "webapp" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  context = "https://github.com/username/webapp"
}

The following table shows the complete list of attributes that you can assign to a target:

`target.args` Copy Section

Use the args attribute to define build arguments for the target.
This has the same effect as passing a --build-arg flag to the build command.

target "default" {
  args = {
    VERSION = "0.0.0+unknown"
  }
}

You can set args attributes to use null values.
Doing so forces the target to use the ARG value specified in the Dockerfile.

variable "GO_VERSION" {
  default = "1.20.3"
}

target "webapp" {
  dockerfile = "webapp.Dockerfile"
  tags = ["docker.io/username/webapp"]
}

target "db" {
  args = {
    GO_VERSION = null
  }
  dockerfile = "db.Dockerfile"
  tags = ["docker.io/username/db"]
}

`target.annotations` Copy Section

The annotations attribute lets you add annotations to images built with bake.
The key takes a list of annotations, in the format of KEY=VALUE.

target "default" {
  output = [{ type = "image", name = "foo" }]
  annotations = ["org.opencontainers.image.authors=dvdksn"]
}

By default, the annotation is added to image manifests. You can configure the
level of the annotations by adding a prefix to the annotation, containing a
comma-separated list of all the levels that you want to annotate. The following
example adds annotations to both the image index and manifests.

target "default" {
  output = [
    {
      type = "image"
      name = "foo"
    }
  ]
  annotations = ["index,manifest:org.opencontainers.image.authors=dvdksn"]
}

Read about the supported levels in
Specifying annotation levels.

`target.attest` Copy Section

The attest attribute lets you apply build attestations to the target.
This attribute accepts the long-form CSV version of attestation parameters.

target "default" {
  attest = [
    {
      type = "provenance"
      mode = "max"
    },
    {
      type = "sbom"
    }
  ]
}

`target.cache-from` Copy Section

Build cache sources.
The builder imports cache from the locations you specify.
It uses the Buildx cache storage backends,
and it works the same way as the --cache-from flag.
This takes a list value, so you can specify multiple cache sources.

target "app" {
  cache-from = [
    {
      type = "s3"
      region = "eu-west-1"
      bucket = "mybucket"
    },
    {
      type = "registry"
      ref = "user/repo:cache"
    }
  ]
}

`target.cache-to` Copy Section

Build cache export destinations.
The builder exports its build cache to the locations you specify.
It uses the Buildx cache storage backends,
and it works the same way as the --cache-to flag.
This takes a list value, so you can specify multiple cache export targets.

target "app" {
  cache-to = [
    {
      type = "s3"
      region = "eu-west-1"
      bucket = "mybucket"
    },
    {
      type = "inline"
    }
  ]
}

`target.call` Copy Section

Specifies the frontend method to use. Frontend methods let you, for example,
execute build checks only, instead of running a build. This is the same as the
--call flag.

target "app" {
  call = "check"
}

Supported values are:

• build builds the target (default)
• check: evaluates build checks for the target
• outline: displays the target's build arguments and their default values if available
• targets: lists all Bake targets in the loaded definition, along with its description.

For more information about frontend methods, refer to the CLI reference for
docker buildx build --call.

`target.context` Copy Section

Specifies the location of the build context to use for this target.
Accepts a URL or a directory path.
This is the same as the build context positional argument
that you pass to the build command.

target "app" {
  context = "./src/www"
}

This resolves to the current working directory (".") by default.
Set BUILDX_BAKE_FILE_RELATIVE_PATHS=1 to resolve local directory paths in
target.context and target.contexts relative to the Bake file that defines
each path. Compose files use the first Compose file directory as the base, which
matches Compose project directory semantics. Use cwd:// for paths that should
remain relative to the current working directory when this opt-in is enabled.

$ docker buildx bake --print -f - <<< 'target "default" {}'
[+] Building 0.0s (0/0)
{
  "target": {
    "default": {
      "context": ".",
      "dockerfile": "Dockerfile"
    }
  }
}

`target.contexts` Copy Section

Additional build contexts.
This is the same as the --build-context flag.
This attribute takes a map, where keys result in named contexts that you can
reference in your builds.

You can specify different types of contexts, such local directories, Git URLs,
and even other Bake targets. Bake automatically determines the type of
a context based on the pattern of the context value.

Pin an image version

# docker-bake.hcl
target "app" {
  contexts = {
    alpine = "docker-image://alpine:3.13"
  }
}

# Dockerfile
FROM alpine
RUN echo "Hello world"

Use a local directory

# docker-bake.hcl
target "app" {
  contexts = {
    src = "../path/to/source"
  }
}

# Dockerfile
FROM scratch AS src
FROM golang
COPY --from=src . .

Use another target as base

[!NOTE]
You should prefer to use regular multi-stage builds over this option. You can
Use this feature when you have multiple Dockerfiles that can't be easily
merged into one.

# docker-bake.hcl
target "base" {
  dockerfile = "baseapp.Dockerfile"
}

target "app" {
  contexts = {
    baseapp = "target:base"
  }
}

# Dockerfile
FROM baseapp
RUN echo "Hello world"

`target.description` Copy Section

Defines a human-readable description for the target, clarifying its purpose or
functionality.

target "lint" {
  description = "Runs golangci-lint to detect style errors"
  args = {
    GOLANGCI_LINT_VERSION = null
  }
  dockerfile = "lint.Dockerfile"
}

This attribute is useful when combined with the docker buildx bake --list=targets
option, providing a more informative output when listing the available build
targets in a Bake file.

`target.dockerfile-inline` Copy Section

Uses the string value as an inline Dockerfile for the build target.

target "default" {
  dockerfile-inline = "FROM alpine\nENTRYPOINT [\"echo\", \"hello\"]"
}

The dockerfile-inline takes precedence over the dockerfile attribute.
If you specify both, Bake uses the inline version.

`target.dockerfile` Copy Section

Name of the Dockerfile to use for the build.
This is the same as the --file flag for the docker build command.

target "default" {
  dockerfile = "./src/www/Dockerfile"
}

Resolves to "Dockerfile" by default.

$ docker buildx bake --print -f - <<< 'target "default" {}'
[+] Building 0.0s (0/0)
{
  "target": {
    "default": {
      "context": ".",
      "dockerfile": "Dockerfile"
    }
  }
}

`target.entitlements` Copy Section

Entitlements are permissions that the build process requires to run.

Currently supported entitlements are:

• network.host: Allows the build to use commands that access the host network. In Dockerfile, use RUN --network=host to run a command with host network enabled.

• security.insecure: Allows the build to run commands in privileged containers that are not limited by the default security sandbox. Such container may potentially access and modify system resources. In Dockerfile, use RUN --security=insecure to run a command in a privileged container.

target "integration-tests" {
  # this target requires privileged containers to run nested containers
  entitlements = ["security.insecure"]
}

Entitlements are enabled with a two-step process. First, a target must declare the entitlements it requires. Secondly, when invoking the bake command, the user must grant the entitlements by passing the --allow flag or confirming the entitlements when prompted in an interactive terminal. This is to ensure that the user is aware of the possibly insecure permissions they are granting to the build process.

`target.extra-hosts` Copy Section

Use the extra-hosts attribute to define custom host-to-IP mapping for the
target. This has the same effect as passing a --add-host flag to
the build command.

target "default" {
  extra-hosts = {
    my_hostname = "8.8.8.8"
  }
}

`target.inherits` Copy Section

A target can inherit attributes from other targets.
Use inherits to reference from one target to another.

In the following example,
the app-dev target specifies an image name and tag.
The app-release target uses inherits to reuse the tag name.

variable "TAG" {
  default = "latest"
}

target "app-dev" {
  tags = ["docker.io/username/myapp:${TAG}"]
}

target "app-release" {
  inherits = ["app-dev"]
  platforms = ["linux/amd64", "linux/arm64"]
}

The inherits attribute is a list,
meaning you can reuse attributes from multiple other targets.
In the following example, the app-release target reuses attributes
from both the app-dev and _release targets.

target "app-dev" {
  args = {
    GO_VERSION = "1.20"
    BUILDX_EXPERIMENTAL = 1
  }
  tags = ["docker.io/username/myapp"]
  dockerfile = "app.Dockerfile"
  labels = {
    "org.opencontainers.image.source" = "https://github.com/username/myapp"
  }
}

target "_release" {
  args = {
    BUILDKIT_CONTEXT_KEEP_GIT_DIR = 1
    BUILDX_EXPERIMENTAL = 0
  }
}

target "app-release" {
  inherits = ["app-dev", "_release"]
  platforms = ["linux/amd64", "linux/arm64"]
}

When inheriting attributes from multiple targets and there's a conflict,
the target that appears last in the inherits list takes precedence.
The previous example defines the BUILDX_EXPERIMENTAL argument twice for the app-release target.
It resolves to 0 because the _release target appears last in the inheritance chain:

$ docker buildx bake --print app-release
[+] Building 0.0s (0/0)
{
  "group": {
    "default": {
      "targets": [
        "app-release"
      ]
    }
  },
  "target": {
    "app-release": {
      "context": ".",
      "dockerfile": "app.Dockerfile",
      "args": {
        "BUILDKIT_CONTEXT_KEEP_GIT_DIR": "1",
        "BUILDX_EXPERIMENTAL": "0",
        "GO_VERSION": "1.20"
      },
      "labels": {
        "org.opencontainers.image.source": "https://github.com/username/myapp"
      },
      "tags": [
        "docker.io/username/myapp"
      ],
      "platforms": [
        "linux/amd64",
        "linux/arm64"
      ]
    }
  }
}

`target.labels` Copy Section

Assigns image labels to the build.
This is the same as the --label flag for docker build.

target "default" {
  labels = {
    "org.opencontainers.image.source" = "https://github.com/username/myapp"
    "com.docker.image.source.entrypoint" = "Dockerfile"
  }
}

It's possible to use a null value for labels.
If you do, the builder uses the label value specified in the Dockerfile.

`target.matrix` Copy Section

A matrix strategy lets you fork a single target into multiple different
variants, based on parameters that you specify.
This works in a similar way to [Matrix strategies for GitHub Actions].
You can use this to reduce duplication in your bake definition.

The matrix attribute is a map of parameter names to lists of values.
Bake builds each possible combination of values as a separate target.

Each generated target must have a unique name.
To specify how target names should resolve, use the name attribute.

The following example resolves the app target to app-foo and app-bar.
It also uses the matrix value to define the target build stage.

target "app" {
  name = "app-${tgt}"
  matrix = {
    tgt = ["foo", "bar"]
  }
  target = tgt
}

$ docker buildx bake --print app
[+] Building 0.0s (0/0)
{
  "group": {
    "app": {
      "targets": [
        "app-foo",
        "app-bar"
      ]
    },
    "default": {
      "targets": [
        "app"
      ]
    }
  },
  "target": {
    "app-bar": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "target": "bar"
    },
    "app-foo": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "target": "foo"
    }
  }
}

Multiple axes

You can specify multiple keys in your matrix to fork a target on multiple axes.
When using multiple matrix keys, Bake builds every possible variant.

The following example builds four targets:

• app-foo-1-0
• app-foo-2-0
• app-bar-1-0
• app-bar-2-0

target "app" {
  name = "app-${tgt}-${replace(version, ".", "-")}"
  matrix = {
    tgt = ["foo", "bar"]
    version = ["1.0", "2.0"]
  }
  target = tgt
  args = {
    VERSION = version
  }
}

Multiple values per matrix target

If you want to differentiate the matrix on more than just a single value,
you can use maps as matrix values. Bake creates a target for each map,
and you can access the nested values using dot notation.

The following example builds two targets:

• app-foo-1-0
• app-bar-2-0

target "app" {
  name = "app-${item.tgt}-${replace(item.version, ".", "-")}"
  matrix = {
    item = [
      {
        tgt = "foo"
        version = "1.0"
      },
      {
        tgt = "bar"
        version = "2.0"
      }
    ]
  }
  target = item.tgt
  args = {
    VERSION = item.version
  }
}

`target.name` Copy Section

Specify name resolution for targets that use a matrix strategy.
The following example resolves the app target to app-foo and app-bar.

target "app" {
  name = "app-${tgt}"
  matrix = {
    tgt = ["foo", "bar"]
  }
  target = tgt
}

`target.network` Copy Section

Specify the network mode for the whole build request. This will override the default network mode
for all the RUN instructions in the Dockerfile. Accepted values are default, host, and none.

Usually, a better approach to set the network mode for your build steps is to instead use RUN --network=<value>
in your Dockerfile. This way, you can set the network mode for individual build steps and everyone building
the Dockerfile gets consistent behavior without needing to pass additional flags to the build command.

If you set network mode to host in your Bake file, you must also grant network.host entitlement when
invoking the bake command. This is because host network mode requires elevated privileges and can be a security risk.
You can pass --allow=network.host to the docker buildx bake command to grant the entitlement, or you can
confirm the entitlement when prompted if you are using an interactive terminal.

target "app" {
  # make sure this build does not access internet
  network = "none"
}

`target.no-cache-filter` Copy Section

Don't use build cache for the specified stages.
This is the same as the --no-cache-filter flag for docker build.
The following example avoids build cache for the foo build stage.

target "default" {
  no-cache-filter = ["foo"]
}

`target.no-cache` Copy Section

Don't use cache when building the image.
This is the same as the --no-cache flag for docker build.

target "default" {
  no-cache = true
}

`target.output` Copy Section

Configuration for exporting the build output.
This is the same as the --output flag.
The following example configures the target to use a cache-only output,

target "default" {
  output = [{ type = "cacheonly" }]
}

[!NOTE]
Local outputs with mode=delete require granting --allow=buildx.local.delete
when invoking docker buildx bake.

`target.policy` Copy Section

Policies to validate build sources and metadata. Each entry uses the same keys
as the --policy flag for docker buildx build (filename, reset,
disabled, strict, log-level). Bake also automatically loads
Dockerfile.rego alongside the target Dockerfile when present.

target "default" {
  policy = [
    { filename = "extra.rego" },
  ]
}

`target.platforms` Copy Section

Set target platforms for the build target.
This is the same as the --platform flag.
The following example creates a multi-platform build for three architectures.

target "default" {
  platforms = ["linux/amd64", "linux/arm64", "linux/arm/v7"]
}

`target.pull` Copy Section

Configures whether the builder should attempt to pull images when building the target.
This is the same as the --pull flag for docker build.
The following example forces the builder to always pull all images referenced in the build target.

target "default" {
  pull = true
}

`target.resources` Copy Section

Sets cgroup resource limits for the containers that run RUN instructions
during the build. The supported keys are memory, memory-swap, cpu-shares,
cpu-period, cpu-quota, cpuset-cpus, and cpuset-mems. These map to the
equivalent docker build flags and to the
--resource
flag for docker buildx build.

target "default" {
  resources = {
    memory      = "2g"
    memory-swap = "4g"
    cpu-quota   = 50000
  }
}

[!NOTE]
These limits require a BuildKit daemon that supports per-step resource limits
and only take effect on Linux. They don't affect the build cache key.

`target.secret` Copy Section

Defines secrets to expose to the build target.
This is the same as the --secret flag.

variable "HOME" {
  default = null
}

target "default" {
  secret = [
    {
      type = "env"
      id = "KUBECONFIG"
    },
    {
      type = "file"
      id = "aws"
      src = "${HOME}/.aws/credentials"
    }
  ]
}

This lets you mount the secret in your Dockerfile.

RUN --mount=type=secret,id=aws,target=/root/.aws/credentials \
    aws cloudfront create-invalidation ...
RUN --mount=type=secret,id=KUBECONFIG,env=KUBECONFIG \
    helm upgrade --install

You can override the source for an existing secret without changing the target's
secret IDs. The secret must already be declared by the target.

$ docker buildx bake --set default.secret.aws=env=AWS_CREDENTIALS
$ docker buildx bake --set default.secret.KUBECONFIG=src=/path/to/kubeconfig

`target.shm-size` Copy Section

Sets the size of the shared memory allocated for build containers when using
RUN instructions.

The format is <number>. number must be greater than 0. Unit is
optional and can be b (bytes), k (kilobytes), m (megabytes), or g
(gigabytes). If you omit the unit, the system uses bytes.

This is the same as the --shm-size flag for docker build.

target "default" {
  shm-size = "128m"
}

[!NOTE]
In most cases, it is recommended to let the builder automatically determine
the appropriate configurations. Manual adjustments should only be considered
when specific performance tuning is required for complex build scenarios.

`target.ssh` Copy Section

Defines SSH agent sockets or keys to expose to the build.
This is the same as the --ssh flag.
This can be useful if you need to access private repositories during a build.

target "default" {
  ssh = [{ id = "default" }]
}

FROM alpine
RUN --mount=type=ssh \
    apk add git openssh-client \
    && install -m 0700 -d ~/.ssh \
    && ssh-keyscan github.com >> ~/.ssh/known_hosts \
    && git clone [email protected]:user/my-private-repo.git

[!NOTE]
When overriding ssh from the command line with --set, use the inline
id=path string form rather than the object form shown above, for example
docker buildx bake --set "*.ssh=default=$HOME/.ssh/id_ed25519". Separate
multiple paths with commas. See bake --set for details.

`target.tags` Copy Section

Image names and tags to use for the build target.
This is the same as the --tag flag.

target "default" {
  tags = [
    "org/repo:latest",
    "myregistry.azurecr.io/team/image:v1"
  ]
}

`target.target` Copy Section

Set the target build stage to build.
This is the same as the --target flag.

target "default" {
  target = "binaries"
}

`target.ulimits` Copy Section

Ulimits overrides the default ulimits of build's containers when using RUN
instructions and are specified with a soft and hard limit as such:
<type>=<soft limit>[:<hard limit>], for example:

target "app" {
  ulimits = [
    "nofile=1024:1024"
  ]
}

[!NOTE]
If you do not provide a hard limit, the soft limit is used
for both values. If no ulimits are set, they are inherited from
the default ulimits set on the daemon.

[!NOTE]
In most cases, it is recommended to let the builder automatically determine
the appropriate configurations. Manual adjustments should only be considered
when specific performance tuning is required for complex build scenarios.

Group Copy Chapter

Groups allow you to invoke multiple builds (targets) at once.

group "default" {
  targets = ["db", "webapp-dev"]
}

target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
}

target "db" {
  dockerfile = "Dockerfile.db"
  tags = ["docker.io/username/db"]
}

Groups take precedence over targets, if both exist with the same name.
The following bake file builds the default group.
Bake ignores the default target.

target "default" {
  dockerfile-inline = "FROM ubuntu"
}

group "default" {
  targets = ["alpine", "debian"]
}
target "alpine" {
  dockerfile-inline = "FROM alpine"
}
target "debian" {
  dockerfile-inline = "FROM debian"
}

Variable Copy Chapter

The HCL file format supports variable block definitions.
You can use variables as build arguments in your Dockerfile,
or interpolate them in attribute values in your Bake file.

variable "TAG" {
  type = string
  default = "latest"
  description = "Tag to use for build"
}

target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:${TAG}"]
}

You can assign a default value for a variable in the Bake file,
or assign a null value to it. If you assign a null value,
Buildx uses the default value from the Dockerfile instead.

You can also add a description of the variable's purpose with the description field. This attribute is useful when combined with the docker buildx bake --list=variables option, providing a more informative output when listing the available variables in a Bake file.

You can override variable defaults set in the Bake file using environment variables.
The following example sets the TAG variable to dev,
overriding the default latest value shown in the previous example.

$ TAG=dev docker buildx bake webapp-dev

Variables can also be assigned an explicit type.
If provided, it will be used to validate the default value (if set), as well as any overrides.
This is particularly useful when using complex types which are intended to be overridden.
The previous example could be expanded to apply an arbitrary series of tags.

variable "TAGS" {
  default = ["latest"]
  type = list(string)
}

target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = [for tag in TAGS: "docker.io/username/webapp:${tag}"]
}

This example shows how to generate three tags without changing the file
or using custom functions/parsing:

$ TAGS=dev,latest,2 docker buildx bake webapp-dev

Variable typing Copy Section

The following primitive types are available:

• string
• number
• bool

The type is expressed like a keyword; it must be expressed as a literal:

variable "OK" {
  type = string
}

# cannot be an actual string
variable "BAD" {
  type = "string"
}

# cannot be the result of an expression
variable "ALSO_BAD" {
  type = lower("string")
}

Specifying primitive types can be valuable to show intent (especially when a default is not provided),
but bake will generally behave as expected without explicit typing.

Complex types are expressed with "type constructors"; they are:

• tuple([<type>,...])
• list(<type>)
• set(<type>)
• map(<type>)
• object({<attr>=<type>},...})

The following are examples of each of those, as well as how the (optional) default value would be expressed:

# structured way to express "1.2.3-alpha"
variable "MY_VERSION" {
  type = tuple([number, number, number, string])
  default = [1, 2, 3, "alpha"]
}

# JDK versions used in a matrix build
variable "JDK_VERSIONS" {
  type = list(number)
  default = [11, 17, 21]
}

# better way to express the previous example; this will also
# enforce set semantics and allow use of set-based functions
variable "JDK_VERSIONS" {
  type = set(number)
  default = [11, 17, 21]
}

# with the help of lookup(), translate a 'feature' to a tag
variable "FEATURE_TO_NAME" {
  type = map(string)
  default = {featureA = "slim", featureB = "tiny"}
}

# map a branch name to a registry location
variable "PUSH_DESTINATION" {
  type = object({branch = string, registry = string})
  default = {branch = "main", registry = "prod-registry.invalid.com"}
}

# make the previous example more useful with composition
variable "PUSH_DESTINATIONS" {
  type = list(object({branch = string, registry = string}))
  default = [
    {branch = "develop", registry = "test-registry.invalid.com"},
    {branch = "main", registry = "prod-registry.invalid.com"},
  ]
}

Note that in each example, the default value would be valid even if typing was not present.
If typing was omitted, the first three would all be considered tuple;
you would be restricted to functions that operate on tuple and, for example, not be able to add elements.
Similarly, the third and fourth would both be considered object, with the limits and semantics of that type.
In short, in the absence of a type, any value delimited with [] is a tuple
and value delimited with {} is an object.
Explicit typing for complex types not only opens up the ability to use functions applicable to that specialized type,
but is also a precondition for providing overrides.

[!NOTE]
See HCL Type Expressions page for more details.

Overriding variables Copy Section

As mentioned in the intro to variables, primitive types (string, number, and bool)
can be overridden without typing and will generally behave as expected.
(When explicit typing is not provided, a variable is assumed to be primitive when the default value lacks {} or [] delimiters;
a variable with neither typing nor a default value is treated as string.)
Naturally, these same overrides can be used alongside explicit typing too;
they may help in edge cases where you want VAR=true to be a string, where without typing,
it may be a string or a bool depending on how/where it's used.
Overriding a variable with a complex type can only be done when the type is provided.
This is still done via environment variables, but the values can be provided via CSV or JSON.

CSV overrides

This is considered the canonical method and is well suited to interactive usage.
It is assumed that list and set will be the most common complex type,
as well as the most common complex type designed to be overridden.
Thus, there is full CSV support for list and set
(and tuple; despite being considered a structural type, it is more like a collection type in this regard).

There is limited support for map and object and no support for composite types;
for these advanced cases, an alternative mechanism using JSON is available.

JSON overrides

Overrides can also be provided via JSON.
This is the only method available for providing some complex types and may be convenient if overrides are already JSON
(for example, if they come from a JSON API).
It can also be used when dealing with values are difficult or impossible to specify using CSV (e.g., values containing quotes or commas).
To use JSON, simply append _JSON to the variable name.
In this contrived example, CSV cannot handle the second value; despite being a supported CSV type, JSON must be used:

variable "VALS" {
  type = list(string)
  default = ["some", "list"]
}

$ cat data.json
["hello","with,comma","with\"quote"]
$ VALS_JSON=$(< data.json) docker buildx bake

# CSV equivalent, though the second value cannot be expressed at all 
$ VALS='hello,"with""quote"' docker buildx bake

This example illustrates some precedence and usage rules:

variable "FOO" {
  type = string
  default = "foo"
}

variable "FOO_JSON" {
  type = string
  default = "foo"
}

The variable FOO can only be overridden using CSV because FOO_JSON, which would typically used for a JSON override,
is already a defined variable.
Since FOO_JSON is an actual variable, setting that environment variable would be expected to a CSV value.
A JSON override is possible for this variable, using environment variable FOO_JSON_JSON.

# These three are all equivalent, setting variable FOO=bar
$ FOO=bar docker buildx bake <...>
$ FOO='bar' docker buildx bake <...>
$ FOO="bar" docker buildx bake <...>

# Sets *only* variable FOO_JSON; FOO is untouched
$ FOO_JSON=bar docker buildx bake <...>

# This also sets FOO_JSON, but will fail due to not being valid JSON
$ FOO_JSON_JSON=bar docker buildx bake <...>

# These are all equivalent
$ cat data.json
"bar"
$ FOO_JSON_JSON=$(< data.json) docker buildx bake <...>
$ FOO_JSON_JSON='"bar"' docker buildx bake <...>
$ FOO_JSON=bar docker buildx bake <...>

# This results in setting two different variables, both specified as CSV (FOO=bar and FOO_JSON="baz")
$ FOO=bar FOO_JSON='"baz"' docker buildx bake <...>

# These refer to the same variable with FOO_JSON_JSON having precedence and read as JSON (FOO_JSON=baz)
$ FOO_JSON=bar FOO_JSON_JSON='"baz"' docker buildx bake <...>

Built-in variables Copy Section

The following variables are built-ins that you can use with Bake without having
to define them.

Use environment variable as default Copy Section

If an environment variable exists with the same name as a declared Bake
variable, Bake uses that environment variable value instead of the declared
default.

To disable this environment-based variable lookup, set
BUILDX_BAKE_DISABLE_VARS_ENV_LOOKUP=1.

variable "HOME" {
  default = "/root"
}

Interpolate variables into attributes Copy Section

To interpolate a variable into an attribute string value,
you must use curly brackets.
The following doesn't work:

variable "HOME" {
  default = "$HOME"
}

target "default" {
  ssh = ["default=$HOME/.ssh/id_rsa"]
}

Wrap the variable in curly brackets where you want to insert it:

variable "HOME" {
    default = "$HOME"
  }

  target "default" {
-   ssh = ["default=$HOME/.ssh/id_rsa"]
+   ssh = ["default=${HOME}/.ssh/id_rsa"]
  }

Before you can interpolate a variable into an attribute,
first you must declare it in the bake file,
as demonstrated in the following example.

$ cat docker-bake.hcl
target "default" {
  dockerfile-inline = "FROM ${BASE_IMAGE}"
}
$ docker buildx bake
[+] Building 0.0s (0/0)
docker-bake.hcl:2
--------------------
   1 |     target "default" {
   2 | >>>   dockerfile-inline = "FROM ${BASE_IMAGE}"
   3 |     }
   4 |
--------------------
ERROR: docker-bake.hcl:2,31-41: Unknown variable; There is no variable named "BASE_IMAGE"., and 1 other diagnostic(s)
$ cat >> docker-bake.hcl

variable "BASE_IMAGE" {
  default = "alpine"
}

$ docker buildx bake
[+] Building 0.6s (5/5) FINISHED

Function Copy Chapter

A set of general-purpose functions provided by go-cty
are available for use in HCL files:

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    buildno = "${add(123, 1)}"
  }
}

In addition, user defined functions
are also supported:

# docker-bake.hcl
function "increment" {
  params = [number]
  result = number + 1
}

target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    buildno = "${increment(123)}"
  }
}

[!NOTE]
See User defined HCL functions page for more details.

File: _vendor/github.com/docker/buildx/docs/bake-stdlib.md Copy Chapter

title: Bake standard library functions Copy Chapter

`absolute` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    val = "${absolute(-42)}" # => 42
  }
}

`add` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${add(123, 1)}" # => 124
  }
}

`and` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${and(true, false)}" # => false
  }
}

`base64decode` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    decoded = "${base64decode("SGVsbG8=")}" # => "Hello"
  }
}

`base64encode` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    encoded = "${base64encode("Hello")}" # => "SGVsbG8="
  }
}

`basename` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    file = "${basename("/usr/local/bin/docker")}" # => "docker"
  }
}

`bcrypt` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    hash = "${bcrypt("mypassword")}" # => "$2a$10$..."
  }
}

`byteslen` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    length = "${byteslen("Docker")}" # => 6
  }
}

`bytesslice` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    part = "${bytesslice("Docker", 0, 3)}" # => "Doc"
  }
}

`can` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    safe = "${can(parseint("123", 10))}" # => true
  }
}

`ceil` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    rounded = "${ceil(3.14)}" # => 4"
  }
}

`chomp` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${chomp("Hello\n\n")}" # => "Hello"
  }
}

`chunklist` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${chunklist([1,2,3,4,5], 2)}"     # => [[1,2],[3,4],[5]]
  }
}

`cidrhost` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${cidrhost("10.0.0.0/16", 5)}"   # => "10.0.0.5"
  }
}

`cidrnetmask` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    mask = "${cidrnetmask("10.0.0.0/16")}"     # => "255.255.0.0"
  }
}

`cidrsubnet` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    subnet = "${cidrsubnet("10.0.0.0/16", 4, 2)}" # => "10.0.32.0/20"
  }
}

`cidrsubnets` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    subs = "${cidrsubnets("10.0.0.0/16", 4, 4)}" # => ["10.0.0.0/20","10.0.16.0/20",...]
  }
}

`coalesce` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    first = "${coalesce(null, "", "docker")}"  # => "docker"
  }
}

`coalescelist` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    first = "${coalescelist([], [1,2], [3])}" # => [1,2]
  }
}

`compact` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    list = "${compact(["a", "", "b", ""])}" # => ["a","b"]
  }
}

`concat` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    list = "${concat([1,2],[3,4])}" # => [1,2,3,4]
  }
}

`contains` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    check = "${contains([1,2,3], 2)}" # => true
  }
}

`convert` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${convert("42", number)}" # => 42
  }
}

`csvdecode` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    data = "${csvdecode("name,age\nAlice,30\nBob,40")}" # => [{"name":"Alice","age":"30"},{"name":"Bob","age":"40"}]
  }
}

`dirname` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    dir = "${dirname("/usr/local/bin/docker")}" # => "/usr/local/bin"
  }
}

`distinct` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${distinct([1,2,2,3,3,3])}" # => [1,2,3]
  }
}

`divide` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${divide(10, 2)}" # => 5
  }
}

`element` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    val = "${element(["a","b","c"], 1)}" # => "b"
  }
}

`equal` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    check = "${equal(2, 2)}" # => true
  }
}

`flatten` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    flat = "${flatten([[1,2],[3,4],[5]])}" # => [1,2,3,4,5]
  }
}

`floor` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${floor(3.99)}" # => 3
  }
}

`format` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${format("Hello, %s!", "World")}" # => "Hello, World!"
  }
}

`formatdate` Copy Chapter

[!WARNING]
Deprecated: use formattimestamp instead. formatdate only accepts RFC3339
timestamp strings.

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    date = "${formatdate("YYYY-MM-DD", "2025-09-16T12:00:00Z")}" # => "2025-09-16"
  }
}

`formattimestamp` Copy Chapter

Formats either an RFC3339 timestamp string or a unix timestamp integer.
The special format X returns the unix timestamp in seconds.

# docker-bake.hcl
variable "SOURCE_DATE_EPOCH" {
  type    = number
  default = formattimestamp("X", "2015-10-21T00:00:00Z") # => 1445385600
}

target "default" {
  dockerfile = "Dockerfile"
  labels = {
    "org.opencontainers.image.created" = formattimestamp("YYYY-MM-DD'T'hh:mm:ssZ", SOURCE_DATE_EPOCH) # => "2015-10-21T00:00:00Z"
  }
  args = {
    build_date = formattimestamp("YYYY-MM-DD", "2025-09-16T12:00:00Z") # => "2025-09-16"
  }
}

`formatlist` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    list = "${formatlist("Hi %s", ["Alice", "Bob"])}" # => ["Hi Alice","Hi Bob"]
  }
}

`greaterthan` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${greaterthan(2, 5)}" # => true
  }
}

`greaterthanorequalto` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${greaterthanorequalto(5, 5)}" # => true
  }
}

`hasindex` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    exists = "${hasindex([10, 20, 30], 1)}"  # => true
    missing = "${hasindex([10, 20, 30], 5)}" # => false
  }
}

`homedir` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    home = "${homedir()}" # => e.g., "/home/user"
  }
}

`indent` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    text = "${indent(4, "Hello\nWorld")}" 
    # => "    Hello\n    World"
  }
}

`index` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    val = "${index({foo = "bar", baz = "qux"}, "baz")}" # => "qux"
  }
}

`indexof` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    pos = "${indexof(["a","b","c"], "b")}" # => 1
  }
}

`int` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    number = "${int(3.75)}" # => 3
  }
}

`join` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    csv = "${join(",", ["a","b","c"])}" # => "a,b,c"
  }
}

`jsondecode` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    obj = "${jsondecode("{\"name\":\"Docker\",\"stars\":5}")}" # => {"name":"Docker","stars":5}
  }
}

`jsonencode` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    str = "${jsonencode({name="Docker", stars=5})}" # => "{\"name\":\"Docker\",\"stars\":5}"
  }
}

`keys` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    list = "${keys({foo = 1, bar = 2, baz = 3})}" 
    # => ["bar","baz","foo"] (sorted order)
  }
}

`length` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    size = "${length([1,2,3,4])}" # => 4
  }
}

`lessthan` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${lessthan(10, 3)}" # => false
  }
}

`lessthanorequalto` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${lessthanorequalto(5, 7)}" # => true
  }
}

`log` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    val = "${log(100, 10)}" # => 2
  }
}

`lookup` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    found    = "${lookup({a="apple", b="banana"}, "a", "none")}" # => "apple"
    fallback = "${lookup({a="apple", b="banana"}, "c", "none")}" # => "none"
  }
}

`lower` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    val = "${lower("HELLO")}" # => "hello"
  }
}

`max` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${max(3, 9, 7)}" # => 9
  }
}

`md5` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    hash = "${md5("docker")}" # => "597dd5f6a..." (hex string)
  }
}

`merge` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    combined = "${merge({a=1, b=2}, {b=3, c=4})}" # => {a=1, b=3, c=4}
  }
}

`min` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${min(3, 9, 7)}" # => 3
  }
}

`modulo` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${modulo(10, 3)}" # => 1
  }
}

`multiply` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${multiply(6, 7)}" # => 42
  }
}

`negate` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${negate(7)}" # => -7
  }
}

`not` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${not(true)}" # => false
  }
}

`notequal` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${notequal(4, 5)}" # => true
  }
}

`or` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${or(true, false)}" # => true
  }
}

`parseint` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${parseint("ff", 16)}" # => 255
  }
}

`pow` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${pow(3, 2)}" # => 9
  }
}

`range` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${range(0, 5)}" # => [0,1,2,3,4]
  }
}

`regex` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${regex("h.llo", "hello")}" # => "hello"
  }
}

`regex_replace` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${regex_replace("[0-9]+", "abc123xyz", "NUM")}" # => "abcNUMxyz"
  }
}

`regexall` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = matches = "${regexall("[a-z]+", "abc123xyz")}" # => ["abc","xyz"]
  }
}

`replace` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${replace("banana", "na", "--")}" # => "ba-- --"
  }
}

`reverse` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${reverse("stressed")}" # => "desserts"
  }
}

`reverselist` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${reverselist([1,2,3])}" # => [3,2,1]
  }
}

`rsadecrypt` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${rsadecrypt("eczGaDhXDbOFRZ...", "MIIEowIBAAKCAQEAgUElV5...")}"
  }
}

`sanitize` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${sanitize("My App! v1.0")}" # => "My_App__v1_0"
  }
}

`semvercmp` Copy Chapter

This function checks if a semantic version fits within a set of constraints.
See Checking Version Constraints
for details.

# docker-bake.hcl
variable "ALPINE_VERSION" {
  default = "3.23"
}

target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  platforms = semvercmp(ALPINE_VERSION, ">= 3.20") ? [
    "linux/amd64",
    "linux/arm64",
    "linux/riscv64"
  ] : [
    "linux/amd64",
    "linux/arm64"
  ]
}

`sethaselement` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${sethaselement([1,2,3], 2)}"  # => true
  }
}

`setintersection` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${setintersection(["a","b","c"], ["b","c","d"])}" # => ["b","c"]
  }
}

`setproduct` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${setproduct(["x","y"], [1,2])}" # => [["x",1],["x",2],["y",1],["y",2]]
  }
}

`setsubtract` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${setsubtract([1,2,3], [2])}" # => [1,3]
  }
}

`setsymmetricdifference` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${setsymmetricdifference([1,2,3], [3,4])}" # => [1,2,4]
  }
}

`setunion` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${setunion(["a","b"], ["b","c"])}" # => ["a","b","c"]
  }
}

`sha1` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${sha1("hello")}" # => "aaf4c61d..." (hex)
  }
}

`sha256` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${sha256("hello")}" # => "2cf24dba..." (hex)
  }
}

`sha512` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${sha512("hello")}" # => "9b71d224..." (hex)
  }
}

`signum` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    zero = "${signum(0)}"    # => 0
    pos  = "${signum(12)}"   # => 1
    neg  = "${signum(-12)}"  # => -1
  }
}

`slice` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${slice(["a","b","c","d"], 1, 3)}" # => ["b","c"]
  }
}

`sort` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${sort(["b","c","a"])}" # => ["a","b","c"]
  }
}

`split` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${split(",", "a,b,c")}" # => ["a","b","c"]
  }
}

`strlen` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${strlen("Docker")}" # => 6
  }
}

`substr` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${substr("abcdef", 2, 3)}" # => "cde"
  }
}

`subtract` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${subtract(10, 3)}" # => 7
  }
}

`timeadd` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${timeadd("2025-09-24T12:00:00Z", "1h30m")}" # => "2025-09-24T13:30:00Z"
  }
}

`timestamp` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${timestamp()}" # => current RFC3339 time at evaluation
  }
}

`title` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${title("hello world-from_docker")}" # => "Hello World-From_Docker"
  }
}

`trim` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${trim("--hello--", "-")}" # => "hello"
  }
}

`trimprefix` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${trimprefix("docker-build", "docker-")}" # => "build"
  }
}

`trimspace` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${trimspace("   hello   ")}" # => "hello"
  }
}

`trimsuffix` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${trimsuffix("filename.txt", ".txt")}" # => "filename"
  }
}

`try` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    # First expr errors (invalid hex), second succeeds → returns 255
    val1 = "${try(parseint("zz", 16), parseint("ff", 16))}" # => 255

    # First expr errors (missing key), fallback string is used
    val2 = "${try(index({a="apple"}, "b"), "fallback")}"    # => "fallback"
  }
}

`unixtimestampparse` Copy Chapter

The returned object has the following attributes:

• year (Number) The year for the unix timestamp.
• year_day (Number) The day of the year for the unix timestamp, in the range 1-365 for non-leap years, and 1-366 in leap years.
• day (Number) The day of the month for the unix timestamp.
• month (Number) The month of the year for the unix timestamp.
• month_name (String) The name of the month for the unix timestamp (ex. "January").
• weekday (Number) The day of the week for the unix timestamp.
• weekday_name (String) The name of the day for the unix timestamp (ex. "Sunday").
• hour (Number) The hour within the day for the unix timestamp, in the range 0-23.
• minute (Number) The minute offset within the hour for the unix timestamp, in the range 0-59.
• second (Number) The second offset within the minute for the unix timestamp, in the range 0-59.
• rfc3339 (String) The RFC3339 format string.
• iso_year (Number) The ISO 8601 year number.
• iso_week (Number) The ISO 8601 week number.

# docker-bake.hcl
variable "SOURCE_DATE_EPOCH" {
  type    = number
  default = 1690328596
}

target "default" {
  args = {
    SOURCE_DATE_EPOCH = SOURCE_DATE_EPOCH
  }
  labels = {
    "org.opencontainers.image.created" = unixtimestampparse(SOURCE_DATE_EPOCH).rfc3339
  }
}

`upper` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${upper("hello")}" # => "HELLO"
  }
}

`urlencode` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    url = "${urlencode("a b=c&d")}" # => "a+b%3Dc%26d"
  }
}

`uuidv4` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    id = "${uuidv4()}" # => random v4 UUID each evaluation
  }
}

`uuidv5` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    # Uses the DNS namespace UUID per RFC 4122
    # "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
    id = "${uuidv5("6ba7b810-9dad-11d1-80b4-00c04fd430c8", "example.com")}"
    # => always "9073926b-929f-31c2-abc9-fad77ae3e8eb" for "example.com"
  }
}

`values` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    vals = "${values({a=1, c=3, b=2})}" # => [1,2,3] (ordered by key: a,b,c)
  }
}

`zipmap` Copy Chapter

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    obj = "${zipmap(["name","stars"], ["Docker", 5])}" # => {name="Docker", stars=5}
  }
}

File: _vendor/github.com/docker/cli/docs/deprecated.md Copy Chapter

title: Deprecated Docker Engine features linkTitle: Deprecated features aliases: ["/engine/misc/deprecated/"] keywords: "docker, documentation, about, technology, deprecate" Copy Chapter

This page provides an overview of features that are deprecated in Engine. Changes
in packaging, and supported (Linux) distributions are not included. To learn
about end of support for Linux distributions, refer to the
release notes.

Feature deprecation policy Copy Chapter

As changes are made to Docker there may be times when existing features need to
be removed or replaced with newer features. Before an existing feature is removed
it is labeled as "deprecated" within the documentation and remains in Docker for
at least one stable release unless specified explicitly otherwise. After that time
it may be removed.

Users are expected to take note of the list of deprecated features each release
and plan their migration away from those features, and (if applicable) towards
the replacement features as soon as possible.

Deprecated engine features Copy Chapter

The following table provides an overview of the current status of deprecated features:

• Deprecated: the feature is marked "deprecated" and should no longer be used.

  The feature may be removed, disabled, or change behavior in a future release.
  The "Deprecated" column contains the release in which the feature was marked
  deprecated, whereas the "Remove" column contains a tentative release in which
  the feature is to be removed. If no release is included in the "Remove" column,
  the release is yet to be decided on.

• Removed: the feature was removed, disabled, or hidden.

  Refer to the linked section for details. Some features are "soft" deprecated,
  which means that they remain functional for backward compatibility, and to
  allow users to migrate to alternatives. In such cases, a warning may be
  printed, and users should not rely on this feature.

Support for cgroup v1 Copy Section

Deprecated in release: v29.0

Support for cgroup v1 is deprecated in the v29.0 release, however, it will continue
to be supported until May 2029.
The latest release in May 2029 may not necessarily support cgroup v1,
but there will be at least one maintained branch with the support for cgroup v1.

The cgroup version currently in use can be checked by running the docker info command:

$ docker info
<...>
Server:
 <...>
 Cgroup Version: 2
 <...>

`--pause` option on `docker commit` Copy Section

Deprecated in release: v29.0

Target for removal in release: v30.0

The --pause option is enabled by default since Docker v1.1.0 to prevent
committing containers in an inconsistent state, but can be disabled by
setting the --pause=false option. In docker CLI v29.0 this flag is
replaced by a --no-pause flag instead. The --pause option is still
functional in the v29.0 release, printing a deprecation warning, but
will be removed in docker CLI v30.

Legacy links environment variables Copy Section

Deprecated in release: v28.4

Disabled by default in release: v29.0

Target for removal in release: v30.0

Containers attached to the default bridge network can specify "legacy links" (e.g.
using --links on the CLI) to get access to other containers attached to that
network. The linking container (i.e., the container created with --links) automatically
gets environment variables that specify the IP address and port mappings of the linked
container. However, these environment variables are prefixed with the linked
container's names, making them impractical.

Starting with Docker v29.0, these environment variables are no longer set by
default. Users who still depend on them can start Docker Engine with the
environment variable DOCKER_KEEP_DEPRECATED_LEGACY_LINKS_ENV_VARS=1 set.

Support for legacy links environment variables, as well as the DOCKER_KEEP_DEPRECATED_LEGACY_LINKS_ENV_VARS
will be removed in Docker Engine v30.0.

Special handling for quoted values for TLS flags Copy Section

Deprecated in release: v28.4

Target for removal in release: v29.0

The --tlscacert, --tlscert, and --tlskey command-line flags had
non-standard behavior for handling values contained in quotes (" or ').
Normally, quotes are handled by the shell, for example, in the following
example, the shell takes care of handling quotes before passing the values
to the docker CLI:

docker --some-option "some-value-in-quotes" ...

However, when passing values using an equal sign (=), this may not happen
and values may be handled including quotes;

docker --some-option="some-value-in-quotes" ...

This caused issues with "Docker Machine", which used this format as part
of its docker-machine config output, and the CLI carried special, non-standard
handling for these flags.

Docker Machine reached EOL, and this special handling made the processing
of flag values inconsistent with other flags used, so this behavior is
deprecated. Users depending on this behavior are recommended to specify
the quoted values using a space between the flag and its value, as illustrated
above.

Empty/nil fields in image Config from inspect API Copy Section

Deprecated in release: v28.3

Target for removal in release: v29.0

The Config field returned by docker image inspect (and the GET /images/{name}/json
API endpoint) currently includes certain fields even when they are empty or nil.
Starting in Docker v29.0, the following fields will be omitted from the API response
when they contain empty or default values:

• Cmd
• Entrypoint
• Env
• Labels
• OnBuild
• User
• Volumes
• WorkingDir

Applications consuming the image inspect API should be updated to handle the
absence of these fields gracefully, treating missing fields as having their
default/empty values.

For API version corresponding to Docker v29.0, these fields will be omitted when
empty. They will continue to be included when using clients that request an older
API version for backward compatibility.

Configuration for pushing non-distributable artifacts Copy Section

Deprecated in release: v28.0

Target for removal in release: v29.0

Non-distributable artifacts (also called foreign layers) were introduced in
docker v1.12 to accommodate Windows images for which the EULA did not allow
layers to be distributed through registries other than those hosted by Microsoft.
The concept of foreign / non-distributable layers was adopted by the OCI distribution
spec in oci#233. These restrictions were relaxed later to allow distributing
these images through non-public registries, for which a configuration was added
in Docker v17.0.6.0.

In 2022, Microsoft updated the EULA and removed these restrictions,
followed by the OCI distribution specification deprecating foreign layers in oci#965.
In 2023, Microsoft removed the use of foreign data layers for their images,
making this functionality obsolete.

Docker v28.0 deprecates the --allow-nondistributable-artifacts daemon flag and
corresponding allow-nondistributable-artifacts field in daemon.json. Setting
either option no longer takes an effect, but a deprecation warning log is added
to raise awareness about the deprecation. This warning is planned to become an
error in the Docker v29.0.

Users currently using these options are therefore recommended to remove this
option from their configuration to prevent the daemon from starting when
upgrading to Docker v29.0.

The AllowNondistributableArtifactsCIDRs and AllowNondistributableArtifactsHostnames
fields in the RegistryConfig of the GET /info API response are also deprecated.
For API version v1.48 and lower, the fields are still included in the response
but always null. In API version v1.49 and higher, the field will be omitted
entirely.

`--time` option on `docker stop` and `docker restart` Copy Section

Deprecated in release: v28.0

The --time option for the docker stop, docker container stop, docker restart,
and docker container restart commands has been renamed to --timeout for
consistency with other uses of timeout options. The --time option is now
deprecated and hidden, but remains functional for backward compatibility.
Users are encouraged to migrate to using the --timeout option instead.

Non-standard fields in image inspect Copy Section

Deprecated in release: v27.0

Removed in release: v28.2

The Config field returned shown in docker image inspect (and as returned by
the GET /images/{name}/json API endpoint) returns additional fields that are
not part of the image's configuration and not part of the Docker image specification
and OCI image specification.

These fields are never set (and always return the default value for the type),
but are not omitted in the response when left empty. As these fields were not
intended to be part of the image configuration response, they are deprecated,
and will be removed from the API in thee next release.

The following fields are not part of the underlying image's Config field, and
removed in the API response for API v1.50 and newer, corresponding with v28.2.
They continue to be included when using clients that use an older API version:

• Hostname
• Domainname
• AttachStdin
• AttachStdout
• AttachStderr
• Tty
• OpenStdin
• StdinOnce
• Image
• NetworkDisabled (omitted unless set on older API versions)
• MacAddress (omitted unless set on older API versions)
• StopTimeout (omitted unless set on older API versions)

Graphdriver plugins (experimental) Copy Section

Deprecated in: v27.0**.

Disabled by default in release: v27.0

Target for removal in release: v28.0

Graphdriver plugins
were an experimental feature that allowed extending the Docker Engine with custom
storage drivers for storing images and containers. This feature was not
maintained since its inception.

Support for graphdriver plugins was disabled by default in v27.0, and removed
in v28.0. Users of this feature are recommended to instead configure the Docker
Engine to use the containerd image store
and a custom snapshotter

API CORS headers Copy Section

Deprecated in release: v27.0

Disabled by default in release: v27.0

Removed in release: v28.0

The api-cors-header configuration option for the Docker daemon is insecure,
and is therefore deprecated and scheduled for removal.
Incorrectly setting this option could leave a window of opportunity
for unauthenticated cross-origin requests to be accepted by the daemon.

In Docker Engine v27.0, this flag can still be set,
but it has no effect unless the environment variable
DOCKERD_DEPRECATED_CORS_HEADER is also set to a non-empty value.

This flag has been removed altogether in v28.0.

This is a breaking change for authorization plugins and other programs
that depend on this option for accessing the Docker API from a browser.
If you need to access the API through a browser, use a reverse proxy.

Unauthenticated TCP connections Copy Section

Deprecated in release: v26.0

Target for removal in release: v28.0

Configuring the Docker daemon to listen on a TCP address will require mandatory
TLS verification. This change aims to ensure secure communication by preventing
unauthorized access to the Docker daemon over potentially insecure networks.
This mandatory TLS requirement applies to all TCP addresses except tcp://localhost.

In version 27.0 and later, specifying --tls=false or --tlsverify=false CLI flags
causes the daemon to fail to start if it's also configured to accept remote connections over TCP.
This also applies to the equivalent configuration options in daemon.json.

To facilitate remote access to the Docker daemon over TCP, you'll need to
implement TLS verification. This secures the connection by encrypting data in
transit and providing a mechanism for mutual authentication.

For environments remote daemon access isn't required,
we recommend binding the Docker daemon to a Unix socket.
For daemons where remote access is required and where TLS encryption is not feasible,
you may want to consider using SSH as an alternative solution.

For further information, assistance, and step-by-step instructions on
configuring TLS (or SSH) for the Docker daemon, refer to
Protect the Docker daemon socket.

`Container` and `ContainerConfig` fields in Image inspect Copy Section

Deprecated in release: v25.0

Removed in release: v26.0

The Container and ContainerConfig fields returned by docker inspect are
mostly an implementation detail of the classic (non-BuildKit) image builder.
These fields are not portable and are empty when using the
BuildKit-based builder (enabled by default since v23.0).
These fields are deprecated in v25.0 and are omitted starting from v26.0 (
API version v1.45 and up). If image configuration of an image is needed,
you can obtain it from the Config field.

Deprecate legacy API versions Copy Section

Deprecated in release: v25.0

Target for removal in release: v26.0

The Docker daemon provides a versioned API for backward compatibility with old
clients. Docker clients can perform API-version negotiation to select the most
recent API version supported by the daemon (downgrading to and older version of
the API when necessary). API version negotiation was introduced in Docker v1.12.0
(API 1.24), and clients before that used a fixed API version.

Docker Engine versions through v25.0 provide support for all API versions
included in stable releases for a given platform. For Docker daemons on Linux,
the earliest supported API version is 1.12 (corresponding with Docker Engine
v1.0.0), whereas for Docker daemons on Windows, the earliest supported API
version is 1.24 (corresponding with Docker Engine v1.12.0).

Support for legacy API versions (providing old API versions on current versions
of the Docker Engine) is primarily intended to provide compatibility with recent,
but still supported versions of the client, which is a common scenario (the Docker
daemon may be updated to the latest release, but not all clients may be up-to-date
or vice versa). Support for API versions before that (API versions provided by
EOL versions of the Docker Daemon) is provided on a "best effort" basis.

Use of old API versions is rare, and support for legacy API versions
involves significant complexity (Docker 1.0.0 having been released 10 years ago).
Because of this, we'll start deprecating support for legacy API versions.

Docker Engine v25.0 by default disables API version older than 1.24 (aligning
the minimum supported API version between Linux and Windows daemons). When
connecting with a client that uses an API version older than 1.24,
the daemon returns an error. The following example configures the Docker
CLI to use API version 1.23, which produces an error:

DOCKER_API_VERSION=1.23 docker version
Error response from daemon: client version 1.23 is too old. Minimum supported API version is 1.24,
upgrade your client to a newer version

Support for API versions lower than 1.24 has been permanently removed in Docker
Engine v26, and the minimum supported API version will be incrementally raised
in releases following that.

Container short ID in network Aliases field Copy Section

Deprecated in release: v25.0

Removed in release: v26.0

The Aliases field returned by docker inspect contains the container short
ID once the container is started. This behavior is deprecated in v25.0 but
kept until the next release, v26.0. Starting with that version, the Aliases
field will only contain the aliases set through the docker container create
and docker run flag --network-alias.

A new field DNSNames containing the container name (if one was specified),
the hostname, the network aliases, as well as the container short ID, has been
introduced in v25.0 and should be used instead of the Aliases field.

Mount `bind-nonrecursive` option Copy Section

Deprecated in release: v25.0

Removed in release: v29.0

The bind-nonrecursive option was replaced with the bind-recursive
option (see cli-4316, cli-4671). The option was still accepted, but
printed a deprecation warning:

bind-nonrecursive is deprecated, use bind-recursive=disabled instead

In the v29.0 release, this warning is removed, and returned as an error.
Users should use the equivalent bind-recursive=disabled option instead.

IsAutomated field, and `is-automated` filter on `docker search` Copy Section

Deprecated in release: v25.0

Removed in release: v28.2

The is_automated field has been deprecated by Docker Hub's search API.
Consequently, the IsAutomated field in image search will always be set
to false in future, and searching for "is-automated=true" will yield no
results.

The AUTOMATED column has been removed from the default docker search
and docker image search output in v25.0, and the corresponding IsAutomated
templating has been removed in v28.2.

Logentries logging driver Copy Section

Deprecated in release: v24.0

Removed in release: v25.0

The logentries service SaaS was shut down on November 15, 2022, rendering
this logging driver non-functional. Users should no longer use this logging
driver, and the driver has been removed in Docker 25.0. Existing containers
using this logging-driver are migrated to use the "local" logging driver
after upgrading.

OOM-score adjust for the daemon Copy Section

Deprecated in release: v24.0

Removed in release: v25.0

The oom-score-adjust option was added to prevent the daemon from being
OOM-killed before other processes. This option was mostly added as a
convenience, as running the daemon as a systemd unit was not yet common.

Having the daemon set its own limits is not best-practice, and something
better handled by the process-manager starting the daemon.

Docker v20.10 and newer no longer adjust the daemon's OOM score by default,
instead setting the OOM-score to the systemd unit (OOMScoreAdjust) that's
shipped with the packages.

Users currently depending on this feature are recommended to adjust the
daemon's OOM score using systemd or through other means, when starting
the daemon.

BuildKit build information Copy Section

Deprecated in release: v23.0

Removed in release: v24.0

Build information
structures have been introduced in BuildKit v0.10.0
and are generated with build metadata that allows you to see all the sources
(images, Git repositories) that were used by the build with their exact
versions and also the configuration that was passed to the build. This
information is also embedded into the image configuration if one is generated.

Legacy builder for Linux images Copy Section

Deprecated in release: v23.0

Docker v23.0 now uses BuildKit by default to build Linux images, and uses the
Buildx CLI component for
docker build. With this change, docker build now exposes all advanced features
that BuildKit provides and which were previously only available through the
docker buildx subcommands.

The Buildx component is installed automatically when installing the docker CLI
using our .deb or .rpm packages, and statically linked binaries are provided
both on download.docker.com, and through the docker/buildx-bin image
on Docker Hub. Refer the Buildx section for
detailed instructions on installing the Buildx component.

This release marks the beginning of the deprecation cycle of the classic ("legacy")
builder for Linux images. No active development will happen on the classic builder
(except for bugfixes). BuildKit development started five Years ago, left the
"experimental" phase since Docker 18.09, and is already the default builder for
Docker Desktop.
While we're comfortable that BuildKit is stable for general use, there may be
some changes in behavior. If you encounter issues with BuildKit, we encourage
you to report issues in the BuildKit issue tracker on GitHub{:target="blank" rel="noopener" class=""}

Classic builder for building Windows images

BuildKit does not (yet) provide support for building Windows images, and
docker build continues to use the classic builder to build native Windows
images on Windows daemons.

Legacy builder fallback Copy Section

Deprecated in release: v23.0

Docker v23.0 now uses BuildKit by default to build Linux images,
which requires the Buildx component to build images with BuildKit. There may be
situations where the Buildx component is not available, and BuildKit cannot be
used.

To provide a smooth transition to BuildKit as the default builder, Docker v23.0
has an automatic fallback for some situations, or produces an error to assist
users to resolve the problem.

In situations where the user did not explicitly opt-in to use BuildKit (i.e.,
DOCKER_BUILDKIT=1 is not set), the CLI automatically falls back to the classic
builder, but prints a deprecation warning:

DEPRECATED: The legacy builder is deprecated and will be removed in a future release.
            Install the buildx component to build images with BuildKit:
            https://docs.docker.com/go/buildx/

This situation may occur if the docker CLI is installed using the static binaries,
and the Buildx component is not installed or not installed correctly. This fallback
will be removed in a future release, therefore we recommend to install the Buildx component
and use BuildKit for your builds, or opt-out of using BuildKit with DOCKER_BUILDKIT=0.

If you opted-in to use BuildKit (DOCKER_BUILDKIT=1), but the Buildx component
is missing, an error is printed instead, and the docker build command fails:

ERROR: BuildKit is enabled but the buildx component is missing or broken.
       Install the buildx component to build images with BuildKit:
       https://docs.docker.com/go/buildx/

We recommend to install the Buildx component
to continue using BuildKit for your builds, but alternatively, users can either
unset the DOCKER_BUILDKIT environment variable to fall back to the legacy builder,
or opt-out of using BuildKit with DOCKER_BUILDKIT=0.

Be aware that the classic builder is deprecated
so both the automatic fallback and opting-out of using BuildKit will no longer
be possible in a future release.

Btrfs storage driver on CentOS 7 and RHEL 7 Copy Section

Removed in release: v23.0

The btrfs storage driver on CentOS and RHEL was provided as a technology preview
by CentOS and RHEL, but has been deprecated since the Red Hat Enterprise Linux 7.4 release,
and removed in CentOS 8 and RHEL 8. Users of the btrfs storage driver on CentOS
are recommended to migrate to a different storage driver, such as overlay2, which
is now the default storage driver. Docker 23.0 continues to provide the btrfs
storage driver to allow users to migrate to an alternative driver. The next release
of Docker will no longer provide this driver.

Support for encrypted TLS private keys Copy Section

Deprecated in release: v20.10

Removed in release: v23.0

Use of encrypted TLS private keys has been deprecated, and has been removed.
Golang has deprecated support for legacy PEM encryption (as specified in
RFC 1423), as it is insecure by
design (see https://go-review.googlesource.com/c/go/+/264159).

This feature allowed using an encrypted private key with a supplied password,
but did not provide additional security as the encryption is known to be broken,
and the key is sitting next to the password in the filesystem. Users are recommended
to decrypt the private key, and store it un-encrypted to continue using it.

Kubernetes stack and context support Copy Section

Deprecated in release: v20.10

Removed in release: v23.0

Following the deprecation of Compose on Kubernetes,
support for Kubernetes in the stack and context commands has been removed from
the CLI, and options related to this functionality are now either ignored, or may
produce an error.

The following command-line flags are removed from the docker context subcommands:

• --default-stack-orchestrator - swarm is now the only (and default) orchestrator for stacks.
• --kubernetes - the Kubernetes endpoint can no longer be stored in docker context.
• --kubeconfig - exporting a context as a kubeconfig file is no longer supported.

The output produced by the docker context inspect subcommand no longer contains
information about StackOrchestrator and Kubernetes endpoints for new contexts.

The following command-line flags are removed from the docker stack subcommands:

• --kubeconfig - using a kubeconfig file as context is no longer supported.
• --namespace - configuring the Kubernetes namespace for stacks is no longer supported.
• --orchestrator - swarm is now the only (and default) orchestrator for stacks.

The DOCKER_STACK_ORCHESTRATOR, DOCKER_ORCHESTRATOR, and KUBECONFIG environment
variables, as well as the stackOrchestrator option in the ~/.docker/config.json
CLI configuration file are no longer used, and ignored.

Pulling images from non-compliant image registries Copy Section

Deprecated in release: v20.10

Removed in release: v28.2

Docker Engine v20.10 and up includes optimizations to verify if images in the
local image cache need updating before pulling, preventing the Docker Engine
from making unnecessary API requests. These optimizations require the container
image registry to conform to the Open Container Initiative Distribution Specification.

While most registries conform to the specification, we encountered some registries
to be non-compliant, resulting in docker pull to fail.

As a temporary solution, Docker Engine v20.10 added a fallback mechanism to
allow docker pull to be functional when using a non-compliant registry. A
warning message is printed in this situation:

WARNING Failed to pull manifest by the resolved digest. This registry does not
        appear to conform to the distribution registry specification; falling back to
        pull by tag. This fallback is DEPRECATED, and will be removed in a future
        release.

The fallback was added to allow users to either migrate their images to a
compliant registry, or for these registries to become compliant.

GitHub deprecated the legacy docker.pkg.github.com registry, and it was
sunset on Feb 24th, 2025
in favor of GitHub Container Registry (GHCR, ghcr.io), making this fallback
no longer needed.

Linux containers on Windows (LCOW) (experimental) Copy Section

Deprecated in release: v20.10

Removed in release: v23.0

The experimental feature to run Linux containers on Windows (LCOW) was introduced
as a technical preview in Docker 17.09. While many enhancements were made after
its introduction, the feature never reached completeness, and development has
now stopped in favor of running Docker natively on Linux in WSL2.

Developers who want to run Linux workloads on a Windows host are encouraged to use
Docker Desktop with WSL2 instead.

BLKIO weight options with cgroups v1 Copy Section

Deprecated in release: v20.10

Specifying blkio weight (docker run --blkio-weight and docker run --blkio-weight-device)
is now marked as deprecated when using cgroups v1 because the corresponding features
were removed in Linux kernel v5.0 and up.
When using cgroups v2, the --blkio-weight options are implemented using
[`io.weight](https://github.com/torvalds/linux/blob/v5.0/Documentation/admin-guide/cgroup-v2.rst#io).

Kernel memory limit Copy Section

Deprecated in release: v20.10

Removed in release: v23.0

Specifying kernel memory limit (docker run --kernel-memory) is no longer supported
because the Linux kernel deprecated kmem.limit_in_bytes in v5.4.
The OCI runtime specification now marks this option as "NOT RECOMMENDED",
and OCI runtimes such as runc no longer support this option.

The Docker API no longer handles the kernel-memory fields, and Docker CLI v29.0
removes the --kernel-memory option.

Classic Swarm and overlay networks using cluster store Copy Section

Deprecated in release: v20.10

Removed in release: v23.0

Standalone ("classic") Swarm has been deprecated, and with that the use of overlay
networks using an external key/value store. The corresponding--cluster-advertise,
--cluster-store, and --cluster-store-opt daemon options have been removed.

Support for legacy `~/.dockercfg` configuration files Copy Section

Deprecated in release: v20.10

Removed in release: v23.0

The Docker CLI up until v1.7.0 used the ~/.dockercfg file to store credentials
after authenticating to a registry (docker login). Docker v1.7.0 replaced this
file with a new CLI configuration file, located in ~/.docker/config.json. When
implementing the new configuration file, the old file (and file-format) was kept
as a fall-back, to assist existing users with migrating to the new file.

Given that the old file format encourages insecure storage of credentials
(credentials are stored unencrypted), and that no version of the CLI since
Docker v1.7.0 has created this file, support for this file, and its format has
been removed.

Configuration options for experimental CLI features Copy Section

Deprecated in release: v19.03

Removed in release: v23.0

The DOCKER_CLI_EXPERIMENTAL environment variable and the corresponding experimental
field in the CLI configuration file are deprecated. Experimental features are
enabled by default, and these configuration options are no longer functional.

Starting with v23.0, the Docker CLI no longer prints Experimental for the client
in the output of docker version, and the field has been removed from the JSON
format.

CLI plugins support Copy Section

Deprecated in release: v20.10

CLI Plugin API is now marked as deprecated.

Dockerfile legacy `ENV name value` syntax Copy Section

Deprecated in release: v20.10

The Dockerfile ENV instruction allows values to be set using either ENV name=value
or ENV name value. The latter (ENV name value) form can be ambiguous, for example,
the following defines a single env-variable (ONE) with value "TWO= THREE=world",
but may have intended to be setting three env-vars:

ENV ONE TWO= THREE=world

This format also does not allow setting multiple environment-variables in a single
ENV line in the Dockerfile.

Use of the ENV name value syntax is discouraged, and may be removed in a future
release. Users are encouraged to update their Dockerfiles to use the ENV name=value
syntax, for example:

ENV ONE="" TWO="" THREE="world"

`docker build --stream` flag (experimental) Copy Section

Deprecated in release: v20.10

Removed in release: v20.10

Docker v17.07 introduced an experimental --stream flag on docker build which
allowed the build-context to be incrementally sent to the daemon, instead of
unconditionally sending the whole build-context.