docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

hugo: run migration script 

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
This commit is contained in:
David Karlsson 2023-08-22 09:42:25 +02:00
parent a0d21ade2f
commit 15e9e1e694
950 changed files with 5772 additions and 5726 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

75
content/_index.md
View File

@ -3,40 +3,41 @@ title: Home
description: Home page for Docker's documentation description: Home page for Docker's documentation
keywords: Docker, documentation, manual, guide, reference, api, samples keywords: Docker, documentation, manual, guide, reference, api, samples
grid: grid:
- title: Get started - title: Get started
image: image:
dark: /assets/images/rocket-dark.svg dark: /assets/images/rocket-dark.svg
light: /assets/images/rocket.svg light: /assets/images/rocket.svg
link: /get-started/ link: /get-started/
description: Learn Docker basics and the benefits of containerizing your applications. description: Learn Docker basics and the benefits of containerizing your applications.
- title: Download and install - title: Download and install
image: image:
dark: /assets/images/download-docker-dark.svg dark: /assets/images/download-docker-dark.svg
light: /assets/images/download-docker.svg light: /assets/images/download-docker.svg
link: /get-docker/ link: /get-docker/
description: Download and install Docker on your machine in a few easy steps. description: Download and install Docker on your machine in a few easy steps.
- title: Guides - title: Guides
image: image:
dark: /assets/images/guides-dark.svg dark: /assets/images/guides-dark.svg
light: /assets/images/guides.svg light: /assets/images/guides.svg
link: /get-started/overview/ link: /get-started/overview/
description: Learn how to set up your Docker environment and start containerizing your applications. description: Learn how to set up your Docker environment and start containerizing
- title: Language-specific guides your applications.
image: - title: Language-specific guides
dark: /assets/images/language-guides-dark.svg image:
light: /assets/images/language-guides.svg dark: /assets/images/language-guides-dark.svg
link: /language/ light: /assets/images/language-guides.svg
description: Learn how to use Docker with your favorite programming language. link: /language/
- title: Manuals description: Learn how to use Docker with your favorite programming language.
image: - title: Manuals
dark: /assets/images/manuals-dark.svg image:
light: /assets/images/manuals.svg dark: /assets/images/manuals-dark.svg
link: /desktop/ light: /assets/images/manuals.svg
description: Browse the manuals and learn how to use Docker products. link: /desktop/
- title: Reference description: Browse the manuals and learn how to use Docker products.
image: - title: Reference
dark: /assets/images/reference-dark.svg image:
light: /assets/images/reference.svg dark: /assets/images/reference-dark.svg
link: /reference/ light: /assets/images/reference.svg
description: Browse the CLI and API reference documentation. link: /reference/
--- description: Browse the CLI and API reference documentation.
---

28
content/admin/_index.md
View File

@ -1,22 +1,24 @@
--- ---
description: Docker Admin provides administrators with centralized observability, access management, and controls for their company and organizations. description: Docker Admin provides administrators with centralized observability,
access management, and controls for their company and organizations.
keywords: admin, administration, company, organization keywords: admin, administration, company, organization
title: Docker Admin overview title: Docker Admin overview
grid: grid:
- title: Company administration - title: Company administration
description: Explore how to manage a company in Docker Admin. description: Explore how to manage a company in Docker Admin.
icon: lan icon: lan
link: /admin/company/ link: /admin/company/
- title: Organization administration - title: Organization administration
description: Learn about organization administration in Docker Admin. description: Learn about organization administration in Docker Admin.
icon: contact_page icon: contact_page
link: /admin/organization/ link: /admin/organization/
--- ---
{% include admin-early-access.md %}
The [Docker Admin](https://admin.docker.com){: target="_blank" rel="noopener" class="_"} console provides administrators with centralized observability, access management, and controls for their company and organizations. To provide these features, Docker uses the following hierarchy and roles. {{< include "admin-early-access.md" >}}
![Docker hierarchy](./images/docker-hierarchy-company.svg){: width="800px" } The [Docker Admin](https://admin.docker.com) console provides administrators with centralized observability, access management, and controls for their company and organizations. To provide these features, Docker uses the following hierarchy and roles.
![Docker hierarchy](./images/docker-hierarchy-company.svg)
- Company: A company simplifies the management of Docker organizations and settings. Creating a company is optional and only available to Docker Business subscribers. - Company: A company simplifies the management of Docker organizations and settings. Creating a company is optional and only available to Docker Business subscribers.
- Company owner: A company can have multiple owners. Company owners have company-wide observability and can manage company-wide settings that apply to all associated organizations. In addition, company owners have the same access as organization owners for all associated organizations. - Company owner: A company can have multiple owners. Company owners have company-wide observability and can manage company-wide settings that apply to all associated organizations. In addition, company owners have the same access as organization owners for all associated organizations.
@ -25,4 +27,4 @@ The [Docker Admin](https://admin.docker.com){: target="_blank" rel="noopener" cl
- Team: A team is a group of Docker members that belong to an organization. Organization and company owners can group members into additional teams to configure repository permissions on a per-team basis. - Team: A team is a group of Docker members that belong to an organization. Organization and company owners can group members into additional teams to configure repository permissions on a per-team basis.
- Member: A member is a Docker user that's a member of at least one team in an organization. - Member: A member is a Docker user that's a member of at least one team in an organization.
{{< grid >}} {{< grid >}}

56
content/admin/company/_index.md
View File

@ -3,39 +3,41 @@ description: Learn about companies.
keywords: company, multiple organizations, manage companies keywords: company, multiple organizations, manage companies
title: Overview title: Overview
grid: grid:
- title: Manage organizations - title: Manage organizations
description: Learn how to add and manage organizations as well as seats within your company. description: Learn how to add and manage organizations as well as seats within your
icon: note_add company.
link: /admin/company/organizations/ icon: note_add
- title: Manage users link: /admin/company/organizations/
description: Explore how to manage users in all organizations. - title: Manage users
icon: contact_page description: Explore how to manage users in all organizations.
link: /admin/company/users/ icon: contact_page
- title: Manage company owners link: /admin/company/users/
description: Find out more about company owners and how to manage them. - title: Manage company owners
icon: group_add description: Find out more about company owners and how to manage them.
link: /admin/company/owners/ icon: group_add
- title: Configure Single Sign-On link: /admin/company/owners/
description: Discover how to configure SSO for your entire company. - title: Configure Single Sign-On
icon: key description: Discover how to configure SSO for your entire company.
link: /admin/company/settings/sso/ icon: key
- title: Set up SCIM link: /admin/company/settings/sso/
description: Set up SCIM to automatically provision and deprovision users in your company. - title: Set up SCIM
icon: checklist description: Set up SCIM to automatically provision and deprovision users in your
link: /admin/company/settings/scim/ company.
- title: Domain management icon: checklist
description: Add and verify your domains. link: /admin/company/settings/scim/
icon: security - title: Domain management
link: /admin/company/settings/domains/ description: Add and verify your domains.
icon: security
link: /admin/company/settings/domains/
--- ---
{% include admin-early-access.md %} {{< include "admin-early-access.md" >}}
{% include admin-company-overview.md %} {{< include "admin-company-overview.md" >}}
To create a company, see To create a company, see
[Create a company](../organization/general-settings.md#create-a-company). [Create a company](../organization/general-settings.md#create-a-company).
Learn how to administer a company using Docker Admin in the following sections. Learn how to administer a company using Docker Admin in the following sections.
{{< grid >}} {{< grid >}}

13
content/admin/company/organizations.md
View File

@ -3,11 +3,12 @@ description: Manage organizations for a company in Docker Admin.
keywords: company, multiple organizations, manage organizations keywords: company, multiple organizations, manage organizations
title: Manage organizations title: Manage organizations
--- ---
{% include admin-early-access.md %}
{{< include "admin-early-access.md" >}}
## View all organizations ## View all organizations
1. Sign in to [Docker Admin](https://admin.docker.com){: target="_blank" rel="noopener" class="_"}. 1. Sign in to [Docker Admin](https://admin.docker.com).
2. In the left navigation, select your company in the drop-down menu. 2. In the left navigation, select your company in the drop-down menu.
3. Under **Organizations**, select **Overview**. 3. Under **Organizations**, select **Overview**.
@ -15,7 +16,7 @@ title: Manage organizations
When you have a [self-serve](../../subscription/details.md#self-serve) subscription that has no pending subscription changes, you can add seats using the following steps. When you have a [self-serve](../../subscription/details.md#self-serve) subscription that has no pending subscription changes, you can add seats using the following steps.
1. Sign in to [Docker Admin](https://admin.docker.com){: target="_blank" rel="noopener" class="_"}. 1. Sign in to [Docker Admin](https://admin.docker.com).
2. In the left navigation, select your company in the drop-down menu. 2. In the left navigation, select your company in the drop-down menu.
3. Under **Organizations**, select **Overview**. 3. Under **Organizations**, select **Overview**.
4. Select the action icon in the organization's card, and then select **Get more seats**. 4. Select the action icon in the organization's card, and then select **Get more seats**.
@ -25,7 +26,7 @@ When you have a [self-serve](../../subscription/details.md#self-serve) subscript
There is no limit to the number of organizations you can have under a company layer. All organizations must have a Business subscription. There is no limit to the number of organizations you can have under a company layer. All organizations must have a Business subscription.
1. Sign in to [Docker Admin](https://admin.docker.com){: target="_blank" rel="noopener" class="_"}. 1. Sign in to [Docker Admin](https://admin.docker.com).
2. In the left navigation, select your company in the drop-down menu. 2. In the left navigation, select your company in the drop-down menu.
3. Select **Add organization**. 3. Select **Add organization**.
4. Choose the organization you want to add from the drop-down menu. 4. Choose the organization you want to add from the drop-down menu.
@ -33,8 +34,8 @@ There is no limit to the number of organizations you can have under a company la
## Manage an organization ## Manage an organization
1. Sign in to [Docker Admin](https://admin.docker.com){: target="_blank" rel="noopener" class="_"}. 1. Sign in to [Docker Admin](https://admin.docker.com).
2. In the left navigation, select your company in the drop-down menu. 2. In the left navigation, select your company in the drop-down menu.
3. Select the organization that you want to manage. 3. Select the organization that you want to manage.
For more details about managing an organization, see [Organization administration](../organization/index.md). For more details about managing an organization, see [Organization administration](../organization/index.md).

7
content/admin/company/owners.md
View File

@ -3,13 +3,14 @@ description: Learn about company owners.
keywords: company, owners keywords: company, owners
title: Manage company owners title: Manage company owners
--- ---
{% include admin-early-access.md %}
{{< include "admin-early-access.md" >}}
As a company owner, you can configure [Single Sign-on (SSO)](./settings/sso.md) and [System for Cross-domain Identity Management (SCIM)](./settings/scim.md) for all organizations under the company. As a company owner, you can configure [Single Sign-on (SSO)](./settings/sso.md) and [System for Cross-domain Identity Management (SCIM)](./settings/scim.md) for all organizations under the company.
## Add a company owner ## Add a company owner
1. Sign in to [Docker Admin](https://admin.docker.com){: target="_blank" rel="noopener" class="_"}. 1. Sign in to [Docker Admin](https://admin.docker.com).
2. In the left navigation, select your company in the drop-down menu. 2. In the left navigation, select your company in the drop-down menu.
3. Select **Company Owners**. 3. Select **Company Owners**.
4. Select **Add Owner**. 4. Select **Add Owner**.
@ -18,7 +19,7 @@ As a company owner, you can configure [Single Sign-on (SSO)](./settings/sso.md)
## Remove a company owner ## Remove a company owner
1. Sign in to [Docker Admin](https://admin.docker.com){: target="_blank" rel="noopener" class="_"}. 1. Sign in to [Docker Admin](https://admin.docker.com).
2. In the left navigation, select your company in the drop-down menu. 2. In the left navigation, select your company in the drop-down menu.
3. Select **Company Owners**. 3. Select **Company Owners**.
4. Select the **Action** icon in the row of the company owner that your want to remove. 4. Select the **Action** icon in the row of the company owner that your want to remove.

2
content/admin/company/settings/domains.md
View File

@ -4,7 +4,7 @@ keywords: domains, SCIM, SSO, Docker Admin
title: Domain management title: Domain management
--- ---
{% include admin-early-access.md %} {{< include "admin-early-access.md" >}}
Use domain management to manage your domains for Single Sign-On and SCIM. Use domain management to manage your domains for Single Sign-On and SCIM.

4
content/admin/company/settings/group-mapping.md
View File

@ -4,6 +4,6 @@ keywords: Group Mapping, SCIM, Docker Admin
title: Group Mapping title: Group Mapping
--- ---
{% include admin-early-access.md %} {{< include "admin-early-access.md" >}}
{% include admin-group-mapping.md product="admin" layer="company" %} {{% admin-group-mapping product="admin" layer="company" %}}

2
content/admin/company/settings/scim.md
View File

@ -4,7 +4,7 @@ keywords: SCIM, SSO
title: SCIM title: SCIM
--- ---
{% include admin-early-access.md %} {{< include "admin-early-access.md" >}}
Follow the steps on this page to manage SCIM for your company. To manage SCIM for an organization, see [SCIM for an organization](/admin/organization/security-settings/scim/). Follow the steps on this page to manage SCIM for your company. To manage SCIM for an organization, see [SCIM for an organization](/admin/organization/security-settings/scim/).

2
content/admin/company/settings/sso-configuration.md
View File

@ -4,7 +4,7 @@ keywords: configure, sso, docker admin
title: Configure Single Sign-On for a company title: Configure Single Sign-On for a company
--- ---
{% include admin-early-access.md %} {{< include "admin-early-access.md" >}}
Follow the steps on this page to configure SSO for your company. To configure SSO for an organization, see [Configure SSO for an organization](/admin/organization/security-settings/sso-configuration/). Follow the steps on this page to configure SSO for your company. To configure SSO for an organization, see [Configure SSO for an organization](/admin/organization/security-settings/sso-configuration/).

7
content/admin/company/settings/sso-management.md
View File

@ -4,13 +4,12 @@ keywords: manage, single sign-on, SSO, sign-on
title: Manage Single Sign-On for a company title: Manage Single Sign-On for a company
--- ---
{% include admin-early-access.md %} {{< include "admin-early-access.md" >}}
Follow the steps on this page to manage SSO for your company. To manage SSO for an organization, see [Manage SSO for an organization](/admin/organization/security-settings/sso-management/). Follow the steps on this page to manage SSO for your company. To manage SSO for an organization, see [Manage SSO for an organization](/admin/organization/security-settings/sso-management/).
## Manage organizations ## Manage organizations
{% include admin-sso-management-orgs.md product="admin" %} {{% admin-sso-management-orgs product="admin" %}}
{% include admin-sso-management.md product="admin" layer="company"%}
{% include admin-sso-management.md product="admin" layer="company"%}

4
content/admin/company/settings/sso.md
View File

@ -4,6 +4,6 @@ keywords: Single Sign-on, SSO, sign-on
title: Single Sign-On overview title: Single Sign-On overview
--- ---
{% include admin-early-access.md %} {{< include "admin-early-access.md" >}}
{% include admin-sso.md product="admin" layer="company" %} {{% admin-sso product="admin" layer="company" %}}

4
content/admin/company/users.md
View File

@ -4,9 +4,9 @@ keywords: company, company users, users, admin, docker admin
title: Manage company users title: Manage company users
--- ---
{% include admin-early-access.md %} {{< include "admin-early-access.md" >}}
{% include admin-users.md product="admin" layer="company" %} {{% admin-users product="admin" layer="company" %}}
## Manage members on a team ## Manage members on a team

66
content/admin/organization/_index.md
View File

@ -3,44 +3,44 @@ description: Learn about organizations.
keywords: organizations, admin, overview keywords: organizations, admin, overview
title: Organization administration overview title: Organization administration overview
grid: grid:
- title: Manage members - title: Manage members
description: Explore how to manage members. description: Explore how to manage members.
icon: contact_page icon: contact_page
link: /admin/organization/members/ link: /admin/organization/members/
- title: Activity logs - title: Activity logs
description: Learn how to audit the activities of your members. description: Learn how to audit the activities of your members.
icon: feed icon: feed
link: /admin/organization/activity-logs/ link: /admin/organization/activity-logs/
- title: Image Access Management - title: Image Access Management
description: Control which types of images your developers can pull. description: Control which types of images your developers can pull.
icon: dynamic_feed icon: dynamic_feed
link: /admin/organization/image-access/ link: /admin/organization/image-access/
- title: Registry Access Management - title: Registry Access Management
description: Define which registries your developers can access. description: Define which registries your developers can access.
icon: all_inbox icon: all_inbox
link: /admin/organization/registry-access/ link: /admin/organization/registry-access/
- title: General settings - title: General settings
description: Configure general information or create a company. description: Configure general information or create a company.
icon: settings_suggest icon: settings_suggest
link: /admin/organization/general-settings/ link: /admin/organization/general-settings/
- title: SSO & SCIM - title: SSO & SCIM
description: > description: 'Set up [Single Sign-On](/admin/organization/security-settings/sso/)
Set up [Single Sign-On](/admin/organization/security-settings/sso/) and and [SCIM](/admin/organization/security-settings/scim/) for your organization.
[SCIM](/admin/organization/security-settings/scim/) for your organization.
icon: key '
- title: Domain management icon: key
description: Add, verify, and audit your domains. - title: Domain management
link: /admin/organization/security-settings/domains/ description: Add, verify, and audit your domains.
icon: security link: /admin/organization/security-settings/domains/
icon: security
--- ---
{% include admin-early-access.md %} {{< include "admin-early-access.md" >}}
{% include admin-org-overview.md %} {{< include "admin-org-overview.md" >}}
To create an organization, see [Create your organization](../../docker-hub/orgs.md). To create an organization, see [Create your organization](../../docker-hub/orgs.md).
Learn how to administer an organization using Docker Admin in the following sections. Learn how to administer an organization using Docker Admin in the following sections.
{{< grid >}} {{< grid >}}

4
content/admin/organization/activity-logs.md
View File

@ -4,6 +4,6 @@ keywords: team, organization, activity, log, audit, activities
title: Activity logs title: Activity logs
--- ---
{% include admin-early-access.md %} {{< include "admin-early-access.md" >}}
{% include admin-org-audit-log.md product="admin" %} {{% admin-org-audit-log product="admin" %}}

6
content/admin/organization/general-settings.md
View File

@ -4,7 +4,7 @@ keywords: organization, settings
title: General settings title: General settings
--- ---
{% include admin-early-access.md %} {{< include "admin-early-access.md" >}}
## Configure general information ## Configure general information
@ -19,7 +19,7 @@ This information includes:
To edit this information: To edit this information:
1. Sign in to [Docker Admin](https://admin.docker.com){: target="_blank" rel="noopener" class="_"}. 1. Sign in to [Docker Admin](https://admin.docker.com).
2. In the left navigation, select your organization in the drop-down menu. 2. In the left navigation, select your organization in the drop-down menu.
3. Under **Organization Settings**, select **General**. 3. Under **Organization Settings**, select **General**.
4. Specify the organization information and select **Save**. 4. Specify the organization information and select **Save**.
@ -28,7 +28,7 @@ To edit this information:
To create a new company: To create a new company:
1. Sign in to [Docker Admin](https://admin.docker.com){: target="_blank" rel="noopener" class="_"}. 1. Sign in to [Docker Admin](https://admin.docker.com).
2. In the left navigation, select your organization in the drop-down menu. 2. In the left navigation, select your organization in the drop-down menu.
3. Under **Organization Settings**, select **General**. 3. Under **Organization Settings**, select **General**.
4. In the **Organization management** section, select **Create a company**. 4. In the **Organization management** section, select **Create a company**.

4
content/admin/organization/image-access.md
View File

@ -4,6 +4,6 @@ keywords: image, access, management
title: Image Access Management title: Image Access Management
--- ---
{% include admin-early-access.md %} {{< include "admin-early-access.md" >}}
{% include admin-image-access.md product="admin" %} {{% admin-image-access product="admin" %}}

6
content/admin/organization/members.md
View File

@ -4,10 +4,10 @@ keywords: members, teams, organizations
title: Manage members title: Manage members
--- ---
{% include admin-early-access.md %} {{< include "admin-early-access.md" >}}
{% include admin-users.md product="admin" %} {{% admin-users product="admin" %}}
## Manage members on a team ## Manage members on a team
Use Docker Hub to add a member to a team or remove a member from a team. For more details, see [Manage members in Docker Hub](../../docker-hub/members.md). Use Docker Hub to add a member to a team or remove a member from a team. For more details, see [Manage members in Docker Hub](../../docker-hub/members.md).

4
content/admin/organization/onboard.md
View File

@ -6,6 +6,6 @@ toc_min: 1
toc_max: 2 toc_max: 2
--- ---
{% include admin-early-access.md %} {{< include "admin-early-access.md" >}}
{% include admin-org-onboarding.md product="admin" %} {{% admin-org-onboarding product="admin" %}}

4
content/admin/organization/registry-access.md
View File

@ -4,6 +4,6 @@ keywords: registry, access, management
title: Registry Access Management title: Registry Access Management
--- ---
{% include admin-early-access.md %} {{< include "admin-early-access.md" >}}
{% include admin-registry-access.md product="admin" %} {{% admin-registry-access product="admin" %}}

4
content/admin/organization/security-settings/domains.md
View File

@ -4,7 +4,7 @@ keywords: domains, SCIM, SSO, Docker Admin, domain audit
title: Domain management title: Domain management
--- ---
{% include admin-early-access.md %} {{< include "admin-early-access.md" >}}
Use domain management to manage your domains for Single Sign-On and SCIM, as well as audit your domains for uncaptured users. Use domain management to manage your domains for Single Sign-On and SCIM, as well as audit your domains for uncaptured users.
@ -14,4 +14,4 @@ Use domain management to manage your domains for Single Sign-On and SCIM, as wel
## Domain audit ## Domain audit
{% include admin-domain-audit.md product="admin" %} {{% admin-domain-audit product="admin" %}}

4
content/admin/organization/security-settings/group-mapping.md
View File

@ -4,6 +4,6 @@ keywords: Group Mapping, SCIM, Docker Admin
title: Group Mapping title: Group Mapping
--- ---
{% include admin-early-access.md %} {{< include "admin-early-access.md" >}}
{% include admin-group-mapping.md product="admin" layer="organization" %} {{% admin-group-mapping product="admin" layer="organization" %}}

2
content/admin/organization/security-settings/scim.md
View File

@ -4,7 +4,7 @@ keywords: SCIM, SSO
title: SCIM title: SCIM
--- ---
{% include admin-early-access.md %} {{< include "admin-early-access.md" >}}
Follow the steps on this page to manage SCIM for your organization. To manage SCIM for a company, see [SCIM for a company](/admin/company/settings/scim/). Follow the steps on this page to manage SCIM for your organization. To manage SCIM for a company, see [SCIM for a company](/admin/company/settings/scim/).

2
content/admin/organization/security-settings/sso-configuration.md
View File

@ -4,7 +4,7 @@ keywords: configure, sso, docker admin
title: Configure Single Sign-On for an organization title: Configure Single Sign-On for an organization
--- ---
{% include admin-early-access.md %} {{< include "admin-early-access.md" >}}
Follow the steps on this page to configure SSO for your organization. To configure SSO for a company, see [Configure SSO for a company](/admin/company/settings/sso-configuration/). Follow the steps on this page to configure SSO for your organization. To configure SSO for a company, see [Configure SSO for a company](/admin/company/settings/sso-configuration/).

4
content/admin/organization/security-settings/sso-faq.md
View File

@ -5,6 +5,6 @@ title: Single Sign-On FAQs
toc_max: 2 toc_max: 2
--- ---
{% include admin-early-access.md %} {{< include "admin-early-access.md" >}}
{% include admin-sso-faq.md %} {{< include "admin-sso-faq.md" >}}

2
content/admin/organization/security-settings/sso-management.md
View File

@ -4,7 +4,7 @@ keywords: manage, single sign-on, SSO, sign-on
title: Manage Single Sign-On for an organization title: Manage Single Sign-On for an organization
--- ---
{% include admin-early-access.md %} {{< include "admin-early-access.md" >}}
Follow the steps on this page to manage SSO for an organization. To manage SSO for a company, see [Manage SSO for a company](/admin/company/settings/sso-management/). Follow the steps on this page to manage SSO for an organization. To manage SSO for a company, see [Manage SSO for a company](/admin/company/settings/sso-management/).

4
content/admin/organization/security-settings/sso.md
View File

@ -4,6 +4,6 @@ keywords: Single sign-on, SSO, sign-on
title: Single Sign-On overview title: Single Sign-On overview
--- ---
{% include admin-early-access.md %} {{< include "admin-early-access.md" >}}
{% include admin-sso.md product="admin" layer="organization" %} {{% admin-sso product="admin" layer="organization" %}}

2
content/billing/_index.md
View File

@ -19,4 +19,4 @@ grid:
Use the resources in this section to manage your billing and payment settings for your Pro, Team, or Business subscription. Use the resources in this section to manage your billing and payment settings for your Pro, Team, or Business subscription.
{{< grid >}} {{< grid >}}

2
content/billing/cycle.md
View File

@ -30,4 +30,4 @@ When you change the billing cycle's duration:
1. In Docker Hub, select **Organizations**. 1. In Docker Hub, select **Organizations**.
2. Select the organization that you want to change the payment method for. 2. Select the organization that you want to change the payment method for.
3. In the bottom-right of the **Plan** tab, select **Switch to annual billing**. 3. In the bottom-right of the **Plan** tab, select **Switch to annual billing**.
4. Review the information displayed on the **Change to an Annual subscription** page and select **Accept Terms and Purchase** to confirm. 4. Review the information displayed on the **Change to an Annual subscription** page and select **Accept Terms and Purchase** to confirm.

2
content/billing/details.md
View File

@ -26,4 +26,4 @@ The billing information provided appears on all your billing invoices. The email
2. Select the organization that you want to change the payment method for. 2. Select the organization that you want to change the payment method for.
3. Select the **Billing** tab and then **Payment Methods**. 3. Select the **Billing** tab and then **Payment Methods**.
4. In the **Billing Information** section, enter your updated billing details. 4. In the **Billing Information** section, enter your updated billing details.
5. Select **Update**. 5. Select **Update**.

4
content/billing/faqs.md
View File

@ -43,7 +43,7 @@ Docker Hub sends the following billing-related emails:
### Does Docker offer academic pricing? ### Does Docker offer academic pricing?
Contact the [Docker Sales Team](https://www.docker.com/company/contact){:target="blank" rel="noopener" class=""}. Contact the [Docker Sales Team](https://www.docker.com/company/contact).
### Do I need to do anything at the end of my subscription term? ### Do I need to do anything at the end of my subscription term?
@ -88,4 +88,4 @@ For organizations:
1. In Docker Hub, select **Organization**, your organization, and then **Billing**. 1. In Docker Hub, select **Organization**, your organization, and then **Billing**.
2. Select the **Payment Methods** tab, then update the email field in the **Billing Information** section. 2. Select the **Payment Methods** tab, then update the email field in the **Billing Information** section.
3. Select **Update**. 3. Select **Update**.

2
content/billing/history.md
View File

@ -32,4 +32,4 @@ From here you can choose to:
From here you can choose to: From here you can choose to:
- Download an invoice. - Download an invoice.
- Update an invoice with recently [updated billing information](details.md) by selecting the menu icon and then **Update Invoice**. - Update an invoice with recently [updated billing information](details.md) by selecting the menu icon and then **Update Invoice**.

2
content/billing/payment-method.md
View File

@ -34,4 +34,4 @@ You can add a payment method or update your account's existing payment method at
4. In the **Payment Information** section, enter the new payment method. 4. In the **Payment Information** section, enter the new payment method.
The screen refreshes and displays your new payment information alongside your existing information. The screen refreshes and displays your new payment information alongside your existing information.
5. Select **Make Default** to ensure that your new payment method applies to all purchases and subscriptions. 5. Select **Make Default** to ensure that your new payment method applies to all purchases and subscriptions.
6. Optional. Remove your existing payment method by selecting the **X** icon. 6. Optional. Remove your existing payment method by selecting the **X** icon.

8
content/billing/scout-billing.md
View File

@ -4,11 +4,11 @@ description: Learn how to buy Docker Scout and manage your subscription
keywords: payments, billing, subscription, scout keywords: payments, billing, subscription, scout
--- ---
{% include scout-early-access.md %} {{< include "scout-early-access.md" >}}
Docker Scout lets users secure their software supply chain and continuously observe and improve their security posture. Docker Scout is free for up to 3 repositories. You can buy Docker Scout Team or Docker Scout Business to turn on Docker Scout for additional repositories. See [Docker Scout subscription and features](../subscription/scout-details.md) to select the plan that works for you. Docker Scout lets users secure their software supply chain and continuously observe and improve their security posture. Docker Scout is free for up to 3 repositories. You can buy Docker Scout Team or Docker Scout Business to turn on Docker Scout for additional repositories. See [Docker Scout subscription and features](../subscription/scout-details.md) to select the plan that works for you.
In this section, learn how to buy Docker Scout Team in Docker Hub for your personal account or for an organization. To buy Docker Scout Business, [contact sales](https://www.docker.com/products/docker-scout/){: target="_blank" rel="noopener" class="_"}. In this section, learn how to buy Docker Scout Team in Docker Hub for your personal account or for an organization. To buy Docker Scout Business, [contact sales](https://www.docker.com/products/docker-scout/).
## Personal account ## Personal account
@ -36,7 +36,7 @@ Once your purchase is complete, you receive a confirmation email and a copy of y
>**Note** >**Note**
> >
> If you're an organization with multiple teams, a Docker Scout Business plan may be better. [Contact sales](https://www.docker.com/products/docker-scout/){: target="_blank" rel="noopener" class="_"} to learn more. > If you're an organization with multiple teams, a Docker Scout Business plan may be better. [Contact sales](https://www.docker.com/products/docker-scout/) to learn more.
7. This redirects you to the payment processing page. Enter your email if this field isn't pre-populated. Then, enter your payment information. 7. This redirects you to the payment processing page. Enter your email if this field isn't pre-populated. Then, enter your payment information.
8. Update the quantity of repositories you want to use with Docker Scout. See [Docker Scout subscriptions](../subscription/scout-details.md) to learn more about the number of repositories available for each plan. 8. Update the quantity of repositories you want to use with Docker Scout. See [Docker Scout subscriptions](../subscription/scout-details.md) to learn more about the number of repositories available for each plan.
@ -50,4 +50,4 @@ Once your purchase is complete, you receive a confirmation email and a copy of y
To access your subscription details, go to the **Billing** section for your personal account or organization that's subscribed. In the **Docker Scout Team** section, select **Change plan**. Here you can find your renewal date, invoice history, or cancel your plan. To access your subscription details, go to the **Billing** section for your personal account or organization that's subscribed. In the **Docker Scout Team** section, select **Change plan**. Here you can find your renewal date, invoice history, or cancel your plan.
Renewals charge to the original credit card used to buy Docker Scout Team. Renewals charge to the original credit card used to buy Docker Scout Team.

83
content/build/_index.md
View File

@ -2,50 +2,45 @@
title: Overview of Docker Build title: Overview of Docker Build
description: Introduction and overview of Docker Build description: Introduction and overview of Docker Build
keywords: build, buildx, buildkit keywords: build, buildx, buildkit
redirect_from:
- /buildx/working-with-buildx/
- /develop/develop-images/build_enhancements/
grid: grid:
- title: "Packaging your software" - title: Packaging your software
description: description: 'Build and package your application to run it anywhere: locally or
"Build and package your application to run it anywhere: locally or in the in the cloud.'
cloud." icon: inventory_2
icon: "inventory_2" link: /build/building/packaging
link: "/build/building/packaging" - title: Multi-stage builds
- title: "Multi-stage builds" description: Keep your images small and secure with minimal dependencies.
description: "Keep your images small and secure with minimal dependencies." icon: stairs
icon: "stairs" link: /build/building/multi-stage
link: "/build/building/multi-stage" - title: Multi-platform images
- title: "Multi-platform images" description: Build, push, pull, and run images seamlessly on different computer
description: architectures.
"Build, push, pull, and run images seamlessly on different computer icon: home_storage
architectures." link: /build/building/multi-platform/
icon: "home_storage" - title: Architecture
link: "/build/building/multi-platform/" description: Explore BuildKit, the open source build engine.
- title: "Architecture" icon: construction
description: "Learn about the Docker Build components." link: /build/buildkit/
icon: "explore" - title: Build drivers
description: "Explore BuildKit, the open source build engine." description: Configure where and how you run your builds.
icon: "construction" icon: engineering
link: "/build/buildkit/" link: /build/drivers/
- title: "Build drivers" - title: Exporters
description: "Configure where and how you run your builds." description: Export any artifact you like, not just Docker images.
icon: "engineering" icon: output
link: "/build/drivers/" link: /build/exporters
- title: "Exporters" - title: Build caching
description: "Export any artifact you like, not just Docker images." description: Avoid unnecessary repetitions of costly operations, such as package
icon: "output" installs.
link: "/build/exporters" icon: cycle
- title: "Build caching" link: /build/cache
description: - title: Bake
"Avoid unnecessary repetitions of costly operations, such as package description: Orchestrate your builds with Bake.
installs." icon: cake
icon: "cycle" link: /build/bake
link: "/build/cache" aliases:
- title: "Bake" - /buildx/working-with-buildx/
description: "Orchestrate your builds with Bake." - /develop/develop-images/build_enhancements/
icon: "cake"
link: "/build/bake"
--- ---
Docker Build is one of Docker Engine's most used features. Whenever you are Docker Build is one of Docker Engine's most used features. Whenever you are
@ -58,4 +53,4 @@ packaging your code. It's a whole ecosystem of tools and features that support
not only common workflow tasks but also provides support for more complex and not only common workflow tasks but also provides support for more complex and
advanced scenarios. advanced scenarios.
{{< grid >}} {{< grid >}}

8
content/build/architecture.md
View File

@ -2,8 +2,8 @@
title: Docker Build architecture title: Docker Build architecture
description: Learn about Docker Build and its components. description: Learn about Docker Build and its components.
keywords: build, buildkit, buildx, architecture keywords: build, buildkit, buildx, architecture
redirect_from: aliases:
- /build/install-buildx/ - /build/install-buildx/
--- ---
Docker Build implements a client-server architecture, where: Docker Build implements a client-server architecture, where:
@ -37,7 +37,7 @@ package. Buildx is included in the Docker Engine installation instructions, see
You can also build the CLI plugin from source, or grab a binary from the GitHub You can also build the CLI plugin from source, or grab a binary from the GitHub
repository and install it manually. See repository and install it manually. See
[docker/buildx README](https://github.com/docker/buildx#manual-download){: target="blank" rel="noopener"} [docker/buildx README](https://github.com/docker/buildx#manual-download)
for more information for more information
## Builders ## Builders
@ -90,4 +90,4 @@ For more information about BuildKit, see [BuildKit](buildkit/index.md).
The following diagram shows an example build sequence involving Buildx and The following diagram shows an example build sequence involving Buildx and
BuildKit. BuildKit.
![Buildx and BuildKit sequence diagram](./images/build-execution.png) ![Buildx and BuildKit sequence diagram](./images/build-execution.png)

13
content/build/attestations/_index.md
View File

@ -1,9 +1,10 @@
--- ---
title: Build attestations title: Build attestations
keywords: build, attestations, sbom, provenance keywords: build, attestations, sbom, provenance
description: > description: 'Introduction to SBOM and provenance attestations with Docker Build;
Introduction to SBOM and provenance attestations with Docker Build; what they what they are and why they exist
are and why they exist
'
--- ---
{% include build-feature-state.md buildkit_v=">=0.11" buildx_v=">=0.10" %} {% include build-feature-state.md buildkit_v=">=0.11" buildx_v=">=0.10" %}
@ -66,9 +67,9 @@ index in a manifest for the final image.
<!-- prettier-ignore --> <!-- prettier-ignore -->
BuildKit produces attestations in the BuildKit produces attestations in the
[in-toto format](https://github.com/in-toto/attestation){: target="blank" rel="noopener" class="\_" }, [in-toto format](https://github.com/in-toto/attestation),
as defined by the as defined by the
[in-toto framework](https://in-toto.io/){: target="blank" rel="noopener" class="\_" }, [in-toto framework](https://in-toto.io/),
a standard supported by the Linux Foundation. a standard supported by the Linux Foundation.
Attestations attach to images as a manifest in the image index. The data records Attestations attach to images as a manifest in the image index. The data records
@ -155,4 +156,4 @@ To deep-dive into the specifics about how attestations are stored, see
Learn more about the available attestation types and how to use them: Learn more about the available attestation types and how to use them:
- [Provenance](slsa-provenance.md) - [Provenance](slsa-provenance.md)
- [SBOM](sbom.md) - [SBOM](sbom.md)

21
content/build/attestations/sbom.md
View File

@ -23,8 +23,7 @@ final image.
The SBOMs generated by BuildKit follow the SPDX standard. SBOMs attach to the The SBOMs generated by BuildKit follow the SPDX standard. SBOMs attach to the
final image as a JSON-encoded SPDX document, using the format defined by the final image as a JSON-encoded SPDX document, using the format defined by the
[in-toto SPDX predicate](https://github.com/in-toto/attestation/blob/main/spec/predicates/spdx.md){: [in-toto SPDX predicate](https://github.com/in-toto/attestation/blob/main/spec/predicates/spdx.md).
target="blank" rel="noopener" }.
## Create SBOM attestations ## Create SBOM attestations
@ -138,7 +137,7 @@ Only stages that are built will be scanned. Stages that aren't dependencies of
the target stage won't be built, or scanned. the target stage won't be built, or scanned.
The following Dockerfile example uses multi-stage builds to build a static website with The following Dockerfile example uses multi-stage builds to build a static website with
[Hugo](https://gohugo.io/){: target="blank" rel="noopener" class="_"}. [Hugo](https://gohugo.io/).
```dockerfile ```dockerfile
# syntax=docker/dockerfile:1 # syntax=docker/dockerfile:1
@ -177,7 +176,7 @@ Using the `--format` option, you can specify a template for the output. All
SBOM-related data is available under the `.SBOM` attribute. For example, to get SBOM-related data is available under the `.SBOM` attribute. For example, to get
the raw contents of an SBOM in SPDX format: the raw contents of an SBOM in SPDX format:
{% raw %}
```console ```console
$ docker buildx imagetools inspect <namespace>/<image>:<version> \ $ docker buildx imagetools inspect <namespace>/<image>:<version> \
--format "{{ json .SBOM.SPDX }}" --format "{{ json .SBOM.SPDX }}"
@ -186,13 +185,13 @@ $ docker buildx imagetools inspect <namespace>/<image>:<version> \
... ...
} }
``` ```
{% endraw %}
You can also construct more complex expressions using the full functionality You can also construct more complex expressions using the full functionality
of Go templates. For example, you can list all the installed packages and their of Go templates. For example, you can list all the installed packages and their
version identifiers: version identifiers:
{% raw %}
```console ```console
$ docker buildx imagetools inspect <namespace>/<image>:<version> \ $ docker buildx imagetools inspect <namespace>/<image>:<version> \
--format "{{ range .SBOM.SPDX.packages }}{{ .name }}@{{ .versionInfo }}{{ println }}{{ end }}" --format "{{ range .SBOM.SPDX.packages }}{{ .name }}@{{ .versionInfo }}{{ println }}{{ end }}"
@ -202,19 +201,19 @@ base-files@11ubuntu5.6
base-passwd@3.5.47 base-passwd@3.5.47
... ...
``` ```
{% endraw %}
## SBOM generator ## SBOM generator
BuildKit generates the SBOM using a scanner plugin. By default, it uses is the BuildKit generates the SBOM using a scanner plugin. By default, it uses is the
[BuildKit Syft scanner](https://github.com/docker/buildkit-syft-scanner){: target="blank" rel="noopener" } [BuildKit Syft scanner](https://github.com/docker/buildkit-syft-scanner)
plugin. This plugin is built on top of plugin. This plugin is built on top of
[Anchore's Syft](https://github.com/anchore/syft){: target="blank" rel="noopener" }, [Anchore's Syft](https://github.com/anchore/syft),
an open source tool for generating an SBOM. an open source tool for generating an SBOM.
You can select a different plugin to use with the `generator` option, specifying You can select a different plugin to use with the `generator` option, specifying
an image that implements the an image that implements the
[BuildKit SBOM scanner protocol](https://github.com/moby/buildkit/blob/master/docs/attestations/sbom-protocol.md){: target="blank" rel="noopener" }. [BuildKit SBOM scanner protocol](https://github.com/moby/buildkit/blob/master/docs/attestations/sbom-protocol.md).
```console ```console
$ docker buildx build --attest type=sbom,generator=<image> . $ docker buildx build --attest type=sbom,generator=<image> .
@ -323,4 +322,4 @@ The following JSON example shows what an SBOM attestation might look like.
"spdxVersion": "SPDX-2.2" "spdxVersion": "SPDX-2.2"
} }
} }
``` ```

10
content/build/attestations/slsa-provenance.md
View File

@ -151,7 +151,7 @@ Using the `--format` option, you can specify a template for the output. All
provenance-related data is available under the `.Provenance` attribute. For provenance-related data is available under the `.Provenance` attribute. For
example, to get the raw contents of the Provenance in the SLSA format: example, to get the raw contents of the Provenance in the SLSA format:
{% raw %}
```console ```console
$ docker buildx imagetools inspect <namespace>/<image>:<version> \ $ docker buildx imagetools inspect <namespace>/<image>:<version> \
--format "{{ json .Provenance.SLSA }}" --format "{{ json .Provenance.SLSA }}"
@ -160,13 +160,13 @@ $ docker buildx imagetools inspect <namespace>/<image>:<version> \
... ...
} }
``` ```
{% endraw %}
You can also construct more complex expressions using the full functionality of You can also construct more complex expressions using the full functionality of
Go templates. For example, for provenance generated with `mode=max`, you can Go templates. For example, for provenance generated with `mode=max`, you can
extract the full source code of the Dockerfile used to build the image: extract the full source code of the Dockerfile used to build the image:
{% raw %}
```console ```console
$ docker buildx imagetools inspect <namespace>/<image>:<version> \ $ docker buildx imagetools inspect <namespace>/<image>:<version> \
--format '{{ range (index .Provenance.SLSA.metadata "https://mobyproject.org/buildkit@v1#metadata").source.infos }}{{ if eq .filename "Dockerfile" }}{{ .data }}{{ end }}{{ end }}' | base64 -d --format '{{ range (index .Provenance.SLSA.metadata "https://mobyproject.org/buildkit@v1#metadata").source.infos }}{{ if eq .filename "Dockerfile" }}{{ .data }}{{ end }}{{ end }}' | base64 -d
@ -174,7 +174,7 @@ FROM ubuntu:20.04
RUN apt-get update RUN apt-get update
... ...
``` ```
{% endraw %}
## Provenance attestation example ## Provenance attestation example
@ -349,4 +349,4 @@ attestation with `mode=max` looks like:
} }
} }
} }
``` ```

10
content/build/bake/_index.md
View File

@ -1,21 +1,21 @@
--- ---
title: High-level builds with Bake title: High-level builds with Bake
keywords: build, buildx, bake, buildkit, hcl, json, compose keywords: build, buildx, bake, buildkit, hcl, json, compose
redirect_from: aliases:
- /build/customize/bake/ - /build/customize/bake/
--- ---
> This command is experimental. > This command is experimental.
> >
> The design of bake is in early stages, and we are looking for [feedback from users](https://github.com/docker/buildx/issues){:target="blank" rel="noopener" class=""}. > The design of bake is in early stages, and we are looking for [feedback from users](https://github.com/docker/buildx/issues).
{: .experimental } { .experimental }
Buildx also aims to provide support for high-level build concepts that go beyond Buildx also aims to provide support for high-level build concepts that go beyond
invoking a single build command. We want to support building all the images in invoking a single build command. We want to support building all the images in
your application together and let the users define project specific reusable your application together and let the users define project specific reusable
build flows that can then be easily invoked by anyone. build flows that can then be easily invoked by anyone.
[BuildKit](https://github.com/moby/buildkit){:target="blank" rel="noopener" class=""} [BuildKit](https://github.com/moby/buildkit)
efficiently handles multiple concurrent build requests and de-duplicating work. efficiently handles multiple concurrent build requests and de-duplicating work.
The build commands can be combined with general-purpose command runners The build commands can be combined with general-purpose command runners
(for example, `make`). However, these tools generally invoke builds in sequence (for example, `make`). However, these tools generally invoke builds in sequence
@ -38,4 +38,4 @@ and also allows better code reuse, different target groups and extended features
* [Configuring builds](configuring-build.md) * [Configuring builds](configuring-build.md)
* [User defined HCL functions](hcl-funcs.md) * [User defined HCL functions](hcl-funcs.md)
* [Defining additional build contexts and linking targets](build-contexts.md) * [Defining additional build contexts and linking targets](build-contexts.md)
* [Building from Compose file](compose-file.md) * [Building from Compose file](compose-file.md)

6
content/build/bake/build-contexts.md
View File

@ -1,7 +1,7 @@
--- ---
title: "Defining additional build contexts and linking targets" title: Defining additional build contexts and linking targets
keywords: build, buildx, bake, buildkit, hcl keywords: build, buildx, bake, buildkit, hcl
redirect_from: aliases:
- /build/customize/bake/build-contexts/ - /build/customize/bake/build-contexts/
--- ---
@ -76,4 +76,4 @@ target "app" {
Please note that in most cases you should just use a single multi-stage Please note that in most cases you should just use a single multi-stage
Dockerfile with multiple targets for similar behavior. This case is recommended Dockerfile with multiple targets for similar behavior. This case is recommended
when you have multiple Dockerfiles that can't be easily merged into one. when you have multiple Dockerfiles that can't be easily merged into one.

8
content/build/bake/compose-file.md
View File

@ -1,7 +1,7 @@
--- ---
title: "Building from Compose file" title: Building from Compose file
keywords: build, buildx, bake, buildkit, compose keywords: build, buildx, bake, buildkit, compose
redirect_from: aliases:
- /build/customize/bake/compose-file/ - /build/customize/bake/compose-file/
--- ---
@ -97,7 +97,7 @@ $ docker buildx bake --print
The compose format has some limitations compared to the HCL format: The compose format has some limitations compared to the HCL format:
* Specifying variables or global scope attributes is not yet supported * Specifying variables or global scope attributes is not yet supported
* `inherits` service field is not supported, but you can use [YAML anchors](../../compose/compose-file/10-fragments.md){:target="blank" rel="noopener" class=""} * `inherits` service field is not supported, but you can use [YAML anchors](../../compose/compose-file/10-fragments.md)
to reference other services like the example above to reference other services like the example above
## `.env` file ## `.env` file
@ -275,4 +275,4 @@ Complete list of valid fields for `x-bake`:
* `pull` * `pull`
* `secret` * `secret`
* `ssh` * `ssh`
* `tags` * `tags`

8
content/build/bake/configuring-build.md
View File

@ -1,7 +1,7 @@
--- ---
title: "Configuring builds" title: Configuring builds
keywords: build, buildx, bake, buildkit, hcl, json keywords: build, buildx, bake, buildkit, hcl, json
redirect_from: aliases:
- /build/customize/bake/configuring-build/ - /build/customize/bake/configuring-build/
--- ---
@ -189,7 +189,7 @@ $ docker buildx bake --set app.args.mybuildarg=bar --set app.platform=linux/arm6
} }
``` ```
Pattern matching syntax defined in [https://golang.org/pkg/path/#Match](https://golang.org/pkg/path/#Match){:target="blank" rel="noopener" class=""} Pattern matching syntax defined in [https://golang.org/pkg/path/#Match](https://golang.org/pkg/path/#Match)
is also supported: is also supported:
```console ```console
@ -274,4 +274,4 @@ $ docker buildx bake -f docker-bake1.hcl -f docker-bake2.hcl --print app
} }
} }
} }
``` ```

10
content/build/bake/hcl-funcs.md
View File

@ -1,7 +1,7 @@
--- ---
title: "User defined HCL functions" title: User defined HCL functions
keywords: build, buildx, bake, buildkit, hcl keywords: build, buildx, bake, buildkit, hcl
redirect_from: aliases:
- /build/customize/bake/hcl-funcs/ - /build/customize/bake/hcl-funcs/
--- ---
@ -100,7 +100,7 @@ $ TAG=$(git rev-parse --short HEAD) docker buildx bake --print webapp
## Using the `add` function ## Using the `add` function
You can use [`go-cty` stdlib functions](https://github.com/zclconf/go-cty/tree/main/cty/function/stdlib){:target="blank" rel="noopener" class=""}. You can use [`go-cty` stdlib functions](https://github.com/zclconf/go-cty/tree/main/cty/function/stdlib).
Here we are using the `add` function. Here we are using the `add` function.
```hcl ```hcl
@ -147,7 +147,7 @@ $ docker buildx bake --print webapp
## Defining an `increment` function ## Defining an `increment` function
It also supports [user defined functions](https://github.com/hashicorp/hcl/tree/main/ext/userfunc){:target="blank" rel="noopener" class=""}. It also supports [user defined functions](https://github.com/hashicorp/hcl/tree/main/ext/userfunc).
The following example defines a simple an `increment` function. The following example defines a simple an `increment` function.
```hcl ```hcl
@ -336,4 +336,4 @@ $ docker buildx bake --print app
} }
} }
} }
``` ```

4
content/build/bake/remote-definition.md
View File

@ -45,7 +45,7 @@ $ docker buildx bake "https://github.com/docker/cli.git#v20.10.11" --print
``` ```
As you can see the context is fixed to `https://github.com/docker/cli.git` even if As you can see the context is fixed to `https://github.com/docker/cli.git` even if
[no context is actually defined](https://github.com/docker/cli/blob/2776a6d694f988c0c1df61cad4bfac0f54e481c8/docker-bake.hcl#L17-L26){:target="blank" rel="noopener" class=""} [no context is actually defined](https://github.com/docker/cli/blob/2776a6d694f988c0c1df61cad4bfac0f54e481c8/docker-bake.hcl#L17-L26)
in the definition. in the definition.
If you want to access the main context for bake command from a bake file If you want to access the main context for bake command from a bake file
@ -133,4 +133,4 @@ $ docker buildx bake "https://github.com/tonistiigi/buildx.git#remote-test" "htt
#8 0.136 drwxrwxrwx 10 root root 4096 Jul 27 18:31 vendor #8 0.136 drwxrwxrwx 10 root root 4096 Jul 27 18:31 vendor
#8 0.136 -rwxrwxrwx 1 root root 9620 Jul 27 18:31 vendor.conf #8 0.136 -rwxrwxrwx 1 root root 9620 Jul 27 18:31 vendor.conf
#8 0.136 /bin/sh: stop: not found #8 0.136 /bin/sh: stop: not found
``` ```

8
content/build/builders/_index.md
View File

@ -1,7 +1,7 @@
--- ---
title: "Builders" title: Builders
keywords: build, buildx, builders, buildkit, drivers, backend keywords: build, buildx, builders, buildkit, drivers, backend
description: description: null
--- ---
A builder is a BuildKit daemon that you can use to run your builds. BuildKit A builder is a BuildKit daemon that you can use to run your builds. BuildKit
@ -16,7 +16,7 @@ running remotely. You interact with builders using the Docker CLI.
> The [Docker Desktop Builds view](../../desktop/use-desktop/builds.md) > The [Docker Desktop Builds view](../../desktop/use-desktop/builds.md)
> is a [Beta](../../release-lifecycle.md#beta) feature that lets you > is a [Beta](../../release-lifecycle.md#beta) feature that lets you
> view and manage builders using Docker Desktop. > view and manage builders using Docker Desktop.
{: .experimental } { .experimental }
## Default builder ## Default builder
@ -76,4 +76,4 @@ selected when you invoke builds.
- For information about how to interact with and manage builders, - For information about how to interact with and manage builders,
see [Manage builders](./manage.md) see [Manage builders](./manage.md)
- To learn about different types of builders, - To learn about different types of builders,
see [Build drivers](../drivers/index.md) see [Build drivers](../drivers/index.md)

6
content/build/builders/manage.md
View File

@ -1,7 +1,7 @@
--- ---
title: "Manage builders" title: Manage builders
keywords: build, buildx, builders, buildkit, drivers, backend keywords: build, buildx, builders, buildkit, drivers, backend
description: description: null
--- ---
You can create, inspect, and manage builders using `docker buildx` commands, You can create, inspect, and manage builders using `docker buildx` commands,
@ -105,4 +105,4 @@ you can inspect builders in Docker Desktop settings. See:
- [Change settings, Windows](../../desktop/settings/windows.md#builders) - [Change settings, Windows](../../desktop/settings/windows.md#builders)
- [Change settings, Mac](../../desktop/settings/mac.md#builders) - [Change settings, Mac](../../desktop/settings/mac.md#builders)
- [Change settings, Linux](../../desktop/settings/linux.md#builders) - [Change settings, Linux](../../desktop/settings/linux.md#builders)

12
content/build/building/base-images.md
View File

@ -2,7 +2,7 @@
title: Create a base image title: Create a base image
description: How to create base images description: How to create base images
keywords: images, base image, examples keywords: images, base image, examples
redirect_from: aliases:
- /articles/baseimages/ - /articles/baseimages/
- /engine/articles/baseimages/ - /engine/articles/baseimages/
- /engine/userguide/eng-image/baseimages/ - /engine/userguide/eng-image/baseimages/
@ -30,7 +30,7 @@ ones.
In general, start with a working machine that is running In general, start with a working machine that is running
the distribution you'd like to package as a parent image, though that is the distribution you'd like to package as a parent image, though that is
not required for some tools like Debian's [Debootstrap](https://wiki.debian.org/Debootstrap){:target="blank" rel="noopener" class=""}, not required for some tools like Debian's [Debootstrap](https://wiki.debian.org/Debootstrap),
which you can also use to build Ubuntu images. which you can also use to build Ubuntu images.
It can be as simple as this to create an Ubuntu parent image: It can be as simple as this to create an Ubuntu parent image:
@ -48,7 +48,7 @@ It can be as simple as this to create an Ubuntu parent image:
DISTRIB_DESCRIPTION="Ubuntu 20.04 LTS" DISTRIB_DESCRIPTION="Ubuntu 20.04 LTS"
There are more example scripts for creating parent images in There are more example scripts for creating parent images in
[the Docker GitHub repository](https://github.com/docker/docker/blob/master/contrib){:target="blank" rel="noopener" class=""}. [the Docker GitHub repository](https://github.com/docker/docker/blob/master/contrib).
## Create a simple parent image using scratch ## Create a simple parent image using scratch
@ -70,7 +70,7 @@ CMD ["/hello"]
``` ```
Assuming you built the "hello" executable example by using the source code at Assuming you built the "hello" executable example by using the source code at
[https://github.com/docker-library/hello-world](https://github.com/docker-library/hello-world){:target="blank" rel="noopener" class=""}, [https://github.com/docker-library/hello-world](https://github.com/docker-library/hello-world),
and you compiled it with the `-static` flag, you can build this Docker and you compiled it with the `-static` flag, you can build this Docker
image using this `docker build` command: image using this `docker build` command:
@ -100,7 +100,7 @@ $ docker run --rm hello
``` ```
This example creates the hello-world image used in the tutorials. This example creates the hello-world image used in the tutorials.
If you want to test it out, you can clone [the image repo](https://github.com/docker-library/hello-world){:target="blank" rel="noopener" class=""}. If you want to test it out, you can clone [the image repo](https://github.com/docker-library/hello-world).
## More resources ## More resources
@ -109,4 +109,4 @@ There are lots of resources available to help you write your `Dockerfile`.
* There's a [complete guide to all the instructions](../../engine/reference/builder.md) available for use in a `Dockerfile` in the reference section. * There's a [complete guide to all the instructions](../../engine/reference/builder.md) available for use in a `Dockerfile` in the reference section.
* To help you write a clear, readable, maintainable `Dockerfile`, we've also * To help you write a clear, readable, maintainable `Dockerfile`, we've also
written a [Dockerfile best practices guide](../../develop/develop-images/dockerfile_best-practices.md). written a [Dockerfile best practices guide](../../develop/develop-images/dockerfile_best-practices.md).
* If your goal is to create a new Docker Official Image, read [Docker Official Images](../../docker-hub/official_images.md). * If your goal is to create a new Docker Official Image, read [Docker Official Images](../../docker-hub/official_images.md).

4
content/build/building/context.md
View File

@ -356,7 +356,7 @@ ERROR: failed to solve: failed to compute cache key: failed to calculate checksu
The following example builds an image using a `Dockerfile` that is passed The following example builds an image using a `Dockerfile` that is passed
through standard input using through standard input using
[shell heredocs](https://en.wikipedia.org/wiki/Here_document){: target="_blank" rel="noopener"}: [shell heredocs](https://en.wikipedia.org/wiki/Here_document):
```bash ```bash
docker build -t myimage:latest - <<EOF docker build -t myimage:latest - <<EOF
@ -366,4 +366,4 @@ EOF
``` ```
This approach is useful when you want to quickly run a build command with a This approach is useful when you want to quickly run a build command with a
Dockerfile that's short and concise. Dockerfile that's short and concise.

12
content/build/building/env-vars.md
View File

@ -2,8 +2,8 @@
title: Environment variables for Docker Build title: Environment variables for Docker Build
description: Use environment variables to configure builds description: Use environment variables to configure builds
keywords: docker build, buildx, buildkit, env, environment variables, config keywords: docker build, buildx, buildkit, env, environment variables, config
redirect_from: aliases:
- /build/buildkit/color-output-controls/ - /build/buildkit/color-output-controls/
--- ---
You can set the following environment variables to enable, disable, or change You can set the following environment variables to enable, disable, or change
@ -30,7 +30,7 @@ See also
You can express Boolean values for environment variables in different ways. For You can express Boolean values for environment variables in different ways. For
example, `true`, `1`, and `T` all evaluate to true. Evaluation is done using the example, `true`, `1`, and `T` all evaluate to true. Evaluation is done using the
`strconv.ParseBool` function in the Go standard library. See the `strconv.ParseBool` function in the Go standard library. See the
[reference documentation](https://pkg.go.dev/strconv#ParseBool){: target="_blank" rel="noopener" class="_" } [reference documentation](https://pkg.go.dev/strconv#ParseBool)
for details. for details.
## BUILDKIT_COLORS ## BUILDKIT_COLORS
@ -43,10 +43,10 @@ $ export BUILDKIT_COLORS="run=123,20,245:error=yellow:cancel=blue:warning=white"
``` ```
Color values can be any valid RGB hex code, or one of the Color values can be any valid RGB hex code, or one of the
[BuildKit predefined colors](https://github.com/moby/buildkit/blob/master/util/progress/progressui/colors.go){: target="_blank" rel="noopener" class="_" }. [BuildKit predefined colors](https://github.com/moby/buildkit/blob/master/util/progress/progressui/colors.go).
Setting `NO_COLOR` to anything turns off colorized output, as recommended by Setting `NO_COLOR` to anything turns off colorized output, as recommended by
[no-color.org](https://no-color.org/){: target="_blank" rel="noopener" class="_" }. [no-color.org](https://no-color.org/).
## BUILDKIT_HOST ## BUILDKIT_HOST
@ -240,4 +240,4 @@ Usage:
```console ```console
$ export BUILDX_NO_DEFAULT_LOAD=1 $ export BUILDX_NO_DEFAULT_LOAD=1
``` ```

10
content/build/building/multi-platform.md
View File

@ -2,7 +2,7 @@
title: Multi-platform images title: Multi-platform images
description: Introduction to multi-platform images and how to build them description: Introduction to multi-platform images and how to build them
keywords: build, buildx, buildkit, multi-platform images keywords: build, buildx, buildkit, multi-platform images
redirect_from: aliases:
- /build/buildx/multiplatform-images/ - /build/buildx/multiplatform-images/
- /desktop/multi-arch/ - /desktop/multi-arch/
- /docker-for-mac/multi-arch/ - /docker-for-mac/multi-arch/
@ -16,7 +16,7 @@ operating systems, such as Windows.
When you run an image with multi-platform support, Docker automatically selects When you run an image with multi-platform support, Docker automatically selects
the image that matches your OS and architecture. the image that matches your OS and architecture.
Most of the Docker Official Images on Docker Hub provide a [variety of architectures](https://github.com/docker-library/official-images#architectures-other-than-amd64){:target="blank" rel="noopener" class=""}. Most of the Docker Official Images on Docker Hub provide a [variety of architectures](https://github.com/docker-library/official-images#architectures-other-than-amd64).
For example, the `busybox` image supports `amd64`, `arm32v5`, `arm32v6`, For example, the `busybox` image supports `amd64`, `arm32v5`, `arm32v6`,
`arm32v7`, `arm64v8`, `i386`, `ppc64le`, and `s390x`. When running this image `arm32v7`, `arm64v8`, `i386`, `ppc64le`, and `s390x`. When running this image
on an `x86_64` / `amd64` machine, the `amd64` variant is pulled and run. on an `x86_64` / `amd64` machine, the `amd64` variant is pulled and run.
@ -147,7 +147,7 @@ NAME/NODE DRIVER/ENDPOINT STATUS BUILDKIT PLATFORMS
mybuilder * docker-container mybuilder * docker-container
mybuilder0 unix:///var/run/docker.sock running v0.12.1 linux/amd64, linux/amd64/v2, linux/amd64/v3, linux/arm64, linux/riscv64, linux/ppc64le, linux/s390x, linux/386, linux/mips64le, linux/mips64, linux/arm/v7, linux/arm/v6 mybuilder0 unix:///var/run/docker.sock running v0.12.1 linux/amd64, linux/amd64/v2, linux/amd64/v3, linux/arm64, linux/riscv64, linux/ppc64le, linux/s390x, linux/386, linux/mips64le, linux/mips64, linux/arm/v7, linux/arm/v6
default docker default docker
default default running v{{ site.buildkit_version }} linux/amd64, linux/arm64, linux/arm/v7, linux/arm/v6 default default running v{{% param "buildkit_version" %}} linux/amd64, linux/arm64, linux/arm/v7, linux/arm/v6
``` ```
## Example ## Example
@ -255,6 +255,6 @@ multi-architecture support, which means you can run containers for different
Linux architectures such as `arm`, `mips`, `ppc64le`, and even `s390x`. Linux architectures such as `arm`, `mips`, `ppc64le`, and even `s390x`.
This does not require any special configuration in the container itself as it This does not require any special configuration in the container itself as it
uses [qemu-static](https://wiki.qemu.org/Main_Page){:target="blank" rel="noopener" class=""} uses [qemu-static](https://wiki.qemu.org/Main_Page)
from the Docker Desktop VM. Because of this, you can run an ARM container, from the Docker Desktop VM. Because of this, you can run an ARM container,
like the `arm32v7` or `ppc64le` variants of the busybox image. like the `arm32v7` or `ppc64le` variants of the busybox image.

10
content/build/building/multi-stage.md
View File

@ -1,10 +1,12 @@
--- ---
title: Multi-stage builds title: Multi-stage builds
description: | description: 'Learn about multi-stage builds and how you can use
Learn about multi-stage builds and how you can use
them to improve your builds and get smaller images them to improve your builds and get smaller images
'
keywords: build, best practices keywords: build, best practices
redirect_from: aliases:
- /engine/userguide/eng-image/multistage-build/ - /engine/userguide/eng-image/multistage-build/
- /develop/develop-images/multistage-build/ - /develop/develop-images/multistage-build/
--- ---
@ -211,4 +213,4 @@ Removing intermediate container bbc025b93175
Successfully built 09fc3770a9c4 Successfully built 09fc3770a9c4
``` ```
The legacy builder processes `stage1`, even if `stage2` doesn't depend on it. The legacy builder processes `stage1`, even if `stage2` doesn't depend on it.

6
content/build/building/opentelemetry.md
View File

@ -3,9 +3,9 @@ title: OpenTelemetry support
keywords: build, buildx buildkit, opentelemetry keywords: build, buildx buildkit, opentelemetry
--- ---
Both Buildx and BuildKit support [OpenTelemetry](https://opentelemetry.io/){:target="blank" rel="noopener" class=""}. Both Buildx and BuildKit support [OpenTelemetry](https://opentelemetry.io/).
To capture the trace to [Jaeger](https://github.com/jaegertracing/jaeger){:target="blank" rel="noopener" class=""}, To capture the trace to [Jaeger](https://github.com/jaegertracing/jaeger),
set `JAEGER_TRACE` environment variable to the collection address using a set `JAEGER_TRACE` environment variable to the collection address using a
`driver-opt`. `driver-opt`.
@ -34,4 +34,4 @@ $ docker buildx inspect --bootstrap
Buildx commands should be traced at `http://127.0.0.1:16686/`: Buildx commands should be traced at `http://127.0.0.1:16686/`:
![OpenTelemetry Buildx Bake](../images/opentelemetry.png) ![OpenTelemetry Buildx Bake](../images/opentelemetry.png)

6
content/build/building/packaging.md
View File

@ -1,7 +1,7 @@
--- ---
title: Packaging your software title: Packaging your software
keywords: build, buildx, buildkit, getting started, dockerfile keywords: build, buildx, buildkit, getting started, dockerfile
redirect_from: aliases:
- /build/hellobuild/ - /build/hellobuild/
--- ---
@ -126,7 +126,7 @@ your Dockerfile, and should be the first line in Dockerfiles.
> We recommend using `docker/dockerfile:1`, which always points to the latest > We recommend using `docker/dockerfile:1`, which always points to the latest
> release of the version 1 syntax. BuildKit automatically checks for updates of > release of the version 1 syntax. BuildKit automatically checks for updates of
> the syntax before building, making sure you are using the most current version. > the syntax before building, making sure you are using the most current version.
{: .tip } { .tip }
### Base image ### Base image
@ -273,4 +273,4 @@ If you are interested in examples in other languages, such as Go, check out
our [language-specific guides](../../language/index.md) in the Guides section. our [language-specific guides](../../language/index.md) in the Guides section.
For more information about building, including advanced use cases and patterns, For more information about building, including advanced use cases and patterns,
refer to the [Build with Docker](../guide/index.md) guide. refer to the [Build with Docker](../guide/index.md) guide.

12
content/build/buildkit/_index.md
View File

@ -6,7 +6,7 @@ keywords: build, buildkit
## Overview ## Overview
[BuildKit](https://github.com/moby/buildkit){:target="blank" rel="noopener" class=""} [BuildKit](https://github.com/moby/buildkit)
is an improved backend to replace the legacy builder. BuildKit is the default builder is an improved backend to replace the legacy builder. BuildKit is the default builder
for users on Docker Desktop, and Docker Engine as of version 23.0. for users on Docker Desktop, and Docker Engine as of version 23.0.
@ -36,8 +36,7 @@ files to be read or uploaded before the work can begin.
## LLB ## LLB
At the core of BuildKit is a At the core of BuildKit is a
[Low-Level Build (LLB)](https://github.com/moby/buildkit#exploring-llb){:target="blank" [Low-Level Build (LLB)](https://github.com/moby/buildkit#exploring-llb) definition format. LLB is an intermediate binary format
rel="noopener" class=""} definition format. LLB is an intermediate binary format
that allows developers to extend BuildKit. LLB defines a content-addressable that allows developers to extend BuildKit. LLB defines a content-addressable
dependency graph that can be used to put together very complex build dependency graph that can be used to put together very complex build
definitions. It also supports features not exposed in Dockerfiles, like direct definitions. It also supports features not exposed in Dockerfiles, like direct
@ -54,8 +53,7 @@ more precise, and portable. The build cache can even be exported to a registry,
where it can be pulled on-demand by subsequent invocations on any host. where it can be pulled on-demand by subsequent invocations on any host.
LLB can be generated directly using a LLB can be generated directly using a
[golang client package](https://pkg.go.dev/github.com/moby/buildkit/client/llb){:target="blank" [golang client package](https://pkg.go.dev/github.com/moby/buildkit/client/llb) that allows defining the relationships between your
rel="noopener" class=""} that allows defining the relationships between your
build operations using Go language primitives. This gives you full power to run build operations using Go language primitives. This gives you full power to run
anything you can imagine, but will probably not be how most people will define anything you can imagine, but will probably not be how most people will define
their builds. Instead, most users would use a frontend component, or LLB nested their builds. Instead, most users would use a frontend component, or LLB nested
@ -112,5 +110,5 @@ daemon.
> >
> BuildKit only supports building Linux containers. Windows support is tracked > BuildKit only supports building Linux containers. Windows support is tracked
> in > in
> [`moby/buildkit#616`](https://github.com/moby/buildkit/issues/616){:target="blank" rel="noopener" class=""} > [`moby/buildkit#616`](https://github.com/moby/buildkit/issues/616)
{: .warning} { .warning }

12
content/build/buildkit/configure.md
View File

@ -136,19 +136,19 @@ $ docker buildx build --push --tag myregistry.com/myimage:latest .
## CNI networking ## CNI networking
CNI networking for builders can be useful for dealing with network port CNI networking for builders can be useful for dealing with network port
contention during concurrent builds. CNI is [not yet](https://github.com/moby/buildkit/issues/28){:target="blank" rel="noopener" class=""} contention during concurrent builds. CNI is [not yet](https://github.com/moby/buildkit/issues/28)
available in the default BuildKit image. But you can create your own image that available in the default BuildKit image. But you can create your own image that
includes CNI support. includes CNI support.
The following Dockerfile example shows a custom BuildKit image with CNI support. The following Dockerfile example shows a custom BuildKit image with CNI support.
It uses the [CNI config for integration tests](https://github.com/moby/buildkit/blob/master//hack/fixtures/cni.json){:target="blank" rel="noopener" class=""} It uses the [CNI config for integration tests](https://github.com/moby/buildkit/blob/master//hack/fixtures/cni.json)
in BuildKit as an example. Feel free to include your own CNI configuration. in BuildKit as an example. Feel free to include your own CNI configuration.
{% raw %}
```dockerfile ```dockerfile
# syntax=docker/dockerfile:1 # syntax=docker/dockerfile:1
ARG BUILDKIT_VERSION=v{{ site.buildkit_version }} ARG BUILDKIT_VERSION=v{{% param "buildkit_version" %}}
ARG CNI_VERSION=v1.0.1 ARG CNI_VERSION=v1.0.1
FROM --platform=$BUILDPLATFORM alpine AS cni-plugins FROM --platform=$BUILDPLATFORM alpine AS cni-plugins
@ -165,7 +165,7 @@ RUN apk add --no-cache iptables
COPY --from=cni-plugins /opt/cni/bin /opt/cni/bin COPY --from=cni-plugins /opt/cni/bin /opt/cni/bin
ADD https://raw.githubusercontent.com/moby/buildkit/${BUILDKIT_VERSION}/hack/fixtures/cni.json /etc/buildkit/cni.json ADD https://raw.githubusercontent.com/moby/buildkit/${BUILDKIT_VERSION}/hack/fixtures/cni.json /etc/buildkit/cni.json
``` ```
{% endraw %}
Now you can build this image, and create a builder instance from it using Now you can build this image, and create a builder instance from it using
[the `--driver-opt image` option](../../engine/reference/commandline/buildx_create.md#driver-opt): [the `--driver-opt image` option](../../engine/reference/commandline/buildx_create.md#driver-opt):
@ -211,4 +211,4 @@ requests. This connection limit prevents your build from getting stuck while
pulling images. The dedicated metadata connection helps reduce the overall build pulling images. The dedicated metadata connection helps reduce the overall build
time. time.
More information: [moby/buildkit#2259](https://github.com/moby/buildkit/pull/2259){:target="blank" rel="noopener" class=""} More information: [moby/buildkit#2259](https://github.com/moby/buildkit/pull/2259)

27
content/build/cache/_index.md vendored
View File

@ -1,11 +1,12 @@
--- ---
title: Optimizing builds with cache management title: Optimizing builds with cache management
description: Improve your build speeds by taking advantage of the builtin cache description: Improve your build speeds by taking advantage of the builtin cache
keywords: > keywords: 'build, buildx, buildkit, dockerfile, image layers, build instructions,
build, buildx, buildkit, dockerfile, image layers, build instructions, build build context
context
redirect_from: '
- /build/building/cache/ aliases:
- /build/building/cache/
--- ---
You will likely find yourself rebuilding the same Docker image over and over You will likely find yourself rebuilding the same Docker image over and over
@ -37,7 +38,7 @@ Each instruction in this Dockerfile translates (roughly) to a layer in your
final image. You can think of image layers as a stack, with each layer adding final image. You can think of image layers as a stack, with each layer adding
more content on top of the layers that came before it: more content on top of the layers that came before it:
![Image layer diagram](../images/cache-stack.png){:.invertible} ![Image layer diagram](../images/cache-stack.png)
Whenever a layer changes, that layer will need to be re-built. For example, Whenever a layer changes, that layer will need to be re-built. For example,
suppose you make a change to your program in the `main.c` file. After this suppose you make a change to your program in the `main.c` file. After this
@ -49,7 +50,7 @@ If a layer changes, all other layers that come after it are also affected. When
the layer with the `COPY` command gets invalidated, all layers that follow will the layer with the `COPY` command gets invalidated, all layers that follow will
need to run again, too: need to run again, too:
![Image layer diagram, showing cache invalidation](../images/cache-stack-invalidated.png){:.invertible} ![Image layer diagram, showing cache invalidation](../images/cache-stack-invalidated.png)
And that's the Docker build cache in a nutshell. Once a layer changes, then all And that's the Docker build cache in a nutshell. Once a layer changes, then all
downstream layers need to be rebuilt as well. Even if they wouldn't build downstream layers need to be rebuilt as well. Even if they wouldn't build
@ -199,12 +200,12 @@ layers to a minimum.
#### Use an appropriate base image #### Use an appropriate base image
Docker provides over 170 pre-built [official images](https://hub.docker.com/search?q=&image_filter=official){:target="blank" rel="noopener" class=""} Docker provides over 170 pre-built [official images](https://hub.docker.com/search?q=&image_filter=official)
for almost every common development scenario. For example, if you're building a for almost every common development scenario. For example, if you're building a
Java web server, use a dedicated image such as [`eclipse-temurin`](https://hub.docker.com/_/eclipse-temurin/){:target="blank" rel="noopener" class=""}. Java web server, use a dedicated image such as [`eclipse-temurin`](https://hub.docker.com/_/eclipse-temurin/).
Even when there's not an official image for what you might want, Docker provides Even when there's not an official image for what you might want, Docker provides
images from [verified publishers](https://hub.docker.com/search?q=&image_filter=store){:target="blank" rel="noopener" class=""} images from [verified publishers](https://hub.docker.com/search?q=&image_filter=store)
and [open source partners](https://hub.docker.com/search?q=&image_filter=open_source){:target="blank" rel="noopener" class=""} and [open source partners](https://hub.docker.com/search?q=&image_filter=open_source)
that can help you on your way. The Docker community often produces third-party that can help you on your way. The Docker community often produces third-party
images to use as well. images to use as well.
@ -273,7 +274,7 @@ RUN echo "the first command" && \
``` ```
Another shell feature that allows you to simplify and concatenate commands in a Another shell feature that allows you to simplify and concatenate commands in a
neat way are [`heredocs`](https://en.wikipedia.org/wiki/Here_document){:target="blank" rel="noopener" class=""}. neat way are [`heredocs`](https://en.wikipedia.org/wiki/Here_document).
It enables you to create multi-line scripts with good readability: It enables you to create multi-line scripts with good readability:
```dockerfile ```dockerfile
@ -292,4 +293,4 @@ of continuing.)
For more information on using cache to do efficient builds, see: For more information on using cache to do efficient builds, see:
- [Garbage collection](garbage-collection.md) - [Garbage collection](garbage-collection.md)
- [Cache storage backends](./backends/index.md) - [Cache storage backends](./backends/index.md)

16
content/build/cache/backends/_index.md vendored
View File

@ -1,8 +1,8 @@
--- ---
title: "Cache storage backends" title: Cache storage backends
keywords: build, buildx, cache, backend, gha, azblob, s3, registry, local keywords: build, buildx, cache, backend, gha, azblob, s3, registry, local
redirect_from: aliases:
- /build/building/cache/backends/ - /build/building/cache/backends/
--- ---
To ensure fast builds, BuildKit automatically caches the build result in its own To ensure fast builds, BuildKit automatically caches the build result in its own
@ -40,13 +40,13 @@ Buildx supports the following cache storage backends:
- `local`: writes the build cache to a local directory on the filesystem. - `local`: writes the build cache to a local directory on the filesystem.
- `gha`: uploads the build cache to - `gha`: uploads the build cache to
[GitHub Actions cache](https://docs.github.com/en/rest/actions/cache){:target="blank" rel="noopener" class=""} (beta). [GitHub Actions cache](https://docs.github.com/en/rest/actions/cache) (beta).
- `s3`: uploads the build cache to an - `s3`: uploads the build cache to an
[AWS S3 bucket](https://aws.amazon.com/s3/){:target="blank" rel="noopener" class=""} (unreleased). [AWS S3 bucket](https://aws.amazon.com/s3/) (unreleased).
- `azblob`: uploads the build cache to - `azblob`: uploads the build cache to
[Azure Blob Storage](https://azure.microsoft.com/en-us/services/storage/blobs/){:target="blank" rel="noopener" class=""} [Azure Blob Storage](https://azure.microsoft.com/en-us/services/storage/blobs/)
(unreleased). (unreleased).
## Command syntax ## Command syntax
@ -78,7 +78,7 @@ $ docker buildx build --push -t <registry>/<image> \
## Multiple caches ## Multiple caches
BuildKit currently only supports BuildKit currently only supports
[a single cache exporter](https://github.com/moby/buildkit/pull/3024){:target="blank" rel="noopener" class=""}. But you [a single cache exporter](https://github.com/moby/buildkit/pull/3024). But you
can import from as many remote caches as you like. For example, a common pattern can import from as many remote caches as you like. For example, a common pattern
is to use the cache of both the current branch and the main branch. The is to use the cache of both the current branch and the main branch. The
following example shows importing cache from multiple locations using the following example shows importing cache from multiple locations using the
@ -162,4 +162,4 @@ $ docker buildx build --push -t <registry>/<image> \
``` ```
This property is only meaningful with the `--cache-to` flag. When fetching This property is only meaningful with the `--cache-to` flag. When fetching
cache, BuildKit will auto-detect the correct media types to use. cache, BuildKit will auto-detect the correct media types to use.

12
content/build/cache/backends/azblob.md vendored
View File

@ -1,8 +1,8 @@
--- ---
title: "Azure Blob Storage cache" title: Azure Blob Storage cache
keywords: build, buildx, cache, backend, azblob, azure keywords: build, buildx, cache, backend, azblob, azure
redirect_from: aliases:
- /build/building/cache/backends/azblob/ - /build/building/cache/backends/azblob/
--- ---
> **Warning** > **Warning**
@ -11,7 +11,7 @@ redirect_from:
> `moby/buildkit:master` image in your Buildx driver. > `moby/buildkit:master` image in your Buildx driver.
The `azblob` cache store uploads your resulting build cache to The `azblob` cache store uploads your resulting build cache to
[Azure's blob storage service](https://azure.microsoft.com/en-us/services/storage/blobs/){:target="blank" rel="noopener" class=""}. [Azure's blob storage service](https://azure.microsoft.com/en-us/services/storage/blobs/).
> **Note** > **Note**
> >
@ -50,7 +50,7 @@ The following table describes the available CSV parameters that you can pass to
The `secret_access_key`, if left unspecified, is read from environment variables The `secret_access_key`, if left unspecified, is read from environment variables
on the BuildKit server following the scheme for the on the BuildKit server following the scheme for the
[Azure Go SDK](https://docs.microsoft.com/en-us/azure/developer/go/azure-sdk-authentication){:target="blank" rel="noopener" class=""}. [Azure Go SDK](https://docs.microsoft.com/en-us/azure/developer/go/azure-sdk-authentication).
The environment variables are read from the server, not the Buildx client. The environment variables are read from the server, not the Buildx client.
## Further reading ## Further reading
@ -58,4 +58,4 @@ The environment variables are read from the server, not the Buildx client.
For an introduction to caching see [Optimizing builds with cache](../index.md). For an introduction to caching see [Optimizing builds with cache](../index.md).
For more information on the `azblob` cache backend, see the For more information on the `azblob` cache backend, see the
[BuildKit README](https://github.com/moby/buildkit#azure-blob-storage-cache-experimental){:target="blank" rel="noopener" class=""}. [BuildKit README](https://github.com/moby/buildkit#azure-blob-storage-cache-experimental).

20
content/build/cache/backends/gha.md vendored
View File

@ -1,8 +1,8 @@
--- ---
title: "GitHub Actions cache" title: GitHub Actions cache
keywords: build, buildx, cache, backend, gha, github, actions keywords: build, buildx, cache, backend, gha, github, actions
redirect_from: aliases:
- /build/building/cache/backends/gha/ - /build/building/cache/backends/gha/
--- ---
> **Warning** > **Warning**
@ -12,10 +12,10 @@ redirect_from:
> unstable and may change in future releases. > unstable and may change in future releases.
The GitHub Actions cache utilizes the The GitHub Actions cache utilizes the
[GitHub-provided Action's cache](https://github.com/actions/cache){:target="blank" rel="noopener" class=""} available [GitHub-provided Action's cache](https://github.com/actions/cache) available
from within your CI execution environment. This is the recommended cache to use from within your CI execution environment. This is the recommended cache to use
inside your GitHub action pipelines, as long as your use case falls within the inside your GitHub action pipelines, as long as your use case falls within the
[size and usage limits set by GitHub](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows#usage-limits-and-eviction-policy){:target="blank" rel="noopener" class=""}. [size and usage limits set by GitHub](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows#usage-limits-and-eviction-policy).
> **Note** > **Note**
> >
@ -57,7 +57,7 @@ If the `url` or `token` parameters are left unspecified, the `gha` cache backend
will fall back to using environment variables. If you invoke the `docker buildx` will fall back to using environment variables. If you invoke the `docker buildx`
command manually from an inline step, then the variables must be manually command manually from an inline step, then the variables must be manually
exposed (using exposed (using
[`crazy-max/ghaction-github-runtime`](https://github.com/crazy-max/ghaction-github-runtime){:target="blank" rel="noopener" class=""}, [`crazy-max/ghaction-github-runtime`](https://github.com/crazy-max/ghaction-github-runtime),
for example). for example).
## Scope ## Scope
@ -81,14 +81,14 @@ $ docker buildx build --push -t <registry>/<image2> \
--cache-from type=gha,url=...,token=...,scope=$GITHUB_REF_NAME-image2 . --cache-from type=gha,url=...,token=...,scope=$GITHUB_REF_NAME-image2 .
``` ```
GitHub's [cache access restrictions](https://docs.github.com/en/actions/advanced-guides/caching-dependencies-to-speed-up-workflows#restrictions-for-accessing-a-cache){:target="blank" rel="noopener" class=""}, GitHub's [cache access restrictions](https://docs.github.com/en/actions/advanced-guides/caching-dependencies-to-speed-up-workflows#restrictions-for-accessing-a-cache),
still apply. Only the cache for the current branch, the base branch and the still apply. Only the cache for the current branch, the base branch and the
default branch is accessible by a workflow. default branch is accessible by a workflow.
### Using `docker/build-push-action` ### Using `docker/build-push-action`
When using the When using the
[`docker/build-push-action`](https://github.com/docker/build-push-action){:target="blank" rel="noopener" class=""}, the [`docker/build-push-action`](https://github.com/docker/build-push-action), the
`url` and `token` parameters are automatically populated. No need to manually `url` and `token` parameters are automatically populated. No need to manually
specify them, or include any additional workarounds. specify them, or include any additional workarounds.
@ -110,7 +110,7 @@ For example:
For an introduction to caching see [Optimizing builds with cache](../index.md). For an introduction to caching see [Optimizing builds with cache](../index.md).
For more information on the `gha` cache backend, see the For more information on the `gha` cache backend, see the
[BuildKit README](https://github.com/moby/buildkit#github-actions-cache-experimental){:target="blank" rel="noopener" class=""}. [BuildKit README](https://github.com/moby/buildkit#github-actions-cache-experimental).
For more information about using GitHub Actions with Docker, see For more information about using GitHub Actions with Docker, see
[Introduction to GitHub Actions](../../ci/github-actions/index.md) [Introduction to GitHub Actions](../../ci/github-actions/index.md)

8
content/build/cache/backends/inline.md vendored
View File

@ -1,8 +1,8 @@
--- ---
title: "Inline cache" title: Inline cache
keywords: build, buildx, cache, backend, inline keywords: build, buildx, cache, backend, inline
redirect_from: aliases:
- /build/building/cache/backends/inline/ - /build/building/cache/backends/inline/
--- ---
The `inline` cache storage backend is the simplest way to get an external cache The `inline` cache storage backend is the simplest way to get an external cache
@ -56,4 +56,4 @@ $ docker buildx build --push -t <registry>/<image> \
For an introduction to caching see [Optimizing builds with cache](../index.md). For an introduction to caching see [Optimizing builds with cache](../index.md).
For more information on the `inline` cache backend, see the For more information on the `inline` cache backend, see the
[BuildKit README](https://github.com/moby/buildkit#inline-push-image-and-cache-together){:target="blank" rel="noopener" class=""}. [BuildKit README](https://github.com/moby/buildkit#inline-push-image-and-cache-together).

12
content/build/cache/backends/local.md vendored
View File

@ -1,13 +1,13 @@
--- ---
title: "Local cache" title: Local cache
keywords: build, buildx, cache, backend, local keywords: build, buildx, cache, backend, local
redirect_from: aliases:
- /build/building/cache/backends/local/ - /build/building/cache/backends/local/
--- ---
The `local` cache store is a simple cache option that stores your cache as files The `local` cache store is a simple cache option that stores your cache as files
in a directory on your filesystem, using an in a directory on your filesystem, using an
[OCI image layout](https://github.com/opencontainers/image-spec/blob/main/image-layout.md){:target="blank" rel="noopener" class=""} [OCI image layout](https://github.com/opencontainers/image-spec/blob/main/image-layout.md)
for the underlying directory structure. Local cache is a good choice if you're for the underlying directory structure. Local cache is a good choice if you're
just testing, or if you want the flexibility to self-manage a shared storage just testing, or if you want the flexibility to self-manage a shared storage
solution. solution.
@ -76,7 +76,7 @@ Like other cache types, local cache gets replaced on export, by replacing the
contents of the `index.json` file. However, previous caches will still be contents of the `index.json` file. However, previous caches will still be
available in the `blobs` directory. These old caches are addressable by digest, available in the `blobs` directory. These old caches are addressable by digest,
and kept indefinitely. Therefore, the size of the local cache will continue to and kept indefinitely. Therefore, the size of the local cache will continue to
grow (see [`moby/buildkit#1896`](https://github.com/moby/buildkit/issues/1896){:target="blank" rel="noopener" class=""} grow (see [`moby/buildkit#1896`](https://github.com/moby/buildkit/issues/1896)
for more information). for more information).
When importing cache using `--cache-to`, you can specify the `digest` parameter When importing cache using `--cache-to`, you can specify the `digest` parameter
@ -93,4 +93,4 @@ $ docker buildx build --push -t <registry>/<image> \
For an introduction to caching see [Optimizing builds with cache](../index.md). For an introduction to caching see [Optimizing builds with cache](../index.md).
For more information on the `local` cache backend, see the For more information on the `local` cache backend, see the
[BuildKit README](https://github.com/moby/buildkit#local-directory-1){:target="blank" rel="noopener" class=""}. [BuildKit README](https://github.com/moby/buildkit#local-directory-1).

8
content/build/cache/backends/registry.md vendored
View File

@ -1,8 +1,8 @@
--- ---
title: "Registry cache" title: Registry cache
keywords: build, buildx, cache, backend, registry keywords: build, buildx, cache, backend, registry
redirect_from: aliases:
- /build/building/cache/backends/registry/ - /build/building/cache/backends/registry/
--- ---
The `registry` cache storage can be thought of as an extension to the `inline` The `registry` cache storage can be thought of as an extension to the `inline`
@ -72,4 +72,4 @@ fail, but the build will continue.
For an introduction to caching see [Optimizing builds with cache](../index.md). For an introduction to caching see [Optimizing builds with cache](../index.md).
For more information on the `registry` cache backend, see the For more information on the `registry` cache backend, see the
[BuildKit README](https://github.com/moby/buildkit#registry-push-image-and-cache-separately){:target="blank" rel="noopener" class=""}. [BuildKit README](https://github.com/moby/buildkit#registry-push-image-and-cache-separately).

12
content/build/cache/backends/s3.md vendored
View File

@ -1,8 +1,8 @@
--- ---
title: "Amazon S3 cache" title: Amazon S3 cache
keywords: build, buildx, cache, backend, s3 keywords: build, buildx, cache, backend, s3
redirect_from: aliases:
- /build/building/cache/backends/s3/ - /build/building/cache/backends/s3/
--- ---
> **Warning** > **Warning**
@ -11,7 +11,7 @@ redirect_from:
> `moby/buildkit:master` image in your Buildx driver. > `moby/buildkit:master` image in your Buildx driver.
The `s3` cache storage uploads your resulting build cache to The `s3` cache storage uploads your resulting build cache to
[Amazon S3 file storage service](https://aws.amazon.com/s3/){:target="blank" rel="noopener" class=""}, [Amazon S3 file storage service](https://aws.amazon.com/s3/),
into a specified bucket. into a specified bucket.
> **Note** > **Note**
@ -54,7 +54,7 @@ The following table describes the available CSV parameters that you can pass to
`access_key_id`, `secret_access_key`, and `session_token`, if left unspecified, `access_key_id`, `secret_access_key`, and `session_token`, if left unspecified,
are read from environment variables on the BuildKit server following the scheme are read from environment variables on the BuildKit server following the scheme
for the [AWS Go SDK](https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html){:target="blank" rel="noopener" class=""}. for the [AWS Go SDK](https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html).
The environment variables are read from the server, not the Buildx client. The environment variables are read from the server, not the Buildx client.
<!-- FIXME: update once https://github.com/docker/buildx/pull/1294 is released --> <!-- FIXME: update once https://github.com/docker/buildx/pull/1294 is released -->
@ -64,4 +64,4 @@ The environment variables are read from the server, not the Buildx client.
For an introduction to caching see [Optimizing builds with cache](../index.md). For an introduction to caching see [Optimizing builds with cache](../index.md).
For more information on the `s3` cache backend, see the For more information on the `s3` cache backend, see the
[BuildKit README](https://github.com/moby/buildkit#s3-cache-experimental){:target="blank" rel="noopener" class=""}. [BuildKit README](https://github.com/moby/buildkit#s3-cache-experimental).

6
content/build/cache/garbage-collection.md vendored
View File

@ -1,8 +1,8 @@
--- ---
title: Garbage collection title: Garbage collection
keywords: build, buildx, buildkit, garbage collection, prune keywords: build, buildx, buildkit, garbage collection, prune
redirect_from: aliases:
- /build/building/cache/garbage-collection/ - /build/building/cache/garbage-collection/
--- ---
While [`docker builder prune`](../../engine/reference/commandline/builder_prune.md) While [`docker builder prune`](../../engine/reference/commandline/builder_prune.md)
@ -89,4 +89,4 @@ GC Policy rule#3:
> **Note** > **Note**
> >
> "Keep bytes" defaults to 10% of the size of the disk. If the disk size cannot > "Keep bytes" defaults to 10% of the size of the disk. If the disk size cannot
> be determined, it defaults to 2GB. > be determined, it defaults to 2GB.

18
content/build/ci/_index.md
View File

@ -1,9 +1,9 @@
--- ---
description: Overview of using Docker for continuous integration description: Overview of using Docker for continuous integration
keywords: ci, build keywords: ci, build
redirect_from:
- /ci-cd/best-practices/
title: Continuous integration with Docker title: Continuous integration with Docker
aliases:
- /ci-cd/best-practices/
--- ---
Continuous Integration (CI) is the part of the development process where you're Continuous Integration (CI) is the part of the development process where you're
@ -11,7 +11,7 @@ looking to get your code changes merged with the main branch of the project. At
this point, development teams run tests and builds to vet that the code changes this point, development teams run tests and builds to vet that the code changes
don't cause any unwanted or unexpected behaviors. don't cause any unwanted or unexpected behaviors.
![Git branches about to get merged](./images/continuous-integration.svg){: .invertible } ![Git branches about to get merged](./images/continuous-integration.svg)
There are several uses for Docker at this stage of development, even if you There are several uses for Docker at this stage of development, even if you
don't end up packaging your application as a container image. don't end up packaging your application as a container image.
@ -36,10 +36,10 @@ image, just like you would for any other containerized application.
The following links provide instructions for how you can get started using The following links provide instructions for how you can get started using
Docker for building your applications in CI: Docker for building your applications in CI:
- [GitHub Actions](https://docs.github.com/en/actions/creating-actions/creating-a-docker-container-action){:target="blank" rel="noopener" class=""} - [GitHub Actions](https://docs.github.com/en/actions/creating-actions/creating-a-docker-container-action)
- [GitLab](https://docs.gitlab.com/runner/executors/docker.html){:target="blank" rel="noopener" class=""} - [GitLab](https://docs.gitlab.com/runner/executors/docker.html)
- [Circle CI](https://circleci.com/docs/using-docker/){:target="blank" rel="noopener" class=""} - [Circle CI](https://circleci.com/docs/using-docker/)
- [Render](https://render.com/docs/docker){:target="blank" rel="noopener" class=""} - [Render](https://render.com/docs/docker)
### Docker in Docker ### Docker in Docker
@ -47,7 +47,7 @@ You can also use a Dockerized build environment to build container images using
Docker. That is, your build environment runs inside a container which itself is Docker. That is, your build environment runs inside a container which itself is
equipped to run Docker builds. This method is referred to as "Docker in Docker". equipped to run Docker builds. This method is referred to as "Docker in Docker".
Docker provides an official [Docker image](https://hub.docker.com/_/docker){:target="blank" rel="noopener" class=""} Docker provides an official [Docker image](https://hub.docker.com/_/docker)
that you can use for this purpose. that you can use for this purpose.
## What's next ## What's next
@ -55,4 +55,4 @@ that you can use for this purpose.
Docker maintains a set of official GitHub Actions that you can use to build, Docker maintains a set of official GitHub Actions that you can use to build,
annotate, and push container images on the GitHub Actions platform. See annotate, and push container images on the GitHub Actions platform. See
[Introduction to GitHub Actions](./github-actions/index.md) to learn more and [Introduction to GitHub Actions](./github-actions/index.md) to learn more and
get started. get started.

30
content/build/ci/github-actions/_index.md
View File

@ -1,11 +1,13 @@
--- ---
title: Introduction to GitHub Actions title: Introduction to GitHub Actions
description: > description: 'Docker maintains a set of official GitHub Actions for building Docker
Docker maintains a set of official GitHub Actions for building Docker images. images.
'
keywords: ci, github actions, gha, build, introduction, tutorial keywords: ci, github actions, gha, build, introduction, tutorial
redirect_from: aliases:
- /ci-cd/github-actions/ - /ci-cd/github-actions/
- /build/ci/github-actions/examples/ - /build/ci/github-actions/examples/
--- ---
GitHub Actions is a popular CI/CD platform for automating your build, test, and GitHub Actions is a popular CI/CD platform for automating your build, test, and
@ -15,20 +17,20 @@ components for building, annotating, and pushing images.
The following GitHub Actions are available: The following GitHub Actions are available:
- [Build and push Docker images](https://github.com/marketplace/actions/build-and-push-docker-images){:target="blank" rel="noopener" class=""}: - [Build and push Docker images](https://github.com/marketplace/actions/build-and-push-docker-images):
build and push Docker images with BuildKit. build and push Docker images with BuildKit.
- [Docker Login](https://github.com/marketplace/actions/docker-login){:target="blank" rel="noopener" class=""}: - [Docker Login](https://github.com/marketplace/actions/docker-login):
sign in to a Docker registry. sign in to a Docker registry.
- [Docker Setup Buildx](https://github.com/marketplace/actions/docker-setup-buildx){:target="blank" rel="noopener" class=""}: - [Docker Setup Buildx](https://github.com/marketplace/actions/docker-setup-buildx):
initiates a BuildKit builder. initiates a BuildKit builder.
- [Docker Metadata action](https://github.com/marketplace/actions/docker-metadata-action){:target="blank" rel="noopener" class=""}: - [Docker Metadata action](https://github.com/marketplace/actions/docker-metadata-action):
extracts metadata from Git reference and GitHub events. extracts metadata from Git reference and GitHub events.
- [Docker Setup QEMU](https://github.com/marketplace/actions/docker-setup-qemu){:target="blank" rel="noopener" class=""}: - [Docker Setup QEMU](https://github.com/marketplace/actions/docker-setup-qemu):
installs [QEMU](https://github.com/qemu/qemu) static binaries for multi-arch installs [QEMU](https://github.com/qemu/qemu) static binaries for multi-arch
builds. builds.
- [Docker Buildx Bake](https://github.com/marketplace/actions/docker-buildx-bake){:target="blank" rel="noopener" class=""}: - [Docker Buildx Bake](https://github.com/marketplace/actions/docker-buildx-bake):
enables using high-level builds with [Bake](../../bake/index.md). enables using high-level builds with [Bake](../../bake/index.md).
- [Docker Scout](https://github.com/docker/scout-action){:target="blank" rel="noopener" class=""}: - [Docker Scout](https://github.com/docker/scout-action):
analyze Docker images for security vulnerabilities. analyze Docker images for security vulnerabilities.
Using Docker's actions provides an easy-to-use interface, while still allowing Using Docker's actions provides an easy-to-use interface, while still allowing
@ -56,7 +58,7 @@ refer to the following sections:
## Get started with GitHub Actions ## Get started with GitHub Actions
{% include gha-tutorial.md %} {{< include "gha-tutorial.md" >}}
## Next steps ## Next steps
@ -66,4 +68,4 @@ using the official Docker actions, to build and push an image to Docker Hub.
There are many more things you can do to customize your workflow to better suit There are many more things you can do to customize your workflow to better suit
your needs. To learn more about some of the more advanced use cases, take a look your needs. To learn more about some of the more advanced use cases, take a look
at the advanced examples, such as [building multi-platform images](multi-platform.md), at the advanced examples, such as [building multi-platform images](multi-platform.md),
or [using cache storage backends](cache.md) and also how to [configure your builder](configure-builder.md). or [using cache storage backends](cache.md) and also how to [configure your builder](configure-builder.md).

33
content/build/ci/github-actions/cache.md
View File

@ -18,7 +18,7 @@ However, note that the `inline` cache exporter only supports `min` cache mode.
To use `max` cache mode, push the image and the cache separately using the To use `max` cache mode, push the image and the cache separately using the
registry cache exporter with the `cache-to` option, as shown in the [registry cache example](#registry-cache). registry cache exporter with the `cache-to` option, as shown in the [registry cache example](#registry-cache).
{% raw %}
```yaml ```yaml
name: ci name: ci
@ -53,14 +53,14 @@ jobs:
cache-from: type=registry,ref=user/app:latest cache-from: type=registry,ref=user/app:latest
cache-to: type=inline cache-to: type=inline
``` ```
{% endraw %}
## Registry cache ## Registry cache
You can import/export cache from a cache manifest or (special) image You can import/export cache from a cache manifest or (special) image
configuration on the registry with the [registry cache exporter](../../cache/backends/registry.md). configuration on the registry with the [registry cache exporter](../../cache/backends/registry.md).
{% raw %}
```yaml ```yaml
name: ci name: ci
@ -95,7 +95,7 @@ jobs:
cache-from: type=registry,ref=user/app:buildcache cache-from: type=registry,ref=user/app:buildcache
cache-to: type=registry,ref=user/app:buildcache,mode=max cache-to: type=registry,ref=user/app:buildcache,mode=max
``` ```
{% endraw %}
## GitHub cache ## GitHub cache
@ -103,9 +103,9 @@ jobs:
> Experimental > Experimental
> >
> This cache exporter is experimental. Please provide feedback on [BuildKit repository](https://github.com/moby/buildkit){:target="blank" rel="noopener" class=""} > This cache exporter is experimental. Please provide feedback on [BuildKit repository](https://github.com/moby/buildkit)
> if you experience any issues. > if you experience any issues.
{: .experimental } { .experimental }
The [GitHub Actions cache exporter](../../cache/backends/gha.md) The [GitHub Actions cache exporter](../../cache/backends/gha.md)
backend uses the [GitHub Cache API](https://github.com/tonistiigi/go-actions-cache/blob/master/api.md) backend uses the [GitHub Cache API](https://github.com/tonistiigi/go-actions-cache/blob/master/api.md)
@ -114,7 +114,7 @@ backend in a GitHub Action workflow, as the `url` (`$ACTIONS_CACHE_URL`) and
`token` (`$ACTIONS_RUNTIME_TOKEN`) attributes only get populated in a workflow `token` (`$ACTIONS_RUNTIME_TOKEN`) attributes only get populated in a workflow
context. context.
{% raw %}
```yaml ```yaml
name: ci name: ci
@ -149,7 +149,7 @@ jobs:
cache-from: type=gha cache-from: type=gha
cache-to: type=gha,mode=max cache-to: type=gha,mode=max
``` ```
{% endraw %}
### Cache mounts ### Cache mounts
@ -165,7 +165,7 @@ cache mount data with your Docker build steps.
The following example shows how to use this workaround with a Go project. The following example shows how to use this workaround with a Go project.
{% raw %}
```yaml ```yaml
name: ci name: ci
on: push on: push
@ -223,7 +223,7 @@ jobs:
with: with:
cache-source: go-build-cache cache-source: go-build-cache
``` ```
{% endraw %}
For more information about this workaround, refer to the For more information about this workaround, refer to the
[GitHub repository](https://github.com/overmindtech/buildkit-cache-dance). [GitHub repository](https://github.com/overmindtech/buildkit-cache-dance).
@ -232,16 +232,16 @@ For more information about this workaround, refer to the
> **Warning** > **Warning**
> >
> At the moment, old cache entries aren't deleted, so the cache size [keeps growing](https://github.com/docker/build-push-action/issues/252){:target="blank" rel="noopener" class=""}. > At the moment, old cache entries aren't deleted, so the cache size [keeps growing](https://github.com/docker/build-push-action/issues/252).
> The following example uses the `Move cache` step as a workaround (see [`moby/buildkit#1896`](https://github.com/moby/buildkit/issues/1896){:target="blank" rel="noopener" class=""} > The following example uses the `Move cache` step as a workaround (see [`moby/buildkit#1896`](https://github.com/moby/buildkit/issues/1896)
> for more info). > for more info).
{: .warning } { .warning }
You can also leverage [GitHub cache](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows){:target="blank" rel="noopener" class=""} You can also leverage [GitHub cache](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows)
using the [actions/cache](https://github.com/actions/cache) and [local cache exporter](../../cache/backends/local.md) using the [actions/cache](https://github.com/actions/cache) and [local cache exporter](../../cache/backends/local.md)
with this action: with this action:
{% raw %}
```yaml ```yaml
name: ci name: ci
@ -291,5 +291,4 @@ jobs:
run: | run: |
rm -rf /tmp/.buildx-cache rm -rf /tmp/.buildx-cache
mv /tmp/.buildx-cache-new /tmp/.buildx-cache mv /tmp/.buildx-cache-new /tmp/.buildx-cache
``` ```
{% endraw %}

27
content/build/ci/github-actions/configure-builder.md
View File

@ -5,13 +5,13 @@ keywords: ci, github actions, gha, buildkit, buildx
--- ---
This page contains instructions on configuring your BuildKit instances when This page contains instructions on configuring your BuildKit instances when
using our [Setup Buildx Action](https://github.com/docker/setup-buildx-action){:target="blank" rel="noopener" class=""}. using our [Setup Buildx Action](https://github.com/docker/setup-buildx-action).
## Version pinning ## Version pinning
By default, the action will attempt to use the latest version of [Buildx](https://github.com/docker/buildx){:target="blank" rel="noopener" class=""} By default, the action will attempt to use the latest version of [Buildx](https://github.com/docker/buildx)
available on the GitHub Runner (the build client) and the latest release of available on the GitHub Runner (the build client) and the latest release of
[BuildKit](https://github.com/moby/buildkit){:target="blank" rel="noopener" class=""} (the build server). [BuildKit](https://github.com/moby/buildkit) (the build server).
To pin to a specific version of Buildx, use the `version` input. For example, To pin to a specific version of Buildx, use the `version` input. For example,
to pin to Buildx v0.10.0: to pin to Buildx v0.10.0:
@ -36,8 +36,8 @@ To pin to a specific version of BuildKit, use the `image` option in the
## BuildKit container logs ## BuildKit container logs
To display BuildKit container logs when using the `docker-container` driver, To display BuildKit container logs when using the `docker-container` driver,
you must either [enable step debug logging](https://docs.github.com/en/actions/monitoring-and-troubleshooting-workflows/enabling-debug-logging#enabling-step-debug-logging){:target="blank" rel="noopener" class=""}, you must either [enable step debug logging](https://docs.github.com/en/actions/monitoring-and-troubleshooting-workflows/enabling-debug-logging#enabling-step-debug-logging),
or set the `--debug` buildkitd flag in the [Docker Setup Buildx](https://github.com/marketplace/actions/docker-setup-buildx){:target="blank" rel="noopener" class=""} action: or set the `--debug` buildkitd flag in the [Docker Setup Buildx](https://github.com/marketplace/actions/docker-setup-buildx) action:
```yaml ```yaml
name: ci name: ci
@ -162,7 +162,7 @@ fields:
Here is an example using remote nodes with the [`remote` driver](../../drivers/remote.md) Here is an example using remote nodes with the [`remote` driver](../../drivers/remote.md)
and [TLS authentication](#tls-authentication): and [TLS authentication](#tls-authentication):
{% raw %}
```yaml ```yaml
name: ci name: ci
@ -195,7 +195,7 @@ jobs:
BUILDER_NODE_2_AUTH_TLS_CERT: ${{ secrets.LINUXONE_CERT }} BUILDER_NODE_2_AUTH_TLS_CERT: ${{ secrets.LINUXONE_CERT }}
BUILDER_NODE_2_AUTH_TLS_KEY: ${{ secrets.LINUXONE_KEY }} BUILDER_NODE_2_AUTH_TLS_KEY: ${{ secrets.LINUXONE_KEY }}
``` ```
{% endraw %}
## Authentication for remote builders ## Authentication for remote builders
@ -207,7 +207,7 @@ using SSH or TLS.
To be able to connect to an SSH endpoint using the [`docker-container` driver](../../drivers/docker-container.md), To be able to connect to an SSH endpoint using the [`docker-container` driver](../../drivers/docker-container.md),
you have to set up the SSH private key and configuration on the GitHub Runner: you have to set up the SSH private key and configuration on the GitHub Runner:
{% raw %}
```yaml ```yaml
name: ci name: ci
@ -231,7 +231,7 @@ jobs:
with: with:
endpoint: ssh://me@graviton2 endpoint: ssh://me@graviton2
``` ```
{% endraw %}
### TLS authentication ### TLS authentication
@ -246,7 +246,7 @@ certificates for the `tcp://`:
The `<idx>` placeholder is the position of the node in the list of nodes. The `<idx>` placeholder is the position of the node in the list of nodes.
{% raw %}
```yaml ```yaml
name: ci name: ci
@ -268,7 +268,7 @@ jobs:
BUILDER_NODE_0_AUTH_TLS_CERT: ${{ secrets.GRAVITON2_CERT }} BUILDER_NODE_0_AUTH_TLS_CERT: ${{ secrets.GRAVITON2_CERT }}
BUILDER_NODE_0_AUTH_TLS_KEY: ${{ secrets.GRAVITON2_KEY }} BUILDER_NODE_0_AUTH_TLS_KEY: ${{ secrets.GRAVITON2_KEY }}
``` ```
{% endraw %}
## Standalone mode ## Standalone mode
@ -315,7 +315,7 @@ hardware.
For more information about remote builder, see [`remote` driver](../../drivers/remote.md) For more information about remote builder, see [`remote` driver](../../drivers/remote.md)
and the [append builder nodes example](#append-additional-nodes-to-the-builder). and the [append builder nodes example](#append-additional-nodes-to-the-builder).
{% raw %}
```yaml ```yaml
name: ci name: ci
@ -357,5 +357,4 @@ jobs:
builder: ${{ steps.builder2.outputs.name }} builder: ${{ steps.builder2.outputs.name }}
context: . context: .
target: mytarget2 target: mytarget2
``` ```
{% endraw %}

5
content/build/ci/github-actions/copy-image-registries.md
View File

@ -6,7 +6,7 @@ keywords: ci, github actions, gha, buildkit, buildx, registry
[Multi-platform images](../../building/multi-platform.md) built using Buildx can [Multi-platform images](../../building/multi-platform.md) built using Buildx can
be copied from one registry to another using the [`buildx imagetools create` command](../../../engine/reference/commandline/buildx_imagetools_create.md): be copied from one registry to another using the [`buildx imagetools create` command](../../../engine/reference/commandline/buildx_imagetools_create.md):
{% raw %}
```yaml ```yaml
name: ci name: ci
@ -58,5 +58,4 @@ jobs:
--tag ghcr.io/user/app:latest \ --tag ghcr.io/user/app:latest \
--tag ghcr.io/user/app:1.0.0 \ --tag ghcr.io/user/app:1.0.0 \
user/app:latest user/app:latest
``` ```
{% endraw %}

5
content/build/ci/github-actions/export-docker.md
View File

@ -6,7 +6,7 @@ keywords: ci, github actions, gha, buildkit, buildx, docker
You may want your build result to be available in the Docker client through You may want your build result to be available in the Docker client through
`docker images` to be able to use it in another step of your workflow: `docker images` to be able to use it in another step of your workflow:
{% raw %}
```yaml ```yaml
name: ci name: ci
@ -36,5 +36,4 @@ jobs:
name: Inspect name: Inspect
run: | run: |
docker image inspect myimage:latest docker image inspect myimage:latest
``` ```
{% endraw %}

7
content/build/ci/github-actions/local-registry.md
View File

@ -3,10 +3,10 @@ title: Local registry with GitHub Actions
keywords: ci, github actions, gha, buildkit, buildx, registry keywords: ci, github actions, gha, buildkit, buildx, registry
--- ---
For testing purposes you may need to create a [local registry](https://hub.docker.com/_/registry){:target="blank" rel="noopener" class=""} For testing purposes you may need to create a [local registry](https://hub.docker.com/_/registry)
to push images into: to push images into:
{% raw %}
```yaml ```yaml
name: ci name: ci
@ -46,5 +46,4 @@ jobs:
name: Inspect name: Inspect
run: | run: |
docker buildx imagetools inspect localhost:5000/name/app:latest docker buildx imagetools inspect localhost:5000/name/app:latest
``` ```
{% endraw %}

9
content/build/ci/github-actions/manage-tags-labels.md
View File

@ -3,12 +3,12 @@ title: Manage tags and labels with GitHub Actions
keywords: ci, github actions, gha, buildkit, buildx, tags, labels keywords: ci, github actions, gha, buildkit, buildx, tags, labels
--- ---
If you want an "automatic" tag management and [OCI Image Format Specification](https://github.com/opencontainers/image-spec/blob/master/annotations.md){:target="blank" rel="noopener" class=""} If you want an "automatic" tag management and [OCI Image Format Specification](https://github.com/opencontainers/image-spec/blob/master/annotations.md)
for labels, you can do it in a dedicated setup step. The following workflow for labels, you can do it in a dedicated setup step. The following workflow
will use the [Docker Metadata Action](https://github.com/docker/metadata-action){:target="blank" rel="noopener" class=""} will use the [Docker Metadata Action](https://github.com/docker/metadata-action)
to handle tags and labels based on GitHub Actions events and Git metadata: to handle tags and labels based on GitHub Actions events and Git metadata:
{% raw %}
```yaml ```yaml
name: ci name: ci
@ -78,5 +78,4 @@ jobs:
push: ${{ github.event_name != 'pull_request' }} push: ${{ github.event_name != 'pull_request' }}
tags: ${{ steps.meta.outputs.tags }} tags: ${{ steps.meta.outputs.tags }}
labels: ${{ steps.meta.outputs.labels }} labels: ${{ steps.meta.outputs.labels }}
``` ```
{% endraw %}

13
content/build/ci/github-actions/multi-platform.md
View File

@ -8,12 +8,12 @@ the `platforms` option, as shown in the following example:
> **Note** > **Note**
> >
> - For a list of available platforms, see the [Docker Setup Buildx](https://github.com/marketplace/actions/docker-setup-buildx){:target="blank" rel="noopener" class=""} > - For a list of available platforms, see the [Docker Setup Buildx](https://github.com/marketplace/actions/docker-setup-buildx)
> action. > action.
> - If you want support for more platforms, you can use QEMU with the [Docker Setup QEMU](https://github.com/docker/setup-qemu-action){:target="blank" rel="noopener" class=""} > - If you want support for more platforms, you can use QEMU with the [Docker Setup QEMU](https://github.com/docker/setup-qemu-action)
> action. > action.
{% raw %}
```yaml ```yaml
name: ci name: ci
@ -50,7 +50,7 @@ jobs:
push: true push: true
tags: user/app:latest tags: user/app:latest
``` ```
{% endraw %}
## Distribute build across multiple runners ## Distribute build across multiple runners
@ -68,7 +68,7 @@ create a manifest list and push it to Docker Hub.
This example also uses the [`metadata` action](https://github.com/docker/metadata-action) This example also uses the [`metadata` action](https://github.com/docker/metadata-action)
to set tags and labels. to set tags and labels.
{% raw %}
```yaml ```yaml
name: ci name: ci
@ -173,5 +173,4 @@ jobs:
name: Inspect image name: Inspect image
run: | run: |
docker buildx imagetools inspect ${{ env.REGISTRY_IMAGE }}:${{ steps.meta.outputs.version }} docker buildx imagetools inspect ${{ env.REGISTRY_IMAGE }}:${{ steps.meta.outputs.version }}
``` ```
{% endraw %}

12
content/build/ci/github-actions/named-contexts.md
View File

@ -20,7 +20,7 @@ FROM alpine
RUN echo "Hello World" RUN echo "Hello World"
``` ```
{% raw %}
```yaml ```yaml
name: ci name: ci
@ -48,11 +48,11 @@ jobs:
alpine=docker-image://alpine:3.16 alpine=docker-image://alpine:3.16
tags: myimage:latest tags: myimage:latest
``` ```
{% endraw %}
## Use image in subsequent steps ## Use image in subsequent steps
By default, the [Docker Setup Buildx](https://github.com/marketplace/actions/docker-setup-buildx){:target="blank" rel="noopener" class=""} By default, the [Docker Setup Buildx](https://github.com/marketplace/actions/docker-setup-buildx)
action uses `docker-container` as a build driver, so built Docker images aren't action uses `docker-container` as a build driver, so built Docker images aren't
loaded automatically. loaded automatically.
@ -64,7 +64,7 @@ FROM alpine
RUN echo "Hello World" RUN echo "Hello World"
``` ```
{% raw %}
```yaml ```yaml
name: ci name: ci
@ -102,7 +102,7 @@ jobs:
alpine=docker-image://my-base-image:latest alpine=docker-image://my-base-image:latest
tags: myimage:latest tags: myimage:latest
``` ```
{% endraw %}
## Using with a container builder ## Using with a container builder
@ -163,4 +163,4 @@ jobs:
build-contexts: | build-contexts: |
alpine=docker-image://localhost:5000/my-base-image:latest alpine=docker-image://localhost:5000/my-base-image:latest
tags: myimage:latest tags: myimage:latest
``` ```

7
content/build/ci/github-actions/push-multi-registries.md
View File

@ -3,10 +3,10 @@ title: Push to multi-registries with GitHub Actions
keywords: ci, github actions, gha, buildkit, buildx, registry keywords: ci, github actions, gha, buildkit, buildx, registry
--- ---
The following workflow will connect you to Docker Hub and [GitHub Container Registry](https://github.com/docker/login-action#github-container-registry){:target="blank" rel="noopener" class=""} The following workflow will connect you to Docker Hub and [GitHub Container Registry](https://github.com/docker/login-action#github-container-registry)
and push the image to both registries: and push the image to both registries:
{% raw %}
```yaml ```yaml
name: ci name: ci
@ -53,5 +53,4 @@ jobs:
user/app:1.0.0 user/app:1.0.0
ghcr.io/user/app:latest ghcr.io/user/app:latest
ghcr.io/user/app:1.0.0 ghcr.io/user/app:1.0.0
``` ```
{% endraw %}

14
content/build/ci/github-actions/secrets.md
View File

@ -3,7 +3,7 @@ title: Using secrets with GitHub Actions
keywords: ci, github actions, gha, buildkit, buildx, secret keywords: ci, github actions, gha, buildkit, buildx, secret
--- ---
In the following example uses and exposes the [`GITHUB_TOKEN` secret](https://docs.github.com/en/actions/security-guides/automatic-token-authentication#about-the-github_token-secret){:target="blank" rel="noopener" class=""} In the following example uses and exposes the [`GITHUB_TOKEN` secret](https://docs.github.com/en/actions/security-guides/automatic-token-authentication#about-the-github_token-secret)
as provided by GitHub in your workflow. as provided by GitHub in your workflow.
First, create a `Dockerfile` that uses the secret: First, create a `Dockerfile` that uses the secret:
@ -18,7 +18,7 @@ RUN --mount=type=secret,id=github_token \
In this example, the secret name is `github_token`. The following workflow In this example, the secret name is `github_token`. The following workflow
exposes this secret using the `secrets` input: exposes this secret using the `secrets` input:
{% raw %}
```yaml ```yaml
name: ci name: ci
@ -51,7 +51,7 @@ jobs:
"github_token=${{ secrets.GITHUB_TOKEN }}" "github_token=${{ secrets.GITHUB_TOKEN }}"
``` ```
{% endraw %}
> **Note** > **Note**
> >
@ -62,11 +62,11 @@ jobs:
> "MY_SECRET=./secret.txt" > "MY_SECRET=./secret.txt"
> ``` > ```
If you're using [GitHub secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets){:target="blank" rel="noopener" class=""} If you're using [GitHub secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets)
and need to handle multi-line value, you will need to place the key-value pair and need to handle multi-line value, you will need to place the key-value pair
between quotes: between quotes:
{% raw %}
```yaml ```yaml
secrets: | secrets: |
"MYSECRET=${{ secrets.GPG_KEY }}" "MYSECRET=${{ secrets.GPG_KEY }}"
@ -81,7 +81,7 @@ secrets: |
ccc" ccc"
"JSON_SECRET={""key1"":""value1"",""key2"":""value2""}" "JSON_SECRET={""key1"":""value1"",""key2"":""value2""}"
``` ```
{% endraw %}
| Key | Value | | Key | Value |
|------------------|-------------------------------------| |------------------|-------------------------------------|
@ -94,4 +94,4 @@ secrets: |
> **Note** > **Note**
> >
> Double escapes are needed for quote signs. > Double escapes are needed for quote signs.

13
content/build/ci/github-actions/share-image-jobs.md
View File

@ -4,13 +4,13 @@ keywords: ci, github actions, gha, buildkit, buildx
--- ---
As each job is isolated in its own runner, you can't use your built image As each job is isolated in its own runner, you can't use your built image
between jobs, except if you're using [self-hosted runners](https://docs.github.com/en/actions/hosting-your-own-runners/about-self-hosted-runners){:target="blank" rel="noopener" class=""} between jobs, except if you're using [self-hosted runners](https://docs.github.com/en/actions/hosting-your-own-runners/about-self-hosted-runners)
However, you can [pass data between jobs](https://docs.github.com/en/actions/using-workflows/storing-workflow-data-as-artifacts#passing-data-between-jobs-in-a-workflow){:target="blank" rel="noopener" class=""} However, you can [pass data between jobs](https://docs.github.com/en/actions/using-workflows/storing-workflow-data-as-artifacts#passing-data-between-jobs-in-a-workflow)
in a workflow using the [actions/upload-artifact](https://github.com/actions/upload-artifact){:target="blank" rel="noopener" class=""} in a workflow using the [actions/upload-artifact](https://github.com/actions/upload-artifact)
and [actions/download-artifact](https://github.com/actions/download-artifact){:target="blank" rel="noopener" class=""} and [actions/download-artifact](https://github.com/actions/download-artifact)
actions: actions:
{% raw %}
```yaml ```yaml
name: ci name: ci
@ -58,5 +58,4 @@ jobs:
run: | run: |
docker load --input /tmp/myimage.tar docker load --input /tmp/myimage.tar
docker image ls -a docker image ls -a
``` ```
{% endraw %}

6
content/build/ci/github-actions/test-before-push.md
View File

@ -12,7 +12,7 @@ The following workflow implements several steps to achieve this:
2. Test your image 2. Test your image
3. Multi-platform build and push the image 3. Multi-platform build and push the image
{% raw %}
```yaml ```yaml
name: ci name: ci
@ -64,11 +64,11 @@ jobs:
push: true push: true
tags: ${{ env.LATEST_TAG }} tags: ${{ env.LATEST_TAG }}
``` ```
{% endraw %}
> **Note** > **Note**
> >
> This workflow doesn't actually build the `linux/amd64` image twice. The image > This workflow doesn't actually build the `linux/amd64` image twice. The image
> is built once, and the following steps uses the internal cache for from the > is built once, and the following steps uses the internal cache for from the
> first `Build and push` step. The second `Build and push` step only builds > first `Build and push` step. The second `Build and push` step only builds
> `linux/arm64`. > `linux/arm64`.

7
content/build/ci/github-actions/update-dockerhub-desc.md
View File

@ -4,10 +4,10 @@ keywords: ci, github actions, gha, buildkit, buildx, docker hub
--- ---
You can update the Docker Hub repository description using a third party action You can update the Docker Hub repository description using a third party action
called [Docker Hub Description](https://github.com/peter-evans/dockerhub-description){:target="blank" rel="noopener" class=""} called [Docker Hub Description](https://github.com/peter-evans/dockerhub-description)
with this action: with this action:
{% raw %}
```yaml ```yaml
name: ci name: ci
@ -49,5 +49,4 @@ jobs:
username: ${{ secrets.DOCKERHUB_USERNAME }} username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }} password: ${{ secrets.DOCKERHUB_TOKEN }}
repository: user/app repository: user/app
``` ```
{% endraw %}

18
content/build/dockerfile/frontend.md
View File

@ -1,8 +1,8 @@
--- ---
title: Custom Dockerfile syntax title: Custom Dockerfile syntax
keywords: build, buildkit, dockerfile, frontend keywords: build, buildkit, dockerfile, frontend
redirect_from: aliases:
- /build/buildkit/dockerfile-frontend/ - /build/buildkit/dockerfile-frontend/
--- ---
## Dockerfile frontend ## Dockerfile frontend
@ -35,7 +35,7 @@ Custom Dockerfile implementations allow you to:
- Make sure all users are using the same implementation to build your Dockerfile - Make sure all users are using the same implementation to build your Dockerfile
- Use the latest features without updating the Docker daemon - Use the latest features without updating the Docker daemon
- Try out new features or third-party features before they are integrated in the Docker daemon - Try out new features or third-party features before they are integrated in the Docker daemon
- Use [alternative build definitions, or create your own](https://github.com/moby/buildkit#exploring-llb){:target="blank" rel="noopener" class=""} - Use [alternative build definitions, or create your own](https://github.com/moby/buildkit#exploring-llb)
> **Note** > **Note**
> >
@ -52,7 +52,7 @@ channels where new images are released: `stable` and `labs`.
### Stable channel ### Stable channel
The `stable` channel follows [semantic versioning](https://semver.org){:target="blank" rel="noopener" class=""}. The `stable` channel follows [semantic versioning](https://semver.org).
For example: For example:
- `docker/dockerfile:1` - kept updated with the latest `1.x.x` minor _and_ patch - `docker/dockerfile:1` - kept updated with the latest `1.x.x` minor _and_ patch
@ -90,14 +90,14 @@ suffix, for example:
Choose a channel that best fits your needs. If you want to benefit from Choose a channel that best fits your needs. If you want to benefit from
new features, use the `labs` channel. Images in the `labs` channel contain new features, use the `labs` channel. Images in the `labs` channel contain
all the features in the `stable` channel, plus early access features. all the features in the `stable` channel, plus early access features.
Stable features in the `labs` channel follow [semantic versioning](https://semver.org){:target="blank" rel="noopener" class=""}, Stable features in the `labs` channel follow [semantic versioning](https://semver.org),
but early access features don't, and newer releases may not be backwards but early access features don't, and newer releases may not be backwards
compatible. Pin the version to avoid having to deal with breaking changes. compatible. Pin the version to avoid having to deal with breaking changes.
## Other resources ## Other resources
For documentation on "labs" features, master builds, and nightly feature For documentation on "labs" features, master builds, and nightly feature
releases, refer to the description in [the BuildKit source repository on GitHub](https://github.com/moby/buildkit/blob/master/README.md){:target="blank" rel="noopener" class=""}. releases, refer to the description in [the BuildKit source repository on GitHub](https://github.com/moby/buildkit/blob/master/README.md).
For a full list of available images, visit the [`docker/dockerfile` repository on Docker Hub](https://hub.docker.com/r/docker/dockerfile){:target="blank" rel="noopener" class=""}, For a full list of available images, visit the [`docker/dockerfile` repository on Docker Hub](https://hub.docker.com/r/docker/dockerfile),
and the [`docker/dockerfile-upstream` repository on Docker Hub](https://hub.docker.com/r/docker/dockerfile-upstream){:target="blank" rel="noopener" class=""} and the [`docker/dockerfile-upstream` repository on Docker Hub](https://hub.docker.com/r/docker/dockerfile-upstream)
for development builds. for development builds.

52
content/build/dockerfile/release-notes.md
View File

@ -12,7 +12,7 @@ For usage, see the [Dockerfile frontend syntax](frontend.md) page.
## 1.6.0 ## 1.6.0
{% include release-date.html date="2023-06-13" %} {{< release-date date="2023-06-13" >}}
### New ### New
@ -36,7 +36,7 @@ The following features have graduated from the labs channel to stable:
## 1.5.2 ## 1.5.2
{% include release-date.html date="2023-02-14" %} {{< release-date date="2023-02-14" >}}
### Bug fixes and enhancements ### Bug fixes and enhancements
@ -46,7 +46,7 @@ The following features have graduated from the labs channel to stable:
## 1.5.1 ## 1.5.1
{% include release-date.html date="2023-01-18" %} {{< release-date date="2023-01-18" >}}
### Bug fixes and enhancements ### Bug fixes and enhancements
@ -54,9 +54,9 @@ The following features have graduated from the labs channel to stable:
## 1.5.0 (labs) ## 1.5.0 (labs)
{% include release-date.html date="2023-01-10" %} {{< release-date date="2023-01-10" >}}
{% include dockerfile-labs-channel.md %} {{< include "dockerfile-labs-channel.md" >}}
### New ### New
@ -65,7 +65,7 @@ The following features have graduated from the labs channel to stable:
## 1.5.0 ## 1.5.0
{% include release-date.html date="2023-01-10" %} {{< release-date date="2023-01-10" >}}
### New ### New
@ -86,7 +86,7 @@ The following features have graduated from the labs channel to stable:
## 1.4.3 ## 1.4.3
{% include release-date.html date="2022-08-23" %} {{< release-date date="2022-08-23" >}}
### Bug fixes and enhancements ### Bug fixes and enhancements
@ -97,7 +97,7 @@ The following features have graduated from the labs channel to stable:
## 1.4.2 ## 1.4.2
{% include release-date.html date="2022-05-06" %} {{< release-date date="2022-05-06" >}}
### Bug fixes and enhancements ### Bug fixes and enhancements
@ -106,7 +106,7 @@ The following features have graduated from the labs channel to stable:
## 1.4.1 ## 1.4.1
{% include release-date.html date="2022-04-08" %} {{< release-date date="2022-04-08" >}}
### Bug fixes and enhancements ### Bug fixes and enhancements
@ -115,7 +115,7 @@ The following features have graduated from the labs channel to stable:
## 1.4.0 ## 1.4.0
{% include release-date.html date="2022-03-09" %} {{< release-date date="2022-03-09" >}}
### New ### New
@ -140,7 +140,7 @@ The following features have graduated from the labs channel to stable:
## 1.3.1 ## 1.3.1
{% include release-date.html date="2021-10-04" %} {{< release-date date="2021-10-04" >}}
### Bug fixes and enhancements ### Bug fixes and enhancements
@ -148,9 +148,9 @@ The following features have graduated from the labs channel to stable:
## 1.3.0 (labs) ## 1.3.0 (labs)
{% include release-date.html date="2021-07-16" %} {{< release-date date="2021-07-16" >}}
{% include dockerfile-labs-channel.md %} {{< include "dockerfile-labs-channel.md" >}}
### New ### New
@ -159,7 +159,7 @@ The following features have graduated from the labs channel to stable:
## 1.3.0 ## 1.3.0
{% include release-date.html date="2021-07-16" %} {{< release-date date="2021-07-16" >}}
### New ### New
@ -179,9 +179,9 @@ The following features have graduated from the labs channel to stable:
## 1.2.1 (labs) ## 1.2.1 (labs)
{% include release-date.html date="2020-12-12" %} {{< release-date date="2020-12-12" >}}
{% include dockerfile-labs-channel.md %} {{< include "dockerfile-labs-channel.md" >}}
### Bug fixes and enhancements ### Bug fixes and enhancements
@ -191,7 +191,7 @@ The following features have graduated from the labs channel to stable:
## 1.2.1 ## 1.2.1
{% include release-date.html date="2020-12-12" %} {{< release-date date="2020-12-12" >}}
### Bug fixes and enhancements ### Bug fixes and enhancements
@ -200,9 +200,9 @@ The following features have graduated from the labs channel to stable:
## 1.2.0 (labs) ## 1.2.0 (labs)
{% include release-date.html date="2020-12-03" %} {{< release-date date="2020-12-03" >}}
{% include dockerfile-labs-channel.md %} {{< include "dockerfile-labs-channel.md" >}}
### Bug fixes and enhancements ### Bug fixes and enhancements
@ -210,7 +210,7 @@ The following features have graduated from the labs channel to stable:
## 1.2.0 ## 1.2.0
{% include release-date.html date="2020-12-03" %} {{< release-date date="2020-12-03" >}}
### New ### New
@ -229,7 +229,7 @@ The following features have graduated from the labs channel to stable:
## 1.1.7 ## 1.1.7
{% include release-date.html date="2020-04-18" %} {{< release-date date="2020-04-18" >}}
### Bug fixes and enhancements ### Bug fixes and enhancements
@ -237,9 +237,9 @@ The following features have graduated from the labs channel to stable:
## 1.1.2 (experimental) ## 1.1.2 (experimental)
{% include release-date.html date="2019-07-31" %} {{< release-date date="2019-07-31" >}}
{% include dockerfile-labs-channel.md %} {{< include "dockerfile-labs-channel.md" >}}
### Bug fixes and enhancements ### Bug fixes and enhancements
@ -251,7 +251,7 @@ The following features have graduated from the labs channel to stable:
## 1.1.2 ## 1.1.2
{% include release-date.html date="2019-07-31" %} {{< release-date date="2019-07-31" >}}
### Bug fixes and enhancements ### Bug fixes and enhancements
@ -261,7 +261,7 @@ The following features have graduated from the labs channel to stable:
## 1.1.0 ## 1.1.0
{% include release-date.html date="2019-04-27" %} {{< release-date date="2019-04-27" >}}
### New ### New
@ -275,4 +275,4 @@ The following features have graduated from the labs channel to stable:
first look for a file `<path/to/Dockerfile>.dockerignore` and if it is not first look for a file `<path/to/Dockerfile>.dockerignore` and if it is not
found `.dockerignore` file will be looked up from the root of the build found `.dockerignore` file will be looked up from the root of the build
context. This allows projects with multiple Dockerfiles to use different context. This allows projects with multiple Dockerfiles to use different
`.dockerignore` definitions `.dockerignore` definitions

12
content/build/drivers/_index.md
View File

@ -1,10 +1,10 @@
--- ---
title: "Drivers overview" title: Drivers overview
keywords: build, buildx, driver, builder, docker-container, kubernetes, remote keywords: build, buildx, driver, builder, docker-container, kubernetes, remote
redirect_from: aliases:
- /build/buildx/drivers/ - /build/buildx/drivers/
- /build/building/drivers/ - /build/building/drivers/
- /build/buildx/multiple-builders/ - /build/buildx/multiple-builders/
--- ---
Buildx drivers are configurations for how and where the BuildKit backend runs. Buildx drivers are configurations for how and where the BuildKit backend runs.
@ -39,4 +39,4 @@ use them:
- [Docker driver](./docker.md) - [Docker driver](./docker.md)
- [Docker container driver](./docker-container.md) - [Docker container driver](./docker-container.md)
- [Kubernetes driver](./kubernetes.md) - [Kubernetes driver](./kubernetes.md)
- [Remote driver](./remote.md) - [Remote driver](./remote.md)

18
content/build/drivers/docker-container.md
View File

@ -1,9 +1,9 @@
--- ---
title: "Docker container driver" title: Docker container driver
keywords: build, buildx, driver, builder, docker-container keywords: build, buildx, driver, builder, docker-container
redirect_from: aliases:
- /build/buildx/drivers/docker-container/ - /build/buildx/drivers/docker-container/
- /build/building/drivers/docker-container/ - /build/building/drivers/docker-container/
--- ---
The buildx Docker container driver allows creation of a managed and customizable The buildx Docker container driver allows creation of a managed and customizable
@ -42,7 +42,7 @@ pass to `--driver-opt`:
## Usage ## Usage
When you run a build, Buildx pulls the specified `image` (by default, When you run a build, Buildx pulls the specified `image` (by default,
[`moby/buildkit`](https://hub.docker.com/r/moby/buildkit)){:target="blank" rel="noopener" class=""}. [`moby/buildkit`](https://hub.docker.com/r/moby/buildkit)).
When the container has started, Buildx submits the build submitted to the When the container has started, Buildx submits the build submitted to the
containerized build server. containerized build server.
@ -120,7 +120,7 @@ container
## QEMU ## QEMU
The `docker-container` driver supports using [QEMU](https://www.qemu.org/){:target="blank" rel="noopener" class=""} The `docker-container` driver supports using [QEMU](https://www.qemu.org/)
(user mode) to build non-native platforms. Use the `--platform` flag to specify (user mode) to build non-native platforms. Use the `--platform` flag to specify
which architectures that you want to build for. which architectures that you want to build for.
@ -171,14 +171,14 @@ $ docker buildx inspect --bootstrap
[Inspect the builder container](../../engine/reference/commandline/inspect.md) [Inspect the builder container](../../engine/reference/commandline/inspect.md)
and see what network is being used: and see what network is being used:
{% raw %}
```console ```console
$ docker inspect buildx_buildkit_mybuilder0 --format={{.NetworkSettings.Networks}} $ docker inspect buildx_buildkit_mybuilder0 --format={{.NetworkSettings.Networks}}
map[foonet:0xc00018c0c0] map[foonet:0xc00018c0c0]
``` ```
{% endraw %}
## Further reading ## Further reading
For more information on the Docker container driver, see the For more information on the Docker container driver, see the
[buildx reference](../../engine/reference/commandline/buildx_create.md#driver). [buildx reference](../../engine/reference/commandline/buildx_create.md#driver).

10
content/build/drivers/docker.md
View File

@ -1,9 +1,9 @@
--- ---
title: "Docker driver" title: Docker driver
keywords: build, buildx, driver, builder, docker keywords: build, buildx, driver, builder, docker
redirect_from: aliases:
- /build/buildx/drivers/docker/ - /build/buildx/drivers/docker/
- /build/building/drivers/docker/ - /build/building/drivers/docker/
--- ---
The Buildx Docker driver is the default driver. It uses the BuildKit server The Buildx Docker driver is the default driver. It uses the BuildKit server
@ -33,4 +33,4 @@ If you need additional configuration and flexibility, consider using the
## Further reading ## Further reading
For more information on the Docker driver, see the For more information on the Docker driver, see the
[buildx reference](../../engine/reference/commandline/buildx_create.md#driver). [buildx reference](../../engine/reference/commandline/buildx_create.md#driver).

23
content/build/drivers/kubernetes.md
View File

@ -1,9 +1,9 @@
--- ---
title: "Kubernetes driver" title: Kubernetes driver
keywords: build, buildx, driver, builder, kubernetes keywords: build, buildx, driver, builder, kubernetes
redirect_from: aliases:
- /build/buildx/drivers/kubernetes/ - /build/buildx/drivers/kubernetes/
- /build/building/drivers/kubernetes/ - /build/building/drivers/kubernetes/
--- ---
The Buildx Kubernetes driver allows connecting your local development or CI The Buildx Kubernetes driver allows connecting your local development or CI
@ -64,7 +64,7 @@ is configurable using the following driver options:
These options allow requesting and limiting the resources available to each These options allow requesting and limiting the resources available to each
BuildKit pod according to the official Kubernetes documentation BuildKit pod according to the official Kubernetes documentation
[here](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/){:target="blank" rel="noopener" class=""}. [here](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/).
For example, to create 4 replica BuildKit pods: For example, to create 4 replica BuildKit pods:
@ -135,7 +135,7 @@ leveraging the native architecture of nodes.
### QEMU ### QEMU
Like the `docker-container` driver, the Kubernetes driver also supports using Like the `docker-container` driver, the Kubernetes driver also supports using
[QEMU](https://www.qemu.org/){:target="blank" rel="noopener" class=""} (user [QEMU](https://www.qemu.org/) (user
mode) to build images for non-native platforms. Include the `--platform` flag mode) to build images for non-native platforms. Include the `--platform` flag
and specify which platforms you want to output to. and specify which platforms you want to output to.
@ -232,8 +232,7 @@ that you want to support.
The Kubernetes driver supports rootless mode. For more information on how The Kubernetes driver supports rootless mode. For more information on how
rootless mode works, and it's requirements, see rootless mode works, and it's requirements, see
[here](https://github.com/moby/buildkit/blob/master/docs/rootless.md){:target="blank" [here](https://github.com/moby/buildkit/blob/master/docs/rootless.md).
rel="noopener" class=""}.
To turn it on in your cluster, you can use the `rootless=true` driver option: To turn it on in your cluster, you can use the `rootless=true` driver option:
@ -262,12 +261,10 @@ Prerequisites:
- You have an existing Kubernetes cluster. If you don't already have one, you - You have an existing Kubernetes cluster. If you don't already have one, you
can follow along by installing can follow along by installing
[minikube](https://minikube.sigs.k8s.io/docs/){:target="blank" rel="noopener" [minikube](https://minikube.sigs.k8s.io/docs/).
class=""}.
- The cluster you want to connect to is accessible via the `kubectl` command, - The cluster you want to connect to is accessible via the `kubectl` command,
with the `KUBECONFIG` environment variable with the `KUBECONFIG` environment variable
[set appropriately](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/#set-the-kubeconfig-environment-variable){:target="blank" [set appropriately](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/#set-the-kubeconfig-environment-variable) if necessary.
rel="noopener" class=""} if necessary.
1. Create a `buildkit` namespace. 1. Create a `buildkit` namespace.
@ -334,4 +331,4 @@ That's it! You've now built an image from a Kubernetes pod, using Buildx!
## Further reading ## Further reading
For more information on the Kubernetes driver, see the For more information on the Kubernetes driver, see the
[buildx reference](../../engine/reference/commandline/buildx_create.md#driver). [buildx reference](../../engine/reference/commandline/buildx_create.md#driver).

22
content/build/drivers/remote.md
View File

@ -1,9 +1,9 @@
--- ---
title: "Remote driver" title: Remote driver
keywords: build, buildx, driver, builder, remote keywords: build, buildx, driver, builder, remote
redirect_from: aliases:
- /build/buildx/drivers/remote/ - /build/buildx/drivers/remote/
- /build/building/drivers/remote/ - /build/building/drivers/remote/
--- ---
The Buildx remote driver allows for more complex custom build workloads, The Buildx remote driver allows for more complex custom build workloads,
@ -35,7 +35,7 @@ pass to `--driver-opt`:
This guide shows you how to create a setup with a BuildKit daemon listening on a This guide shows you how to create a setup with a BuildKit daemon listening on a
Unix socket, and have Buildx connect through it. Unix socket, and have Buildx connect through it.
1. Ensure that [BuildKit](https://github.com/moby/buildkit){:target="blank" rel="noopener" class=""} 1. Ensure that [BuildKit](https://github.com/moby/buildkit)
is installed. is installed.
For example, you can launch an instance of buildkitd with: For example, you can launch an instance of buildkitd with:
@ -44,8 +44,8 @@ Unix socket, and have Buildx connect through it.
$ sudo ./buildkitd --group $(id -gn) --addr unix://$HOME/buildkitd.sock $ sudo ./buildkitd --group $(id -gn) --addr unix://$HOME/buildkitd.sock
``` ```
Alternatively, [see here](https://github.com/moby/buildkit/blob/master/docs/rootless.md){:target="blank" rel="noopener" class=""} Alternatively, [see here](https://github.com/moby/buildkit/blob/master/docs/rootless.md)
for running buildkitd in rootless mode or [here](https://github.com/moby/buildkit/tree/master/examples/systemd){:target="blank" rel="noopener" class=""} for running buildkitd in rootless mode or [here](https://github.com/moby/buildkit/tree/master/examples/systemd)
for examples of running it as a systemd service. for examples of running it as a systemd service.
2. Check that you have a Unix socket that you can connect to. 2. Check that you have a Unix socket that you can connect to.
@ -97,7 +97,7 @@ but this is for illustration purposes.)
1. Generate certificates for BuildKit. 1. Generate certificates for BuildKit.
You can use the [create-certs.sh](https://github.com/moby/buildkit/blob/master/examples/kubernetes/create-certs.sh){:target="blank" rel="noopener" class=""} You can use the [create-certs.sh](https://github.com/moby/buildkit/blob/master/examples/kubernetes/create-certs.sh)
script as a starting point. Note that while it's possible to expose BuildKit script as a starting point. Note that while it's possible to expose BuildKit
over TCP without using TLS, it's not recommended. Doing so allows arbitrary over TCP without using TLS, it's not recommended. Doing so allows arbitrary
access to BuildKit without credentials. access to BuildKit without credentials.
@ -150,10 +150,10 @@ pods, the Buildx builder will need to be recreated from within each pod or
copied between them. copied between them.
1. Create a Kubernetes deployment of `buildkitd`, as per the instructions 1. Create a Kubernetes deployment of `buildkitd`, as per the instructions
[here](https://github.com/moby/buildkit/tree/master/examples/kubernetes){:target="blank" rel="noopener" class=""}. [here](https://github.com/moby/buildkit/tree/master/examples/kubernetes).
Following the guide, create certificates for the BuildKit daemon and client Following the guide, create certificates for the BuildKit daemon and client
using [create-certs.sh](https://github.com/moby/buildkit/blob/master/examples/kubernetes/create-certs.sh){:target="blank" rel="noopener" class=""}, using [create-certs.sh](https://github.com/moby/buildkit/blob/master/examples/kubernetes/create-certs.sh),
and create a deployment of BuildKit pods with a service that connects to and create a deployment of BuildKit pods with a service that connects to
them. them.
@ -192,4 +192,4 @@ $ docker buildx create \
--name remote-container \ --name remote-container \
--driver remote \ --driver remote \
kube-pod://buildkitd-XXXXXXXXXX-xxxxx kube-pod://buildkitd-XXXXXXXXXX-xxxxx
``` ```

23
content/build/exporters/_index.md
View File

@ -1,10 +1,11 @@
--- ---
title: "Exporters overview" title: Exporters overview
keywords: > keywords: 'build, buildx, buildkit, exporter, image, registry, local, tar, oci, docker,
build, buildx, buildkit, exporter, image, registry, local, tar, oci, docker,
cacheonly cacheonly
redirect_from:
- /build/building/exporters/ '
aliases:
- /build/building/exporters/
--- ---
Exporters save your build results to a specified output type. You specify the Exporters save your build results to a specified output type. You specify the
@ -18,10 +19,10 @@ Buildx supports the following exporters:
- `local`: exports the build root filesystem into a local directory. - `local`: exports the build root filesystem into a local directory.
- `tar`: packs the build root filesystem into a local tarball. - `tar`: packs the build root filesystem into a local tarball.
- `oci`: exports the build result to the local filesystem in the - `oci`: exports the build result to the local filesystem in the
[OCI image layout](https://github.com/opencontainers/image-spec/blob/v1.0.1/image-layout.md){:target="blank" rel="noopener" class="_"} [OCI image layout](https://github.com/opencontainers/image-spec/blob/v1.0.1/image-layout.md)
format. format.
- `docker`: exports the build result to the local filesystem in the - `docker`: exports the build result to the local filesystem in the
[Docker Image Specification v1.2.0](https://github.com/moby/moby/blob/v24.0.0/image/spec/v1.2.md){:target="blank" rel="noopener" class="_"} [Docker Image Specification v1.2.0](https://github.com/moby/moby/blob/v24.0.0/image/spec/v1.2.md)
format. format.
- `cacheonly`: doesn't export a build output, but runs the build and creates a - `cacheonly`: doesn't export a build output, but runs the build and creates a
cache. cache.
@ -184,7 +185,7 @@ WARNING: No output specified with docker-container driver.
## Multiple exporters ## Multiple exporters
You can only specify a single exporter for any given build (see You can only specify a single exporter for any given build (see
[this pull request](https://github.com/moby/buildkit/pull/2760) for details){:target="blank" rel="noopener" class="_"}. [this pull request](https://github.com/moby/buildkit/pull/2760) for details).
But you can perform multiple builds one after another to export the same content But you can perform multiple builds one after another to export the same content
twice. BuildKit caches the build, so unless any of the layers change, all twice. BuildKit caches the build, so unless any of the layers change, all
successive builds following the first are instant. successive builds following the first are instant.
@ -242,8 +243,8 @@ the previous compression algorithm.
> **Note** > **Note**
> >
> The `gzip` and `estargz` compression methods use the [`compress/gzip` package](https://pkg.go.dev/compress/gzip){: target="blank" rel="noopener" class="_" }, > The `gzip` and `estargz` compression methods use the [`compress/gzip` package](https://pkg.go.dev/compress/gzip),
> while `zstd` uses the [`github.com/klauspost/compress/zstd` package](https://github.com/klauspost/compress/tree/master/zstd){: target="blank" rel="noopener" class="_" }. > while `zstd` uses the [`github.com/klauspost/compress/zstd` package](https://github.com/klauspost/compress/tree/master/zstd).
### OCI media types ### OCI media types
@ -266,4 +267,4 @@ them:
- [Image and registry exporters](image-registry.md) - [Image and registry exporters](image-registry.md)
- [OCI and Docker exporters](oci-docker.md). - [OCI and Docker exporters](oci-docker.md).
- [Local and tar exporters](local-tar.md) - [Local and tar exporters](local-tar.md)

15
content/build/exporters/image-registry.md
View File

@ -1,9 +1,10 @@
--- ---
title: "Image and registry exporters" title: Image and registry exporters
keywords: > keywords: 'build, buildx, buildkit, exporter, image, registry
build, buildx, buildkit, exporter, image, registry
redirect_from: '
- /build/building/exporters/image-registry/ aliases:
- /build/building/exporters/image-registry/
--- ---
The `image` exporter outputs the build result into a container image format. The The `image` exporter outputs the build result into a container image format. The
@ -57,9 +58,9 @@ $ docker buildx build \
``` ```
For more information about annotations, see For more information about annotations, see
[BuildKit documentation](https://github.com/moby/buildkit/blob/master/docs/annotations.md){:target="blank" rel="noopener" class=""}. [BuildKit documentation](https://github.com/moby/buildkit/blob/master/docs/annotations.md).
## Further reading ## Further reading
For more information on the `image` or `registry` exporters, see the For more information on the `image` or `registry` exporters, see the
[BuildKit README](https://github.com/moby/buildkit/blob/master/README.md#imageregistry){:target="blank" rel="noopener" class=""}. [BuildKit README](https://github.com/moby/buildkit/blob/master/README.md#imageregistry).

13
content/build/exporters/local-tar.md
View File

@ -1,9 +1,10 @@
--- ---
title: "Local and tar exporters" title: Local and tar exporters
keywords: > keywords: 'build, buildx, buildkit, exporter, local, tar
build, buildx, buildkit, exporter, local, tar
redirect_from: '
- /build/building/exporters/local-tar/ aliases:
- /build/building/exporters/local-tar/
--- ---
The `local` and `tar` exporters output the root filesystem of the build result The `local` and `tar` exporters output the root filesystem of the build result
@ -34,4 +35,4 @@ The following table describes the available parameters:
## Further reading ## Further reading
For more information on the `local` or `tar` exporters, see the For more information on the `local` or `tar` exporters, see the
[BuildKit README](https://github.com/moby/buildkit/blob/master/README.md#local-directory){:target="blank" rel="noopener" class=""}. [BuildKit README](https://github.com/moby/buildkit/blob/master/README.md#local-directory).

17
content/build/exporters/oci-docker.md
View File

@ -1,13 +1,14 @@
--- ---
title: "OCI and Docker exporters" title: OCI and Docker exporters
keywords: > keywords: 'build, buildx, buildkit, exporter, oci, docker
build, buildx, buildkit, exporter, oci, docker
redirect_from: '
- /build/building/exporters/local-tar/ aliases:
- /build/building/exporters/local-tar/
--- ---
The `oci` exporter outputs the build result into an The `oci` exporter outputs the build result into an
[OCI image layout](https://github.com/opencontainers/image-spec/blob/main/image-layout.md){:target="blank" rel="noopener" class=""} [OCI image layout](https://github.com/opencontainers/image-spec/blob/main/image-layout.md)
tarball. The `docker` exporter behaves the same way, except it exports a Docker tarball. The `docker` exporter behaves the same way, except it exports a Docker
image layout instead. image layout instead.
@ -56,9 +57,9 @@ $ docker buildx build \
``` ```
For more information about annotations, see For more information about annotations, see
[BuildKit documentation](https://github.com/moby/buildkit/blob/master/docs/annotations.md){:target="blank" rel="noopener" class=""}. [BuildKit documentation](https://github.com/moby/buildkit/blob/master/docs/annotations.md).
## Further reading ## Further reading
For more information on the `oci` or `docker` exporters, see the For more information on the `oci` or `docker` exporters, see the
[BuildKit README](https://github.com/moby/buildkit/blob/master/README.md#docker-tarball){:target="blank" rel="noopener" class=""}. [BuildKit README](https://github.com/moby/buildkit/blob/master/README.md#docker-tarball).

2
content/build/guide/_index.md
View File

@ -31,4 +31,4 @@ workflows. You don't need to complete this entire guide from start to finish.
Follow the sections that seem relevant to you, and save the advanced sections at Follow the sections that seem relevant to you, and save the advanced sections at
the end for later, when you need them. the end for later, when you need them.
[Get started](intro.md){: .button .primary-btn } {{< button text="Get started" url="intro.md" >}}

19
content/build/guide/build-args.md
View File

@ -1,8 +1,9 @@
--- ---
title: Build arguments title: Build arguments
description: Introduction to configurable builds, using build args description: Introduction to configurable builds, using build args
keywords: > keywords: 'build, buildkit, buildx, guide, tutorial, build arguments, arg
build, buildkit, buildx, guide, tutorial, build arguments, arg
'
--- ---
{% include_relative nav.html selected="5" %} {% include_relative nav.html selected="5" %}
@ -14,7 +15,7 @@ uses as a fallback.
## Change runtime versions ## Change runtime versions
A practical use case for build arguments is to specify runtime versions for A practical use case for build arguments is to specify runtime versions for
build stages. Your image uses the `golang:{{site.example_go_version}}-alpine` build stages. Your image uses the `golang:{{% param "example_go_version" %}}-alpine`
image as a base image. image as a base image.
But what if someone wanted to use a different version of Go for building the But what if someone wanted to use a different version of Go for building the
application? They could update the version number inside the Dockerfile, but application? They could update the version number inside the Dockerfile, but
@ -23,8 +24,8 @@ has to be. Build arguments make life easier:
```diff ```diff
# syntax=docker/dockerfile:1 # syntax=docker/dockerfile:1
- FROM golang:{{site.example_go_version}}-alpine AS base - FROM golang:{{% param "example_go_version" %}}-alpine AS base
+ ARG GO_VERSION={{site.example_go_version}} + ARG GO_VERSION={{% param "example_go_version" %}}
+ FROM golang:${GO_VERSION}-alpine AS base + FROM golang:${GO_VERSION}-alpine AS base
WORKDIR /src WORKDIR /src
RUN --mount=type=cache,target=/go/pkg/mod/ \ RUN --mount=type=cache,target=/go/pkg/mod/ \
@ -52,9 +53,9 @@ has to be. Build arguments make life easier:
``` ```
The `ARG` keyword is interpolated in the image name in the `FROM` instruction. The `ARG` keyword is interpolated in the image name in the `FROM` instruction.
The default value of the `GO_VERSION` build argument is set to `{{site.example_go_version}}`. The default value of the `GO_VERSION` build argument is set to `{{% param "example_go_version" %}}`.
If the build doesn't receive a `GO_VERSION` build argument, the `FROM` instruction If the build doesn't receive a `GO_VERSION` build argument, the `FROM` instruction
resolves to `golang:{{site.example_go_version}}-alpine`. resolves to `golang:{{% param "example_go_version" %}}-alpine`.
Try setting a different version of Go to use for building, using the Try setting a different version of Go to use for building, using the
`--build-arg` flag for the build command: `--build-arg` flag for the build command:
@ -97,7 +98,7 @@ a variable in the code.
```diff ```diff
# syntax=docker/dockerfile:1 # syntax=docker/dockerfile:1
ARG GO_VERSION={{site.example_go_version}} ARG GO_VERSION={{% param "example_go_version" %}}
FROM golang:${GO_VERSION}-alpine AS base FROM golang:${GO_VERSION}-alpine AS base
WORKDIR /src WORKDIR /src
RUN --mount=type=cache,target=/go/pkg/mod/ \ RUN --mount=type=cache,target=/go/pkg/mod/ \
@ -153,4 +154,4 @@ Related information:
The next section of this guide shows how you can use Docker builds to create not The next section of this guide shows how you can use Docker builds to create not
only container images, but executable binaries as well. only container images, but executable binaries as well.
[Export binaries](export.md){: .button .primary-btn } {{< button text="Export binaries" url="export.md" >}}

9
content/build/guide/export.md
View File

@ -1,8 +1,9 @@
--- ---
title: Export binaries title: Export binaries
description: Using Docker builds to create and export executable binaries description: Using Docker builds to create and export executable binaries
keywords: > keywords: 'build, buildkit, buildx, guide, tutorial, build arguments, arg
build, buildkit, buildx, guide, tutorial, build arguments, arg
'
--- ---
{% include_relative nav.html selected="6" %} {% include_relative nav.html selected="6" %}
@ -50,7 +51,7 @@ stage:
```diff ```diff
# syntax=docker/dockerfile:1 # syntax=docker/dockerfile:1
ARG GO_VERSION={{site.example_go_version}} ARG GO_VERSION={{% param "example_go_version" %}}
FROM golang:${GO_VERSION}-alpine AS base FROM golang:${GO_VERSION}-alpine AS base
WORKDIR /src WORKDIR /src
RUN --mount=type=cache,target=/go/pkg/mod/ \ RUN --mount=type=cache,target=/go/pkg/mod/ \
@ -114,4 +115,4 @@ Related information:
The next topic of this guide is testing: how you can use Docker to run The next topic of this guide is testing: how you can use Docker to run
application tests. application tests.
[Test](test.md){: .button .primary-btn } {{< button text="Test" url="test.md" >}}

8
content/build/guide/intro.md
View File

@ -55,7 +55,7 @@ Here's the Dockerfile used as the starting point for this guide:
```dockerfile ```dockerfile
# syntax=docker/dockerfile:1 # syntax=docker/dockerfile:1
FROM golang:{{site.example_go_version}}-alpine FROM golang:{{% param "example_go_version" %}}-alpine
WORKDIR /src WORKDIR /src
COPY . . COPY . .
RUN go mod download RUN go mod download
@ -74,9 +74,9 @@ Here’s what this Dockerfile does:
the `dockerfile:1` syntax which is best practice: it ensures that you have the `dockerfile:1` syntax which is best practice: it ensures that you have
access to the latest Docker build features. access to the latest Docker build features.
2. `FROM golang:{{site.example_go_version}}-alpine` 2. `FROM golang:{{% param "example_go_version" %}}-alpine`
The `FROM` instruction uses version `{{site.example_go_version}}-alpine` of the `golang` official image. The `FROM` instruction uses version `{{% param "example_go_version" %}}-alpine` of the `golang` official image.
3. `WORKDIR /src` 3. `WORKDIR /src`
@ -169,4 +169,4 @@ Related information:
The next section explores how you can use layer cache to improve build speed. The next section explores how you can use layer cache to improve build speed.
[Layers](layers.md){: .button .primary-btn } {{< button text="Layers" url="layers.md" >}}

10
content/build/guide/layers.md
View File

@ -11,7 +11,7 @@ of ordered build instructions. Each instruction in a Dockerfile roughly translat
to an image layer. The following diagram illustrates how a Dockerfile translates to an image layer. The following diagram illustrates how a Dockerfile translates
into a stack of layers in a container image. into a stack of layers in a container image.
![From Dockerfile to layers](./images/layers.png){:.invertible} ![From Dockerfile to layers](./images/layers.png)
## Cached layers ## Cached layers
@ -25,7 +25,7 @@ following step (`RUN go mod download`). If you were to change any of the project
files, then that would invalidate the cache for the `COPY` layer. It also invalidates files, then that would invalidate the cache for the `COPY` layer. It also invalidates
the cache for all of the layers that follow. the cache for all of the layers that follow.
![Layer cache is bust](./images/cache-bust.png){:.invertible} ![Layer cache is bust](./images/cache-bust.png)
Because of the current order of the Dockerfile instructions, the builder must Because of the current order of the Dockerfile instructions, the builder must
download the Go modules again, despite none of the packages having changed since download the Go modules again, despite none of the packages having changed since
@ -47,7 +47,7 @@ For Go to know which dependencies to download, you need to copy the `go.mod` and
```diff ```diff
# syntax=docker/dockerfile:1 # syntax=docker/dockerfile:1
FROM golang:{{site.example_go_version}}-alpine FROM golang:{{% param "example_go_version" %}}-alpine
WORKDIR /src WORKDIR /src
- COPY . . - COPY . .
+ COPY go.mod go.sum . + COPY go.mod go.sum .
@ -63,7 +63,7 @@ builder to download the dependencies each time. The `COPY . .` instruction
appears after the package management instructions, so the builder can reuse the appears after the package management instructions, so the builder can reuse the
`RUN go mod download` layer. `RUN go mod download` layer.
![Reordered](./images/reordered-layers.png){:.invertible} ![Reordered](./images/reordered-layers.png)
## Summary ## Summary
@ -80,4 +80,4 @@ Related information:
The next section shows how you can make the build run faster, and make the The next section shows how you can make the build run faster, and make the
resulting output smaller, using multi-stage builds. resulting output smaller, using multi-stage builds.
[Multi-stage](multi-stage.md){: .button .primary-btn } {{< button text="Multi-stage" url="multi-stage.md" >}}

15
content/build/guide/mounts.md
View File

@ -1,8 +1,9 @@
--- ---
title: Mounts title: Mounts
description: Introduction to cache mounts and bind mounts in builds description: Introduction to cache mounts and bind mounts in builds
keywords: > keywords: 'build, buildkit, buildx, guide, tutorial, mounts, cache mounts, bind mounts
build, buildkit, buildx, guide, tutorial, mounts, cache mounts, bind mounts
'
--- ---
{% include_relative nav.html selected="4" %} {% include_relative nav.html selected="4" %}
@ -36,7 +37,7 @@ mount the `/go/pkg/mod` directory as a cache mount:
```diff ```diff
# syntax=docker/dockerfile:1 # syntax=docker/dockerfile:1
FROM golang:{{site.example_go_version}}-alpine AS base FROM golang:{{% param "example_go_version" %}}-alpine AS base
WORKDIR /src WORKDIR /src
COPY go.mod go.sum . COPY go.mod go.sum .
- RUN go mod download - RUN go mod download
@ -117,7 +118,7 @@ Update the version of the `chi` package that the server component of the
application uses: application uses:
```console ```console
$ docker run -v $PWD:$PWD -w $PWD golang:{{site.example_go_version}}-alpine \ $ docker run -v $PWD:$PWD -w $PWD golang:{{% param "example_go_version" %}}-alpine \
go get github.com/go-chi/chi/v5@v5.0.8 go get github.com/go-chi/chi/v5@v5.0.8
``` ```
@ -151,7 +152,7 @@ the need for the additional `COPY` instruction (and layer) entirely.
```diff ```diff
# syntax=docker/dockerfile:1 # syntax=docker/dockerfile:1
FROM golang:{{site.example_go_version}}-alpine AS base FROM golang:{{% param "example_go_version" %}}-alpine AS base
WORKDIR /src WORKDIR /src
- COPY go.mod go.sum . - COPY go.mod go.sum .
RUN --mount=type=cache,target=/go/pkg/mod/ \ RUN --mount=type=cache,target=/go/pkg/mod/ \
@ -183,7 +184,7 @@ Similarly, you can use the same technique to remove the need for the second
```diff ```diff
# syntax=docker/dockerfile:1 # syntax=docker/dockerfile:1
FROM golang:{{site.example_go_version}}-alpine AS base FROM golang:{{% param "example_go_version" %}}-alpine AS base
WORKDIR /src WORKDIR /src
RUN --mount=type=cache,target=/go/pkg/mod/ \ RUN --mount=type=cache,target=/go/pkg/mod/ \
--mount=type=bind,source=go.sum,target=go.sum \ --mount=type=bind,source=go.sum,target=go.sum \
@ -225,4 +226,4 @@ Related information:
The next section of this guide is an introduction to making your builds The next section of this guide is an introduction to making your builds
configurable, using build arguments. configurable, using build arguments.
[Build arguments](build-args.md){: .button .primary-btn } {{< button text="Build arguments" url="build-args.md" >}}

16
content/build/guide/multi-platform.md
View File

@ -1,9 +1,7 @@
--- ---
title: Multi-platform title: Multi-platform
description: Building for multiple operating systems and architectures description: Building for multiple operating systems and architectures
keywords: >- keywords: build, buildkit, buildx, guide, tutorial, multi-platform, emulation, cross-compilation
build, buildkit, buildx, guide, tutorial, multi-platform, emulation,
cross-compilation
--- ---
{% include_relative nav.html selected="8" %} {% include_relative nav.html selected="8" %}
@ -112,7 +110,7 @@ When you build using a builder that supports multi-platform builds, the builder
runs all of the build steps under emulation for each platform that you specify. runs all of the build steps under emulation for each platform that you specify.
Effectively forking the build into two concurrent processes. Effectively forking the build into two concurrent processes.
![Build pipelines using emulation](./images/emulation.png){:.invertible} ![Build pipelines using emulation](./images/emulation.png)
There are, however, a few downsides to running multi-platform builds using There are, however, a few downsides to running multi-platform builds using
emulation: emulation:
@ -157,7 +155,7 @@ the pre-defined platform arguments are forked automatically for each platform.
This is in contrast to builds running under emulation, where the entire build This is in contrast to builds running under emulation, where the entire build
pipeline runs per platform. pipeline runs per platform.
![Build pipelines using cross-compilation](./images/cross-compilation.png){:.invertible} ![Build pipelines using cross-compilation](./images/cross-compilation.png)
### Update the Dockerfile ### Update the Dockerfile
@ -175,8 +173,8 @@ follows:
```diff ```diff
# syntax=docker/dockerfile:1 # syntax=docker/dockerfile:1
ARG GO_VERSION={{site.example_go_version}} ARG GO_VERSION={{% param "example_go_version" %}}
ARG GOLANGCI_LINT_VERSION={{site.example_golangci_lint_version}} ARG GOLANGCI_LINT_VERSION={{% param "example_golangci_lint_version" %}}
- FROM golang:${GO_VERSION}-alpine AS base - FROM golang:${GO_VERSION}-alpine AS base
+ FROM --platform=$BUILDPLATFORM golang:${GO_VERSION}-alpine AS base + FROM --platform=$BUILDPLATFORM golang:${GO_VERSION}-alpine AS base
WORKDIR /src WORKDIR /src
@ -262,7 +260,7 @@ Related information:
- [`docker buildx create` CLI reference](../../engine/reference/commandline/buildx_create.md) - [`docker buildx create` CLI reference](../../engine/reference/commandline/buildx_create.md)
You may also want to consider checking out You may also want to consider checking out
[xx - Dockerfile cross-compilation helpers](https://github.com/tonistiigi/xx){: target="_blank" rel="noopener" }. [xx - Dockerfile cross-compilation helpers](https://github.com/tonistiigi/xx).
`xx` is a Docker image containing utility scripts that make cross-compiling with Docker builds easier. `xx` is a Docker image containing utility scripts that make cross-compiling with Docker builds easier.
## Next steps ## Next steps
@ -270,4 +268,4 @@ You may also want to consider checking out
This section is the final part of the Build with Docker guide. The following This section is the final part of the Build with Docker guide. The following
page contains some pointers for where to go next. page contains some pointers for where to go next.
[Next steps](next-steps.md){: .button .primary-btn } {{< button text="Next steps" url="next-steps.md" >}}

10
content/build/guide/multi-stage.md
View File

@ -41,7 +41,7 @@ built in the previous stage are copied over to the filesystem of the new stage.
```diff ```diff
# syntax=docker/dockerfile:1 # syntax=docker/dockerfile:1
FROM golang:{{site.example_go_version}}-alpine FROM golang:{{% param "example_go_version" %}}-alpine
WORKDIR /src WORKDIR /src
COPY go.mod go.sum . COPY go.mod go.sum .
RUN go mod download RUN go mod download
@ -90,8 +90,8 @@ to the final `scratch` image.
```diff ```diff
# syntax=docker/dockerfile:1 # syntax=docker/dockerfile:1
- FROM golang:{{site.example_go_version}}-alpine - FROM golang:{{% param "example_go_version" %}}-alpine
+ FROM golang:{{site.example_go_version}}-alpine AS base + FROM golang:{{% param "example_go_version" %}}-alpine AS base
WORKDIR /src WORKDIR /src
COPY go.mod go.sum . COPY go.mod go.sum .
RUN go mod download RUN go mod download
@ -129,7 +129,7 @@ unnamed `FROM scratch` stage with two separate stages named `client` and
```diff ```diff
# syntax=docker/dockerfile:1 # syntax=docker/dockerfile:1
FROM golang:{{site.example_go_version}}-alpine AS base FROM golang:{{% param "example_go_version" %}}-alpine AS base
WORKDIR /src WORKDIR /src
COPY go.mod go.sum . COPY go.mod go.sum .
RUN go mod download RUN go mod download
@ -190,4 +190,4 @@ Related information:
The next section describes how you can use file mounts to further improve build The next section describes how you can use file mounts to further improve build
speeds. speeds.
[Mounts](mounts.md){: .button .primary-btn } {{< button text="Mounts" url="mounts.md" >}}

4
content/build/guide/next-steps.md
View File

@ -30,5 +30,5 @@ If you don't see the feedback widget, try turning off your content filtering
extension or ad blocker, if you use one. extension or ad blocker, if you use one.
You can also submit an issue on You can also submit an issue on
[the docs GitHub repository](https://github.com/docker/docs/issues/new){: target="_blank" rel="noopener" }, [the docs GitHub repository](https://github.com/docker/docs/issues/new),
if you prefer. if you prefer.

6
content/build/guide/test.md
View File

@ -40,8 +40,8 @@ Now you can add this as a step to the Dockerfile.
```diff ```diff
# syntax=docker/dockerfile:1 # syntax=docker/dockerfile:1
ARG GO_VERSION={{site.example_go_version}} ARG GO_VERSION={{% param "example_go_version" %}}
+ ARG GOLANGCI_LINT_VERSION={{site.example_golangci_lint_version}} + ARG GOLANGCI_LINT_VERSION={{% param "example_golangci_lint_version" %}}
FROM golang:${GO_VERSION}-alpine AS base FROM golang:${GO_VERSION}-alpine AS base
WORKDIR /src WORKDIR /src
RUN --mount=type=cache,target=/go/pkg/mod/ \ RUN --mount=type=cache,target=/go/pkg/mod/ \
@ -114,4 +114,4 @@ This section has shown an example on how you can use Docker builds to run tests
The next topic in this guide is multi-platform builds, using emulation and The next topic in this guide is multi-platform builds, using emulation and
cross-compilation. cross-compilation.
[Multi-platform](multi-platform.md){: .button .primary-btn } {{< button text="Multi-platform" url="multi-platform.md" >}}

Some files were not shown because too many files have changed in this diff Show More