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
keywords: Docker, documentation, manual, guide, reference, api, samples
grid:
- title: Get started
image:
dark: /assets/images/rocket-dark.svg
light: /assets/images/rocket.svg
link: /get-started/
description: Learn Docker basics and the benefits of containerizing your applications.
- title: Download and install
image:
dark: /assets/images/download-docker-dark.svg
light: /assets/images/download-docker.svg
link: /get-docker/
description: Download and install Docker on your machine in a few easy steps.
- title: Guides
image:
dark: /assets/images/guides-dark.svg
light: /assets/images/guides.svg
link: /get-started/overview/
description: Learn how to set up your Docker environment and start containerizing your applications.
- title: Language-specific guides
image:
dark: /assets/images/language-guides-dark.svg
light: /assets/images/language-guides.svg
link: /language/
description: Learn how to use Docker with your favorite programming language.
- title: Manuals
image:
dark: /assets/images/manuals-dark.svg
light: /assets/images/manuals.svg
link: /desktop/
description: Browse the manuals and learn how to use Docker products.
- title: Reference
image:
dark: /assets/images/reference-dark.svg
light: /assets/images/reference.svg
link: /reference/
description: Browse the CLI and API reference documentation.
---
- title: Get started
image:
dark: /assets/images/rocket-dark.svg
light: /assets/images/rocket.svg
link: /get-started/
description: Learn Docker basics and the benefits of containerizing your applications.
- title: Download and install
image:
dark: /assets/images/download-docker-dark.svg
light: /assets/images/download-docker.svg
link: /get-docker/
description: Download and install Docker on your machine in a few easy steps.
- title: Guides
image:
dark: /assets/images/guides-dark.svg
light: /assets/images/guides.svg
link: /get-started/overview/
description: Learn how to set up your Docker environment and start containerizing
your applications.
- title: Language-specific guides
image:
dark: /assets/images/language-guides-dark.svg
light: /assets/images/language-guides.svg
link: /language/
description: Learn how to use Docker with your favorite programming language.
- title: Manuals
image:
dark: /assets/images/manuals-dark.svg
light: /assets/images/manuals.svg
link: /desktop/
description: Browse the manuals and learn how to use Docker products.
- title: Reference
image:
dark: /assets/images/reference-dark.svg
light: /assets/images/reference.svg
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
title: Docker Admin overview
grid:
- title: Company administration
description: Explore how to manage a company in Docker Admin.
icon: lan
link: /admin/company/
- title: Organization administration
description: Learn about organization administration in Docker Admin.
icon: contact_page
link: /admin/organization/
- title: Company administration
description: Explore how to manage a company in Docker Admin.
icon: lan
link: /admin/company/
- title: Organization administration
description: Learn about organization administration in Docker Admin.
icon: contact_page
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 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.
- 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
title: Overview
grid:
- title: Manage organizations
description: Learn how to add and manage organizations as well as seats within your company.
icon: note_add
link: /admin/company/organizations/
- title: Manage users
description: Explore how to manage users in all organizations.
icon: contact_page
link: /admin/company/users/
- title: Manage company owners
description: Find out more about company owners and how to manage them.
icon: group_add
link: /admin/company/owners/
- title: Configure Single Sign-On
description: Discover how to configure SSO for your entire company.
icon: key
link: /admin/company/settings/sso/
- title: Set up SCIM
description: Set up SCIM to automatically provision and deprovision users in your company.
icon: checklist
link: /admin/company/settings/scim/
- title: Domain management
description: Add and verify your domains.
icon: security
link: /admin/company/settings/domains/
- title: Manage organizations
description: Learn how to add and manage organizations as well as seats within your
company.
icon: note_add
link: /admin/company/organizations/
- title: Manage users
description: Explore how to manage users in all organizations.
icon: contact_page
link: /admin/company/users/
- title: Manage company owners
description: Find out more about company owners and how to manage them.
icon: group_add
link: /admin/company/owners/
- title: Configure Single Sign-On
description: Discover how to configure SSO for your entire company.
icon: key
link: /admin/company/settings/sso/
- title: Set up SCIM
description: Set up SCIM to automatically provision and deprovision users in your
company.
icon: checklist
link: /admin/company/settings/scim/
- title: Domain management
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
[Create a company](../organization/general-settings.md#create-a-company).
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
title: Manage organizations
---
{% include admin-early-access.md %}
{{< include "admin-early-access.md" >}}
## 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.
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.
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.
3. Under **Organizations**, select **Overview**.
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.
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.
3. Select **Add organization**.
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
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.
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
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.
## 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.
3. Select **Company Owners**.
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
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.
3. Select **Company Owners**.
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
---
{% include admin-early-access.md %}
{{< include "admin-early-access.md" >}}
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
---
{% 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
---
{% 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/).

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
---
{% 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/).

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
---
{% 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/).
## Manage organizations
{% include admin-sso-management-orgs.md product="admin" %}
{% include admin-sso-management.md product="admin" layer="company"%}
{{% admin-sso-management-orgs product="admin" %}}
{% 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
---
{% 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
---
{% 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

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

@ -3,44 +3,44 @@ description: Learn about organizations.
keywords: organizations, admin, overview
title: Organization administration overview
grid:
- title: Manage members
description: Explore how to manage members.
icon: contact_page
link: /admin/organization/members/
- title: Activity logs
description: Learn how to audit the activities of your members.
icon: feed
link: /admin/organization/activity-logs/
- title: Image Access Management
description: Control which types of images your developers can pull.
icon: dynamic_feed
link: /admin/organization/image-access/
- title: Registry Access Management
description: Define which registries your developers can access.
icon: all_inbox
link: /admin/organization/registry-access/
- title: General settings
description: Configure general information or create a company.
icon: settings_suggest
link: /admin/organization/general-settings/
- title: SSO & SCIM
description: >
Set up [Single Sign-On](/admin/organization/security-settings/sso/) and
[SCIM](/admin/organization/security-settings/scim/) for your organization.
icon: key
- title: Domain management
description: Add, verify, and audit your domains.
link: /admin/organization/security-settings/domains/
icon: security
- title: Manage members
description: Explore how to manage members.
icon: contact_page
link: /admin/organization/members/
- title: Activity logs
description: Learn how to audit the activities of your members.
icon: feed
link: /admin/organization/activity-logs/
- title: Image Access Management
description: Control which types of images your developers can pull.
icon: dynamic_feed
link: /admin/organization/image-access/
- title: Registry Access Management
description: Define which registries your developers can access.
icon: all_inbox
link: /admin/organization/registry-access/
- title: General settings
description: Configure general information or create a company.
icon: settings_suggest
link: /admin/organization/general-settings/
- title: SSO & SCIM
description: 'Set up [Single Sign-On](/admin/organization/security-settings/sso/)
and [SCIM](/admin/organization/security-settings/scim/) for your organization.
'
icon: key
- title: Domain management
description: Add, verify, and audit your domains.
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).
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
---
{% 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
---
{% include admin-early-access.md %}
{{< include "admin-early-access.md" >}}
## Configure general information
@ -19,7 +19,7 @@ This information includes:
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.
3. Under **Organization Settings**, select **General**.
4. Specify the organization information and select **Save**.
@ -28,7 +28,7 @@ To edit this information:
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.
3. Under **Organization Settings**, select **General**.
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
---
{% 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
---
{% 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
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
---
{% 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
---
{% 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
---
{% 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.
@ -14,4 +14,4 @@ Use domain management to manage your domains for Single Sign-On and SCIM, as wel
## 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
---
{% 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
---
{% 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/).

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
---
{% 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/).

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

@ -5,6 +5,6 @@ title: Single Sign-On FAQs
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
---
{% 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/).

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
---
{% 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.
{{< 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**.
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**.
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.
3. Select the **Billing** tab and then **Payment Methods**.
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?
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?
@ -88,4 +88,4 @@ For organizations:
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.
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:
- 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.
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.
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
---
{% 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.
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
@ -36,7 +36,7 @@ Once your purchase is complete, you receive a confirmation email and a copy of y
>**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.
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.
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
description: Introduction and overview of Docker Build
keywords: build, buildx, buildkit
redirect_from:
- /buildx/working-with-buildx/
- /develop/develop-images/build_enhancements/
grid:
- title: "Packaging your software"
description:
"Build and package your application to run it anywhere: locally or in the
cloud."
icon: "inventory_2"
link: "/build/building/packaging"
- title: "Multi-stage builds"
description: "Keep your images small and secure with minimal dependencies."
icon: "stairs"
link: "/build/building/multi-stage"
- title: "Multi-platform images"
description:
"Build, push, pull, and run images seamlessly on different computer
architectures."
icon: "home_storage"
link: "/build/building/multi-platform/"
- title: "Architecture"
description: "Learn about the Docker Build components."
icon: "explore"
description: "Explore BuildKit, the open source build engine."
icon: "construction"
link: "/build/buildkit/"
- title: "Build drivers"
description: "Configure where and how you run your builds."
icon: "engineering"
link: "/build/drivers/"
- title: "Exporters"
description: "Export any artifact you like, not just Docker images."
icon: "output"
link: "/build/exporters"
- title: "Build caching"
description:
"Avoid unnecessary repetitions of costly operations, such as package
installs."
icon: "cycle"
link: "/build/cache"
- title: "Bake"
description: "Orchestrate your builds with Bake."
icon: "cake"
link: "/build/bake"
- title: Packaging your software
description: 'Build and package your application to run it anywhere: locally or
in the cloud.'
icon: inventory_2
link: /build/building/packaging
- title: Multi-stage builds
description: Keep your images small and secure with minimal dependencies.
icon: stairs
link: /build/building/multi-stage
- title: Multi-platform images
description: Build, push, pull, and run images seamlessly on different computer
architectures.
icon: home_storage
link: /build/building/multi-platform/
- title: Architecture
description: Explore BuildKit, the open source build engine.
icon: construction
link: /build/buildkit/
- title: Build drivers
description: Configure where and how you run your builds.
icon: engineering
link: /build/drivers/
- title: Exporters
description: Export any artifact you like, not just Docker images.
icon: output
link: /build/exporters
- title: Build caching
description: Avoid unnecessary repetitions of costly operations, such as package
installs.
icon: cycle
link: /build/cache
- title: Bake
description: Orchestrate your builds with Bake.
icon: cake
link: /build/bake
aliases:
- /buildx/working-with-buildx/
- /develop/develop-images/build_enhancements/
---
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
advanced scenarios.
{{< grid >}}
{{< grid >}}

8
content/build/architecture.md
View File

@ -2,8 +2,8 @@
title: Docker Build architecture
description: Learn about Docker Build and its components.
keywords: build, buildkit, buildx, architecture
redirect_from:
- /build/install-buildx/
aliases:
- /build/install-buildx/
---
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
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
## 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
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
keywords: build, attestations, sbom, provenance
description: >
Introduction to SBOM and provenance attestations with Docker Build; what they
are and why they exist
description: 'Introduction to SBOM and provenance attestations with Docker Build;
what they are and why they exist
'
---
{% 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 -->
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
[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.
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:
- [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
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){:
target="blank" rel="noopener" }.
[in-toto SPDX predicate](https://github.com/in-toto/attestation/blob/main/spec/predicates/spdx.md).
## 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 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
# 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
the raw contents of an SBOM in SPDX format:
{% raw %}
```console
$ docker buildx imagetools inspect <namespace>/<image>:<version> \
--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
of Go templates. For example, you can list all the installed packages and their
version identifiers:
{% raw %}
```console
$ docker buildx imagetools inspect <namespace>/<image>:<version> \
--format "{{ range .SBOM.SPDX.packages }}{{ .name }}@{{ .versionInfo }}{{ println }}{{ end }}"
@ -202,19 +201,19 @@ base-files@11ubuntu5.6
base-passwd@3.5.47
...
```
{% endraw %}
## SBOM generator
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
[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.
You can select a different plugin to use with the `generator` option, specifying
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
$ 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"
}
}
```
```

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
example, to get the raw contents of the Provenance in the SLSA format:
{% raw %}
```console
$ docker buildx imagetools inspect <namespace>/<image>:<version> \
--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
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:
{% raw %}
```console
$ 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
@ -174,7 +174,7 @@ FROM ubuntu:20.04
RUN apt-get update
...
```
{% endraw %}
## 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
keywords: build, buildx, bake, buildkit, hcl, json, compose
redirect_from:
aliases:
- /build/customize/bake/
---
> 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=""}.
{: .experimental }
> The design of bake is in early stages, and we are looking for [feedback from users](https://github.com/docker/buildx/issues).
{ .experimental }
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
your application together and let the users define project specific reusable
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.
The build commands can be combined with general-purpose command runners
(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)
* [User defined HCL functions](hcl-funcs.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
redirect_from:
aliases:
- /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
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
redirect_from:
aliases:
- /build/customize/bake/compose-file/
---
@ -97,7 +97,7 @@ $ docker buildx bake --print
The compose format has some limitations compared to the HCL format:
* 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
## `.env` file
@ -275,4 +275,4 @@ Complete list of valid fields for `x-bake`:
* `pull`
* `secret`
* `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
redirect_from:
aliases:
- /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:
```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
redirect_from:
aliases:
- /build/customize/bake/hcl-funcs/
---
@ -100,7 +100,7 @@ $ TAG=$(git rev-parse --short HEAD) docker buildx bake --print webapp
## 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.
```hcl
@ -147,7 +147,7 @@ $ docker buildx bake --print webapp
## 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.
```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
[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.
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 -rwxrwxrwx 1 root root 9620 Jul 27 18:31 vendor.conf
#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
description:
description: null
---
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)
> is a [Beta](../../release-lifecycle.md#beta) feature that lets you
> view and manage builders using Docker Desktop.
{: .experimental }
{ .experimental }
## Default builder
@ -76,4 +76,4 @@ selected when you invoke builds.
- For information about how to interact with and manage builders,
see [Manage builders](./manage.md)
- 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
description:
description: null
---
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, 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
description: How to create base images
keywords: images, base image, examples
redirect_from:
aliases:
- /articles/baseimages/
- /engine/articles/baseimages/
- /engine/userguide/eng-image/baseimages/
@ -30,7 +30,7 @@ ones.
In general, start with a working machine that is running
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.
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"
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
@ -70,7 +70,7 @@ CMD ["/hello"]
```
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
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.
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
@ -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.
* 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).
* 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
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
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
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
description: Use environment variables to configure builds
keywords: docker build, buildx, buildkit, env, environment variables, config
redirect_from:
- /build/buildkit/color-output-controls/
aliases:
- /build/buildkit/color-output-controls/
---
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
example, `true`, `1`, and `T` all evaluate to true. Evaluation is done using 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.
## 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
[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
[no-color.org](https://no-color.org/){: target="_blank" rel="noopener" class="_" }.
[no-color.org](https://no-color.org/).
## BUILDKIT_HOST
@ -240,4 +240,4 @@ Usage:
```console
$ export BUILDX_NO_DEFAULT_LOAD=1
```
```

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

@ -2,7 +2,7 @@
title: Multi-platform images
description: Introduction to multi-platform images and how to build them
keywords: build, buildx, buildkit, multi-platform images
redirect_from:
aliases:
- /build/buildx/multiplatform-images/
- /desktop/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
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`,
`arm32v7`, `arm64v8`, `i386`, `ppc64le`, and `s390x`. When running this image
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
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 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
@ -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`.
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,
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
description: |
Learn about multi-stage builds and how you can use
description: 'Learn about multi-stage builds and how you can use
them to improve your builds and get smaller images
'
keywords: build, best practices
redirect_from:
aliases:
- /engine/userguide/eng-image/multistage-build/
- /develop/develop-images/multistage-build/
---
@ -211,4 +213,4 @@ Removing intermediate container bbc025b93175
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
---
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
`driver-opt`.
@ -34,4 +34,4 @@ $ docker buildx inspect --bootstrap
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
keywords: build, buildx, buildkit, getting started, dockerfile
redirect_from:
aliases:
- /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
> 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.
{: .tip }
{ .tip }
### 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.
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
[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
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
At the core of BuildKit is a
[Low-Level Build (LLB)](https://github.com/moby/buildkit#exploring-llb){:target="blank"
rel="noopener" class=""} definition format. LLB is an intermediate binary format
[Low-Level Build (LLB)](https://github.com/moby/buildkit#exploring-llb) definition format. LLB is an intermediate binary format
that allows developers to extend BuildKit. LLB defines a content-addressable
dependency graph that can be used to put together very complex build
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.
LLB can be generated directly using a
[golang client package](https://pkg.go.dev/github.com/moby/buildkit/client/llb){:target="blank"
rel="noopener" class=""} that allows defining the relationships between your
[golang client package](https://pkg.go.dev/github.com/moby/buildkit/client/llb) that allows defining the relationships between your
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
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
> in
> [`moby/buildkit#616`](https://github.com/moby/buildkit/issues/616){:target="blank" rel="noopener" class=""}
{: .warning}
> [`moby/buildkit#616`](https://github.com/moby/buildkit/issues/616)
{ .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 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
includes 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.
{% raw %}
```dockerfile
# syntax=docker/dockerfile:1
ARG BUILDKIT_VERSION=v{{ site.buildkit_version }}
ARG BUILDKIT_VERSION=v{{% param "buildkit_version" %}}
ARG CNI_VERSION=v1.0.1
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
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
[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
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
description: Improve your build speeds by taking advantage of the builtin cache
keywords: >
build, buildx, buildkit, dockerfile, image layers, build instructions, build
context
redirect_from:
- /build/building/cache/
keywords: 'build, buildx, buildkit, dockerfile, image layers, build instructions,
build context
'
aliases:
- /build/building/cache/
---
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
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,
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
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
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
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
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
images from [verified publishers](https://hub.docker.com/search?q=&image_filter=store){:target="blank" rel="noopener" class=""}
and [open source partners](https://hub.docker.com/search?q=&image_filter=open_source){: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)
that can help you on your way. The Docker community often produces third-party
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
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:
```dockerfile
@ -292,4 +293,4 @@ of continuing.)
For more information on using cache to do efficient builds, see:
- [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
redirect_from:
- /build/building/cache/backends/
aliases:
- /build/building/cache/backends/
---
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.
- `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
[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
[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).
## Command syntax
@ -78,7 +78,7 @@ $ docker buildx build --push -t <registry>/<image> \
## Multiple caches
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
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
@ -162,4 +162,4 @@ $ docker buildx build --push -t <registry>/<image> \
```
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
redirect_from:
- /build/building/cache/backends/azblob/
aliases:
- /build/building/cache/backends/azblob/
---
> **Warning**
@ -11,7 +11,7 @@ redirect_from:
> `moby/buildkit:master` image in your Buildx driver.
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**
>
@ -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
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.
## 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 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
redirect_from:
- /build/building/cache/backends/gha/
aliases:
- /build/building/cache/backends/gha/
---
> **Warning**
@ -12,10 +12,10 @@ redirect_from:
> unstable and may change in future releases.
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
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**
>
@ -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`
command manually from an inline step, then the variables must be manually
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).
## Scope
@ -81,14 +81,14 @@ $ docker buildx build --push -t <registry>/<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
default branch is accessible by a workflow.
### Using `docker/build-push-action`
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
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 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
[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
redirect_from:
- /build/building/cache/backends/inline/
aliases:
- /build/building/cache/backends/inline/
---
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 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
redirect_from:
- /build/building/cache/backends/local/
aliases:
- /build/building/cache/backends/local/
---
The `local` cache store is a simple cache option that stores your cache as files
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
just testing, or if you want the flexibility to self-manage a shared storage
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
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
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).
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 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
redirect_from:
- /build/building/cache/backends/registry/
aliases:
- /build/building/cache/backends/registry/
---
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 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
redirect_from:
- /build/building/cache/backends/s3/
aliases:
- /build/building/cache/backends/s3/
---
> **Warning**
@ -11,7 +11,7 @@ redirect_from:
> `moby/buildkit:master` image in your Buildx driver.
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.
> **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,
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.
<!-- 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 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
keywords: build, buildx, buildkit, garbage collection, prune
redirect_from:
- /build/building/cache/garbage-collection/
aliases:
- /build/building/cache/garbage-collection/
---
While [`docker builder prune`](../../engine/reference/commandline/builder_prune.md)
@ -89,4 +89,4 @@ GC Policy rule#3:
> **Note**
>
> "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
keywords: ci, build
redirect_from:
- /ci-cd/best-practices/
title: Continuous integration with Docker
aliases:
- /ci-cd/best-practices/
---
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
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
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
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=""}
- [GitLab](https://docs.gitlab.com/runner/executors/docker.html){:target="blank" rel="noopener" class=""}
- [Circle CI](https://circleci.com/docs/using-docker/){:target="blank" rel="noopener" class=""}
- [Render](https://render.com/docs/docker){: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)
- [Circle CI](https://circleci.com/docs/using-docker/)
- [Render](https://render.com/docs/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
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.
## 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,
annotate, and push container images on the GitHub Actions platform. See
[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
description: >
Docker maintains a set of official GitHub Actions for building Docker images.
description: 'Docker maintains a set of official GitHub Actions for building Docker
images.
'
keywords: ci, github actions, gha, build, introduction, tutorial
redirect_from:
- /ci-cd/github-actions/
- /build/ci/github-actions/examples/
aliases:
- /ci-cd/github-actions/
- /build/ci/github-actions/examples/
---
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:
- [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.
- [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.
- [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.
- [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.
- [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
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).
- [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.
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
{% include gha-tutorial.md %}
{{< include "gha-tutorial.md" >}}
## 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
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),
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
registry cache exporter with the `cache-to` option, as shown in the [registry cache example](#registry-cache).
{% raw %}
```yaml
name: ci
@ -53,14 +53,14 @@ jobs:
cache-from: type=registry,ref=user/app:latest
cache-to: type=inline
```
{% endraw %}
## Registry cache
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).
{% raw %}
```yaml
name: ci
@ -95,7 +95,7 @@ jobs:
cache-from: type=registry,ref=user/app:buildcache
cache-to: type=registry,ref=user/app:buildcache,mode=max
```
{% endraw %}
## GitHub cache
@ -103,9 +103,9 @@ jobs:
> 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.
{: .experimental }
{ .experimental }
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)
@ -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
context.
{% raw %}
```yaml
name: ci
@ -149,7 +149,7 @@ jobs:
cache-from: type=gha
cache-to: type=gha,mode=max
```
{% endraw %}
### 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.
{% raw %}
```yaml
name: ci
on: push
@ -223,7 +223,7 @@ jobs:
with:
cache-source: go-build-cache
```
{% endraw %}
For more information about this workaround, refer to the
[GitHub repository](https://github.com/overmindtech/buildkit-cache-dance).
@ -232,16 +232,16 @@ For more information about this workaround, refer to the
> **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=""}.
> 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=""}
> 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)
> 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)
with this action:
{% raw %}
```yaml
name: ci
@ -291,5 +291,4 @@ jobs:
run: |
rm -rf /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
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
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
[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 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
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=""},
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:
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) action:
```yaml
name: ci
@ -162,7 +162,7 @@ fields:
Here is an example using remote nodes with the [`remote` driver](../../drivers/remote.md)
and [TLS authentication](#tls-authentication):
{% raw %}
```yaml
name: ci
@ -195,7 +195,7 @@ jobs:
BUILDER_NODE_2_AUTH_TLS_CERT: ${{ secrets.LINUXONE_CERT }}
BUILDER_NODE_2_AUTH_TLS_KEY: ${{ secrets.LINUXONE_KEY }}
```
{% endraw %}
## 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),
you have to set up the SSH private key and configuration on the GitHub Runner:
{% raw %}
```yaml
name: ci
@ -231,7 +231,7 @@ jobs:
with:
endpoint: ssh://me@graviton2
```
{% endraw %}
### TLS authentication
@ -246,7 +246,7 @@ certificates for the `tcp://`:
The `<idx>` placeholder is the position of the node in the list of nodes.
{% raw %}
```yaml
name: ci
@ -268,7 +268,7 @@ jobs:
BUILDER_NODE_0_AUTH_TLS_CERT: ${{ secrets.GRAVITON2_CERT }}
BUILDER_NODE_0_AUTH_TLS_KEY: ${{ secrets.GRAVITON2_KEY }}
```
{% endraw %}
## Standalone mode
@ -315,7 +315,7 @@ hardware.
For more information about remote builder, see [`remote` driver](../../drivers/remote.md)
and the [append builder nodes example](#append-additional-nodes-to-the-builder).
{% raw %}
```yaml
name: ci
@ -357,5 +357,4 @@ jobs:
builder: ${{ steps.builder2.outputs.name }}
context: .
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
be copied from one registry to another using the [`buildx imagetools create` command](../../../engine/reference/commandline/buildx_imagetools_create.md):
{% raw %}
```yaml
name: ci
@ -58,5 +58,4 @@ jobs:
--tag ghcr.io/user/app:latest \
--tag ghcr.io/user/app:1.0.0 \
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
`docker images` to be able to use it in another step of your workflow:
{% raw %}
```yaml
name: ci
@ -36,5 +36,4 @@ jobs:
name: Inspect
run: |
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
---
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:
{% raw %}
```yaml
name: ci
@ -46,5 +46,4 @@ jobs:
name: Inspect
run: |
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
---
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
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:
{% raw %}
```yaml
name: ci
@ -78,5 +78,4 @@ jobs:
push: ${{ github.event_name != 'pull_request' }}
tags: ${{ steps.meta.outputs.tags }}
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**
>
> - 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.
> - 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.
{% raw %}
```yaml
name: ci
@ -50,7 +50,7 @@ jobs:
push: true
tags: user/app:latest
```
{% endraw %}
## 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)
to set tags and labels.
{% raw %}
```yaml
name: ci
@ -173,5 +173,4 @@ jobs:
name: Inspect image
run: |
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"
```
{% raw %}
```yaml
name: ci
@ -48,11 +48,11 @@ jobs:
alpine=docker-image://alpine:3.16
tags: myimage:latest
```
{% endraw %}
## 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
loaded automatically.
@ -64,7 +64,7 @@ FROM alpine
RUN echo "Hello World"
```
{% raw %}
```yaml
name: ci
@ -102,7 +102,7 @@ jobs:
alpine=docker-image://my-base-image:latest
tags: myimage:latest
```
{% endraw %}
## Using with a container builder
@ -163,4 +163,4 @@ jobs:
build-contexts: |
alpine=docker-image://localhost:5000/my-base-image: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
---
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:
{% raw %}
```yaml
name: ci
@ -53,5 +53,4 @@ jobs:
user/app:1.0.0
ghcr.io/user/app:latest
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
---
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.
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
exposes this secret using the `secrets` input:
{% raw %}
```yaml
name: ci
@ -51,7 +51,7 @@ jobs:
"github_token=${{ secrets.GITHUB_TOKEN }}"
```
{% endraw %}
> **Note**
>
@ -62,11 +62,11 @@ jobs:
> "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
between quotes:
{% raw %}
```yaml
secrets: |
"MYSECRET=${{ secrets.GPG_KEY }}"
@ -81,7 +81,7 @@ secrets: |
ccc"
"JSON_SECRET={""key1"":""value1"",""key2"":""value2""}"
```
{% endraw %}
| Key | Value |
|------------------|-------------------------------------|
@ -94,4 +94,4 @@ secrets: |
> **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
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=""}
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=""}
in a workflow using the [actions/upload-artifact](https://github.com/actions/upload-artifact){:target="blank" rel="noopener" class=""}
and [actions/download-artifact](https://github.com/actions/download-artifact){: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)
in a workflow using the [actions/upload-artifact](https://github.com/actions/upload-artifact)
and [actions/download-artifact](https://github.com/actions/download-artifact)
actions:
{% raw %}
```yaml
name: ci
@ -58,5 +58,4 @@ jobs:
run: |
docker load --input /tmp/myimage.tar
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
3. Multi-platform build and push the image
{% raw %}
```yaml
name: ci
@ -64,11 +64,11 @@ jobs:
push: true
tags: ${{ env.LATEST_TAG }}
```
{% endraw %}
> **Note**
>
> 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
> 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
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:
{% raw %}
```yaml
name: ci
@ -49,5 +49,4 @@ jobs:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
repository: user/app
```
{% endraw %}
```

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

@ -1,8 +1,8 @@
---
title: Custom Dockerfile syntax
keywords: build, buildkit, dockerfile, frontend
redirect_from:
- /build/buildkit/dockerfile-frontend/
aliases:
- /build/buildkit/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
- 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
- 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**
>
@ -52,7 +52,7 @@ channels where new images are released: `stable` and `labs`.
### 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:
- `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
new features, use the `labs` channel. Images in the `labs` channel contain
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
compatible. Pin the version to avoid having to deal with breaking changes.
## Other resources
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=""}.
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=""},
and the [`docker/dockerfile-upstream` repository on Docker Hub](https://hub.docker.com/r/docker/dockerfile-upstream){:target="blank" rel="noopener" class=""}
for development builds.
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),
and the [`docker/dockerfile-upstream` repository on Docker Hub](https://hub.docker.com/r/docker/dockerfile-upstream)
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
{% include release-date.html date="2023-06-13" %}
{{< release-date date="2023-06-13" >}}
### New
@ -36,7 +36,7 @@ The following features have graduated from the labs channel to stable:
## 1.5.2
{% include release-date.html date="2023-02-14" %}
{{< release-date date="2023-02-14" >}}
### Bug fixes and enhancements
@ -46,7 +46,7 @@ The following features have graduated from the labs channel to stable:
## 1.5.1
{% include release-date.html date="2023-01-18" %}
{{< release-date date="2023-01-18" >}}
### Bug fixes and enhancements
@ -54,9 +54,9 @@ The following features have graduated from the labs channel to stable:
## 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
@ -65,7 +65,7 @@ The following features have graduated from the labs channel to stable:
## 1.5.0
{% include release-date.html date="2023-01-10" %}
{{< release-date date="2023-01-10" >}}
### New
@ -86,7 +86,7 @@ The following features have graduated from the labs channel to stable:
## 1.4.3
{% include release-date.html date="2022-08-23" %}
{{< release-date date="2022-08-23" >}}
### Bug fixes and enhancements
@ -97,7 +97,7 @@ The following features have graduated from the labs channel to stable:
## 1.4.2
{% include release-date.html date="2022-05-06" %}
{{< release-date date="2022-05-06" >}}
### Bug fixes and enhancements
@ -106,7 +106,7 @@ The following features have graduated from the labs channel to stable:
## 1.4.1
{% include release-date.html date="2022-04-08" %}
{{< release-date date="2022-04-08" >}}
### Bug fixes and enhancements
@ -115,7 +115,7 @@ The following features have graduated from the labs channel to stable:
## 1.4.0
{% include release-date.html date="2022-03-09" %}
{{< release-date date="2022-03-09" >}}
### New
@ -140,7 +140,7 @@ The following features have graduated from the labs channel to stable:
## 1.3.1
{% include release-date.html date="2021-10-04" %}
{{< release-date date="2021-10-04" >}}
### Bug fixes and enhancements
@ -148,9 +148,9 @@ The following features have graduated from the labs channel to stable:
## 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
@ -159,7 +159,7 @@ The following features have graduated from the labs channel to stable:
## 1.3.0
{% include release-date.html date="2021-07-16" %}
{{< release-date date="2021-07-16" >}}
### New
@ -179,9 +179,9 @@ The following features have graduated from the labs channel to stable:
## 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
@ -191,7 +191,7 @@ The following features have graduated from the labs channel to stable:
## 1.2.1
{% include release-date.html date="2020-12-12" %}
{{< release-date date="2020-12-12" >}}
### Bug fixes and enhancements
@ -200,9 +200,9 @@ The following features have graduated from the labs channel to stable:
## 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
@ -210,7 +210,7 @@ The following features have graduated from the labs channel to stable:
## 1.2.0
{% include release-date.html date="2020-12-03" %}
{{< release-date date="2020-12-03" >}}
### New
@ -229,7 +229,7 @@ The following features have graduated from the labs channel to stable:
## 1.1.7
{% include release-date.html date="2020-04-18" %}
{{< release-date date="2020-04-18" >}}
### Bug fixes and enhancements
@ -237,9 +237,9 @@ The following features have graduated from the labs channel to stable:
## 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
@ -251,7 +251,7 @@ The following features have graduated from the labs channel to stable:
## 1.1.2
{% include release-date.html date="2019-07-31" %}
{{< release-date date="2019-07-31" >}}
### Bug fixes and enhancements
@ -261,7 +261,7 @@ The following features have graduated from the labs channel to stable:
## 1.1.0
{% include release-date.html date="2019-04-27" %}
{{< release-date date="2019-04-27" >}}
### 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
found `.dockerignore` file will be looked up from the root of the build
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
redirect_from:
- /build/buildx/drivers/
- /build/building/drivers/
- /build/buildx/multiple-builders/
aliases:
- /build/buildx/drivers/
- /build/building/drivers/
- /build/buildx/multiple-builders/
---
Buildx drivers are configurations for how and where the BuildKit backend runs.
@ -39,4 +39,4 @@ use them:
- [Docker driver](./docker.md)
- [Docker container driver](./docker-container.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
redirect_from:
- /build/buildx/drivers/docker-container/
- /build/building/drivers/docker-container/
aliases:
- /build/buildx/drivers/docker-container/
- /build/building/drivers/docker-container/
---
The buildx Docker container driver allows creation of a managed and customizable
@ -42,7 +42,7 @@ pass to `--driver-opt`:
## Usage
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
containerized build server.
@ -120,7 +120,7 @@ container
## 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
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)
and see what network is being used:
{% raw %}
```console
$ docker inspect buildx_buildkit_mybuilder0 --format={{.NetworkSettings.Networks}}
map[foonet:0xc00018c0c0]
```
{% endraw %}
## Further reading
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
redirect_from:
- /build/buildx/drivers/docker/
- /build/building/drivers/docker/
aliases:
- /build/buildx/drivers/docker/
- /build/building/drivers/docker/
---
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
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
redirect_from:
- /build/buildx/drivers/kubernetes/
- /build/building/drivers/kubernetes/
aliases:
- /build/buildx/drivers/kubernetes/
- /build/building/drivers/kubernetes/
---
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
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:
@ -135,7 +135,7 @@ leveraging the native architecture of nodes.
### QEMU
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
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
rootless mode works, and it's requirements, see
[here](https://github.com/moby/buildkit/blob/master/docs/rootless.md){:target="blank"
rel="noopener" class=""}.
[here](https://github.com/moby/buildkit/blob/master/docs/rootless.md).
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
can follow along by installing
[minikube](https://minikube.sigs.k8s.io/docs/){:target="blank" rel="noopener"
class=""}.
[minikube](https://minikube.sigs.k8s.io/docs/).
- The cluster you want to connect to is accessible via the `kubectl` command,
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"
rel="noopener" class=""} if necessary.
[set appropriately](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/#set-the-kubeconfig-environment-variable) if necessary.
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
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
redirect_from:
- /build/buildx/drivers/remote/
- /build/building/drivers/remote/
aliases:
- /build/buildx/drivers/remote/
- /build/building/drivers/remote/
---
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
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.
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
```
Alternatively, [see here](https://github.com/moby/buildkit/blob/master/docs/rootless.md){:target="blank" rel="noopener" class=""}
for running buildkitd in rootless mode or [here](https://github.com/moby/buildkit/tree/master/examples/systemd){: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)
for examples of running it as a systemd service.
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.
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
over TCP without using TLS, it's not recommended. Doing so allows arbitrary
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.
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
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
them.
@ -192,4 +192,4 @@ $ docker buildx create \
--name remote-container \
--driver remote \
kube-pod://buildkitd-XXXXXXXXXX-xxxxx
```
```

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

@ -1,10 +1,11 @@
---
title: "Exporters overview"
keywords: >
build, buildx, buildkit, exporter, image, registry, local, tar, oci, docker,
title: Exporters overview
keywords: 'build, buildx, buildkit, exporter, image, registry, local, tar, oci, docker,
cacheonly
redirect_from:
- /build/building/exporters/
'
aliases:
- /build/building/exporters/
---
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.
- `tar`: packs the build root filesystem into a local tarball.
- `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.
- `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.
- `cacheonly`: doesn't export a build output, but runs the build and creates a
cache.
@ -184,7 +185,7 @@ WARNING: No output specified with docker-container driver.
## Multiple exporters
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
twice. BuildKit caches the build, so unless any of the layers change, all
successive builds following the first are instant.
@ -242,8 +243,8 @@ the previous compression algorithm.
> **Note**
>
> The `gzip` and `estargz` compression methods use the [`compress/gzip` package](https://pkg.go.dev/compress/gzip){: target="blank" rel="noopener" class="_" },
> while `zstd` uses the [`github.com/klauspost/compress/zstd` package](https://github.com/klauspost/compress/tree/master/zstd){: 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).
### OCI media types
@ -266,4 +267,4 @@ them:
- [Image and registry exporters](image-registry.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"
keywords: >
build, buildx, buildkit, exporter, image, registry
redirect_from:
- /build/building/exporters/image-registry/
title: Image and registry exporters
keywords: 'build, buildx, buildkit, exporter, image, registry
'
aliases:
- /build/building/exporters/image-registry/
---
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
[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
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"
keywords: >
build, buildx, buildkit, exporter, local, tar
redirect_from:
- /build/building/exporters/local-tar/
title: Local and tar exporters
keywords: 'build, buildx, buildkit, exporter, local, tar
'
aliases:
- /build/building/exporters/local-tar/
---
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
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"
keywords: >
build, buildx, buildkit, exporter, oci, docker
redirect_from:
- /build/building/exporters/local-tar/
title: OCI and Docker exporters
keywords: 'build, buildx, buildkit, exporter, oci, docker
'
aliases:
- /build/building/exporters/local-tar/
---
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
image layout instead.
@ -56,9 +57,9 @@ $ docker buildx build \
```
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
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
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
description: Introduction to configurable builds, using build args
keywords: >
build, buildkit, buildx, guide, tutorial, build arguments, arg
keywords: 'build, buildkit, buildx, guide, tutorial, build arguments, arg
'
---
{% include_relative nav.html selected="5" %}
@ -14,7 +15,7 @@ uses as a fallback.
## Change runtime versions
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.
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
@ -23,8 +24,8 @@ has to be. Build arguments make life easier:
```diff
# syntax=docker/dockerfile:1
- FROM golang:{{site.example_go_version}}-alpine AS base
+ ARG GO_VERSION={{site.example_go_version}}
- FROM golang:{{% param "example_go_version" %}}-alpine AS base
+ ARG GO_VERSION={{% param "example_go_version" %}}
+ FROM golang:${GO_VERSION}-alpine AS base
WORKDIR /src
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 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
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
`--build-arg` flag for the build command:
@ -97,7 +98,7 @@ a variable in the code.
```diff
# 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
WORKDIR /src
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
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
description: Using Docker builds to create and export executable binaries
keywords: >
build, buildkit, buildx, guide, tutorial, build arguments, arg
keywords: 'build, buildkit, buildx, guide, tutorial, build arguments, arg
'
---
{% include_relative nav.html selected="6" %}
@ -50,7 +51,7 @@ stage:
```diff
# 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
WORKDIR /src
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
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
# syntax=docker/dockerfile:1
FROM golang:{{site.example_go_version}}-alpine
FROM golang:{{% param "example_go_version" %}}-alpine
WORKDIR /src
COPY . .
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
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`
@ -169,4 +169,4 @@ Related information:
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
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
@ -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
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
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
# syntax=docker/dockerfile:1
FROM golang:{{site.example_go_version}}-alpine
FROM golang:{{% param "example_go_version" %}}-alpine
WORKDIR /src
- COPY . .
+ 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
`RUN go mod download` layer.
![Reordered](./images/reordered-layers.png){:.invertible}
![Reordered](./images/reordered-layers.png)
## Summary
@ -80,4 +80,4 @@ Related information:
The next section shows how you can make the build run faster, and make the
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
description: Introduction to cache mounts and bind mounts in builds
keywords: >
build, buildkit, buildx, guide, tutorial, mounts, cache mounts, bind mounts
keywords: 'build, buildkit, buildx, guide, tutorial, mounts, cache mounts, bind mounts
'
---
{% include_relative nav.html selected="4" %}
@ -36,7 +37,7 @@ mount the `/go/pkg/mod` directory as a cache mount:
```diff
# syntax=docker/dockerfile:1
FROM golang:{{site.example_go_version}}-alpine AS base
FROM golang:{{% param "example_go_version" %}}-alpine AS base
WORKDIR /src
COPY go.mod go.sum .
- RUN go mod download
@ -117,7 +118,7 @@ Update the version of the `chi` package that the server component of the
application uses:
```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
```
@ -151,7 +152,7 @@ the need for the additional `COPY` instruction (and layer) entirely.
```diff
# syntax=docker/dockerfile:1
FROM golang:{{site.example_go_version}}-alpine AS base
FROM golang:{{% param "example_go_version" %}}-alpine AS base
WORKDIR /src
- COPY go.mod go.sum .
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
# syntax=docker/dockerfile:1
FROM golang:{{site.example_go_version}}-alpine AS base
FROM golang:{{% param "example_go_version" %}}-alpine AS base
WORKDIR /src
RUN --mount=type=cache,target=/go/pkg/mod/ \
--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
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
description: Building for multiple operating systems and architectures
keywords: >-
build, buildkit, buildx, guide, tutorial, multi-platform, emulation,
cross-compilation
keywords: build, buildkit, buildx, guide, tutorial, multi-platform, emulation, cross-compilation
---
{% 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.
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
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
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
@ -175,8 +173,8 @@ follows:
```diff
# syntax=docker/dockerfile:1
ARG GO_VERSION={{site.example_go_version}}
ARG GOLANGCI_LINT_VERSION={{site.example_golangci_lint_version}}
ARG GO_VERSION={{% param "example_go_version" %}}
ARG GOLANGCI_LINT_VERSION={{% param "example_golangci_lint_version" %}}
- FROM golang:${GO_VERSION}-alpine AS base
+ FROM --platform=$BUILDPLATFORM golang:${GO_VERSION}-alpine AS base
WORKDIR /src
@ -262,7 +260,7 @@ Related information:
- [`docker buildx create` CLI reference](../../engine/reference/commandline/buildx_create.md)
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.
## 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
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
# syntax=docker/dockerfile:1
FROM golang:{{site.example_go_version}}-alpine
FROM golang:{{% param "example_go_version" %}}-alpine
WORKDIR /src
COPY go.mod go.sum .
RUN go mod download
@ -90,8 +90,8 @@ to the final `scratch` image.
```diff
# syntax=docker/dockerfile:1
- FROM golang:{{site.example_go_version}}-alpine
+ FROM golang:{{site.example_go_version}}-alpine AS base
- FROM golang:{{% param "example_go_version" %}}-alpine
+ FROM golang:{{% param "example_go_version" %}}-alpine AS base
WORKDIR /src
COPY go.mod go.sum .
RUN go mod download
@ -129,7 +129,7 @@ unnamed `FROM scratch` stage with two separate stages named `client` and
```diff
# syntax=docker/dockerfile:1
FROM golang:{{site.example_go_version}}-alpine AS base
FROM golang:{{% param "example_go_version" %}}-alpine AS base
WORKDIR /src
COPY go.mod go.sum .
RUN go mod download
@ -190,4 +190,4 @@ Related information:
The next section describes how you can use file mounts to further improve build
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.
You can also submit an issue on
[the docs GitHub repository](https://github.com/docker/docs/issues/new){: target="_blank" rel="noopener" },
if you prefer.
[the docs GitHub repository](https://github.com/docker/docs/issues/new),
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
# syntax=docker/dockerfile:1
ARG GO_VERSION={{site.example_go_version}}
+ ARG GOLANGCI_LINT_VERSION={{site.example_golangci_lint_version}}
ARG GO_VERSION={{% param "example_go_version" %}}
+ ARG GOLANGCI_LINT_VERSION={{% param "example_golangci_lint_version" %}}
FROM golang:${GO_VERSION}-alpine AS base
WORKDIR /src
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
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