diff --git a/_vale/Docker/Acronyms.yml b/_vale/Docker/Acronyms.yml index 0649318e254..cfccdaf0800 100644 --- a/_vale/Docker/Acronyms.yml +++ b/_vale/Docker/Acronyms.yml @@ -5,10 +5,11 @@ level: warning ignorecase: false # Ensures that the existence of 'first' implies the existence of 'second'. first: '\b([A-Z]{2,5})\b' -second: '(?:\b[A-Z][a-z]+ )+\(([A-Z]{2,5})\)' +second: '(?:\b[A-Z][a-z]+ )+\(([A-Z]{2,5})s?\)' # ... with the exception of these: exceptions: - AGPL + - AI - API - ARM - ASP @@ -16,7 +17,10 @@ exceptions: - AWS - BIOS - BPF + - BSD + - CFS - CI + - CIDR - CISA - CLI - CNCF @@ -24,6 +28,7 @@ exceptions: - CPU - CSS - CSV + - CUDA - CVE - DCT - DEBUG @@ -54,9 +59,12 @@ exceptions: - HTTP - HTTPS - IAM + - IBM - ID - IDE - IP + - IPAM + - IPC - JAR - JSON - JSX @@ -70,10 +78,13 @@ exceptions: - NET - NFS - NOTE + - NTFS - NTLM + - NUMA - NVDA - OCI - OS + - OSI - OSS - PATH - PDF @@ -86,6 +97,7 @@ exceptions: - RAM - REPL - REST + - RFC - RHEL - RPM - RSA @@ -120,8 +132,10 @@ exceptions: - USB - USD - UTF + - UTS - UUID - VAT + - VIP - VLAN - VM - VPN diff --git a/_vale/config/vocabularies/Docker/accept.txt b/_vale/config/vocabularies/Docker/accept.txt index 97b29fc6332..516200bd089 100644 --- a/_vale/config/vocabularies/Docker/accept.txt +++ b/_vale/config/vocabularies/Docker/accept.txt @@ -1,4 +1,4 @@ -(?-i)[A-Z]{2,}'?s +(?i)[A-Z]{2,}'?s Amazon Anchore Apple @@ -20,8 +20,8 @@ Couchbase Datadog Ddosify Debootstrap -Dev Environments? Dev +Dev Environments? Django Docker Build Cloud Docker Business @@ -73,8 +73,8 @@ Nuxeo OAuth OTel Okta -Paketo PKG +Paketo Postgres PowerShell Python @@ -97,20 +97,27 @@ Windows WireMock Zscaler Zsh +[Aa]nonymized? [Aa]utobuild -[Bb]uildx +[Aa]llowlist [Bb]uildpack(s)? +[Bb]uildx [Cc]odenames? [Cc]ompose +[Cc]onfigs [Dd]istroless [Ff]ilepaths? [Ff]iletypes? [GgCc]oroutine +[Hh]ealthcheck [Hh]ostname [Ii]nfosec +[Ii]nline [Kk]eyrings? [Ll]oopback +[Mm]emcached [Mm]oby +[Mm]ountpoint [Nn]amespace [Oo]nboarding [Pp]aravirtualization @@ -123,6 +130,7 @@ Zsh [Ss]andbox(ed)? [Ss]eccomp [Ss]ubmounts? +[Ss]ubnet [Ss]ubpaths? [Ss]ubtrees? [Ss]wappable @@ -133,12 +141,17 @@ Zsh [Ss]ysfs [Tt]oolchains? [Uu]narchived? +[Uu]ngated +[Uu]ntrusted +[Uu]serland +[Uu]serspace [Vv]irtiofs [Vv]irtualize [Ww]alkthrough cgroup config containerd +datacenter deprovisioning deserialization deserialize @@ -166,18 +179,19 @@ npm osquery osxfs pgAdmin +rollback rootful runc snapshotters? stdin stdout -subnet +syntaxes +sysctls systemd tmpfs ufw +uid umask -ungated -userland -untrusted vSphere vpnkit +windowsfilter diff --git a/_vendor/modules.txt b/_vendor/modules.txt index e0b9fdce71a..77efffc0e10 100644 --- a/_vendor/modules.txt +++ b/_vendor/modules.txt @@ -2,5 +2,5 @@ # github.com/moby/buildkit v0.18.0 # github.com/docker/buildx v0.19.2 # github.com/docker/cli v27.4.0+incompatible -# github.com/docker/compose/v2 v2.31.0 +# github.com/docker/compose/v2 v2.32.0 # github.com/docker/scout-cli v1.15.0 diff --git a/content/_index.md b/content/_index.md index 5d5ecb947b2..5561dc158f3 100644 --- a/content/_index.md +++ b/content/_index.md @@ -80,17 +80,6 @@ grid: url: "/scout/quickstart/" - text: "Image analysis" url: "/scout/image-analysis/" - - title: Trusted content - icon: verified - description: | - High-quality, secure images from Docker and verified partners. - links: - - text: "Overview" - url: "/trusted-content/" - - text: "Official images" - url: "/trusted-content/official-images/" - - text: "Verified publisher program" - url: "/trusted-content/dvp-program/" - title: Subscription icon: card_membership description: | diff --git a/content/get-started/docker-concepts/building-images/multi-stage-builds.md b/content/get-started/docker-concepts/building-images/multi-stage-builds.md index 7e45aa8f81c..0de903ee206 100644 --- a/content/get-started/docker-concepts/building-images/multi-stage-builds.md +++ b/content/get-started/docker-concepts/building-images/multi-stage-builds.md @@ -231,7 +231,7 @@ Now that you have the project, you’re ready to create the `Dockerfile`. 1. Now that you have an image built, it's time to run the container. ```console - $ docker run -d -p 8080:8080 spring-helloworld + $ docker run -p 8080:8080 spring-helloworld ``` You'll then see output similar to the following in the container log: diff --git a/content/get-started/docker-concepts/the-basics/what-is-an-image.md b/content/get-started/docker-concepts/the-basics/what-is-an-image.md index d818f1797ad..c3702a4c5fe 100644 --- a/content/get-started/docker-concepts/the-basics/what-is-an-image.md +++ b/content/get-started/docker-concepts/the-basics/what-is-an-image.md @@ -188,10 +188,7 @@ In this walkthrough, you searched and pulled a Docker image. In addition to pull The following resources will help you learn more about exploring, finding, and building images: -- [Docker Trusted Content](/manuals/trusted-content/_index.md) - - [Docker Official Images docs](/manuals/trusted-content/official-images/_index.md) - - [Docker Verified Publisher docs](/manuals/trusted-content/dvp-program.md) - - [Docker-Sponsored Open Source Program docs](/manuals/trusted-content/dsos-program.md) +- [Docker trusted content](/manuals/docker-hub/image-library/trusted-content.md) - [Explore the Image view in Docker Desktop](/manuals/desktop/use-desktop/images.md) - [Docker Build overview](/manuals/build/concepts/overview.md) - [Docker Hub](https://hub.docker.com) diff --git a/content/get-started/introduction/build-and-push-first-image.md b/content/get-started/introduction/build-and-push-first-image.md index ce507efa716..69af604c805 100644 --- a/content/get-started/introduction/build-and-push-first-image.md +++ b/content/get-started/introduction/build-and-push-first-image.md @@ -33,7 +33,7 @@ If you’re new to container images, think of them as a standardized package tha To share your Docker images, you need a place to store them. This is where registries come in. While there are many registries, Docker Hub is the default and go-to registry for images. Docker Hub provides both a place for you to store your own images and to find images from others to either run or use as the bases for your own images. -In [Develop with containers](develop-with-containers.md), you used the following images that came from Docker Hub, each of which are [Docker Official Images](/trusted-content/official-images/): +In [Develop with containers](develop-with-containers.md), you used the following images that came from Docker Hub, each of which are [Docker Official Images](/manuals/docker-hub/image-library/trusted-content.md#docker-official-images): - [node](https://hub.docker.com/_/node) - provides a Node environment and is used as the base of your development efforts. This image is also used as the base for the final application image. - [mysql](https://hub.docker.com/_/mysql) - provides a MySQL database to store the to-do list items diff --git a/content/get-started/workshop/02_our_app.md b/content/get-started/workshop/02_our_app.md index 0e2ee0bbc5a..9d05ba5fc11 100644 --- a/content/get-started/workshop/02_our_app.md +++ b/content/get-started/workshop/02_our_app.md @@ -104,7 +104,7 @@ Now that you have an image, you can run the application in a container using the The `-d` flag (short for `--detach`) runs the container in the background. This means that Docker starts your container and returns you to the terminal - prompt. + prompt. Also, it does not display logs in the terminal. The `-p` flag (short for `--publish`) creates a port mapping between the host and the container. The `-p` flag takes a string value in the format of diff --git a/content/guides/_index.md b/content/guides/_index.md index 4d10f38ead8..1aed59cd077 100644 --- a/content/guides/_index.md +++ b/content/guides/_index.md @@ -6,8 +6,9 @@ params: icon: developer_guide layout: landing aliases: - - /learning-paths/ + - /guides/language/ - /language/ + - /learning-paths/ --- Explore our collection of guides to learn how Docker can optimize your diff --git a/content/guides/container-supported-development.md b/content/guides/container-supported-development.md index b76918ebdc1..5a2f142f923 100644 --- a/content/guides/container-supported-development.md +++ b/content/guides/container-supported-development.md @@ -51,6 +51,10 @@ With container-supported development, it's easy to run databases locally. In thi {{< youtube-embed VieWeXOwKLU >}} +> [!TIP] +> +> Learn more about running databases in containers in the [Use containerized databases](/guides/databases.md) guide. + ### Demo: mocking API endpoints Many APIs require data from other data endpoints. In development, this adds complexities such as the sharing of credentials, uptime/availability, and rate limiting. Instead of relying on those services directly, your application can interact with a mock API server. @@ -59,6 +63,10 @@ This demo will demonstrate how using WireMock can make it easy to develop and te {{< youtube-embed VXSmX6f8vo0 >}} +> [!TIP] +> +> Learn more about using WireMock to mock API in the [Mocking API services with WireMock](/guides/wiremock.md) guide. + ### Demo: developing the cloud locally When developing apps, it's often easier to outsource aspects of the application to cloud services, such as Amazon S3. However, connecting to those services in local development introduces IAM policies, networking constraints, and provisioning complications. While these requirements are important in a production setting, they complicate development environments significantly. @@ -67,6 +75,10 @@ With container-supported development, you can run local instances of these servi {{< youtube-embed JtwUMvR5xlY >}} +> [!TIP] +> +> Learn more about using LocalStack in the [Develop and test AWS Cloud applications using LocalStack](/guides/localstack.md) guide. + ### Demo: adding additional debug and troubleshooting tools Once you start using containers in your development environment, it becomes much easier to add additional containers to visualize the contents of the databases or message queues, seed document stores, or event publishers. In this demo, you'll see a few of these examples, as well as how you can connect multiple containers together to make testing even easier. diff --git a/content/includes/admin-company-overview.md b/content/includes/admin-company-overview.md index 194c4bbd7d0..9595e947572 100644 --- a/content/includes/admin-company-overview.md +++ b/content/includes/admin-company-overview.md @@ -8,16 +8,15 @@ The following diagram depicts the setup of a company and how it relates to assoc With a company, administrators can: -- View and manage all nested organizations and configure settings centrally. -- Carefully control access to the company and company settings. -- Have up to ten unique users assigned the company owner role. -- Configure SSO and SCIM for all nested organizations. -- Enforce SSO for all users in the company. +- View and manage all nested organizations and configure settings centrally +- Carefully control access to the company and company settings +- Have up to ten unique users assigned the company owner role +- Configure SSO and SCIM for all nested organizations +- Enforce SSO for all users in the company ## Prerequisites Before you create a company, verify the following: - Any organizations you want to add to a company have a Docker Business subscription -- You're an organization owner -- You're an organization owner for any additional organizations you want to add to the company you create +- You're an organization owner for your organization and any additional organizations you want to add diff --git a/content/includes/hub-categories.md b/content/includes/hub-categories.md new file mode 100644 index 00000000000..5b2b747b0c4 --- /dev/null +++ b/content/includes/hub-categories.md @@ -0,0 +1,34 @@ +The categories include: + +- **API Management**: Tools for creating, publishing, analyzing, and securing + APIs. +- **Content Management System:** Software applications to create and manage + digital content through templates, procedures, and standard formats. +- **Data Science:** Tools and software to support analyzing data and generating + actionable insights. +- **Databases & Storage:** Systems for storing, retrieving, and managing data. +- **Languages & Frameworks:** Programming language runtimes and frameworks. +- **Integrations & Delivery:** Tools for Continuous Integration (CI) and + Continuous Delivery (CD). +- **Internet of Things:** Tools supporting Internet of Things (IoT) + applications. +- **Machine Learning & AI:** Tools and frameworks optimized for artificial + intelligence and machine learning projects, such as pre-installed libraries + and frameworks for data analysis, model training, and deployment. +- **Message Queues:** Message queuing systems optimized for reliable, scalable, + and efficient message handling. +- **Monitoring & Observability:** Tools to track software and system performance + through metrics, logs, and traces, as well as observability to explore the + system’s state and diagnose issues. +- **Networking:** Repositories that support data exchange and connecting + computers and other devices to share resources. +- **Operating Systems:** Software that manages all other programs on a computer + and serves as an intermediary between users and the computer hardware, while + overseeing applications and system resources. +- **Security:** Tools to protect a computer system or network from theft, + unauthorized access, or damage to their hardware, software, or electronic + data, as well as from service disruption. +- **Web Servers:** Software to serve web pages, HTML files, and other assets to + users or other systems. +- **Web Analytics:** Tools to collect, measure, analyze, and report on web data + and website visitor engagement. \ No newline at end of file diff --git a/content/manuals/_index.md b/content/manuals/_index.md index 7ef904dfb11..31252a51cae 100644 --- a/content/manuals/_index.md +++ b/content/manuals/_index.md @@ -76,10 +76,6 @@ params: description: Commercial use licenses for Docker products. icon: card_membership link: /subscription/ - - title: Trusted content - description: Curated, high-quality content from trusted sources. - icon: verified - link: /trusted-content/ --- This section contains user guides on how to install, set up, configure, and use diff --git a/content/manuals/accounts/deactivate-user-account.md b/content/manuals/accounts/deactivate-user-account.md index 1985a8a3182..8639c5c43c5 100644 --- a/content/manuals/accounts/deactivate-user-account.md +++ b/content/manuals/accounts/deactivate-user-account.md @@ -18,7 +18,7 @@ Before deactivating your Docker account, ensure you meet the following requireme - For owners, you must leave your organization or company before deactivating your Docker account. To do this: 1. Sign in to the [Docker Admin Console](https://app.docker.com/admin). - 2. Select the organization you need to leave from the top-left drop-down menu. + 2. Select the organization you need to leave from the **Choose profile** page. 3. Find your username in the **Members** tab. 4. Select the **More options** menu and then select **Leave organization**. diff --git a/content/manuals/accounts/manage-account.md b/content/manuals/accounts/manage-account.md index ce47dcce0e7..9d28ded5cbc 100644 --- a/content/manuals/accounts/manage-account.md +++ b/content/manuals/accounts/manage-account.md @@ -63,6 +63,6 @@ For information on personal access tokens, see [Create and manage access tokens] You can take administrative actions for your account in Docker Home. -For more information on converting your account, see [Convert an account into an organization](../admin/convert-account.md). +For more information on converting your account, see [Convert an account into an organization](../admin/organization/convert-account.md). For information on deactivating your account, see [Deactivating a user account](./deactivate-user-account.md). diff --git a/content/manuals/admin/company/new-company.md b/content/manuals/admin/company/new-company.md index 079081701d3..9100cf85629 100644 --- a/content/manuals/admin/company/new-company.md +++ b/content/manuals/admin/company/new-company.md @@ -6,7 +6,9 @@ aliases: - /docker-hub/new-company/ --- -You can create a new company in the Docker Admin Console. Before you begin, make sure you're the owner of the organization you want to add to the new company. The organization also needs to have a Docker Business subscription. +You can create a new company in the Docker Admin Console. Before you begin, you must: +- Be the owner of the organization you want to add to your company +- Have a Docker Business subscription {{< include "admin-early-access.md" >}} @@ -14,16 +16,17 @@ You can create a new company in the Docker Admin Console. Before you begin, make To create a new company: -1. In the Admin Console, navigate to the organization you want to place under a company. The organization must have a Business subscription, and you must be an owner of the organization. -2. Under **Organization settings**, select **Company management**. -3. Select **Create a company**. -4. Enter a unique name for your company, then select **Continue**. +1. Sign in to the [Admin Console](https://app.docker.com/admin). +2. Select your organization you want to add to your company from the **Choose profile** page. +3. Under **Organization settings**, select **Company management**. +4. Select **Create a company**. +5. Enter a unique name for your company, then select **Continue**. > [!TIP] > > The name for your company can't be the same as an existing user, organization, or company namespace. -5. Review the company migration details and then select **Create company**. +6. Review the company migration details and then select **Create company**. For more information on how you can add organizations to your company, see [Add organizations to a company](./organizations.md#add-organizations-to-a-company). diff --git a/content/manuals/admin/company/organizations.md b/content/manuals/admin/company/organizations.md index 54e1ffe50a4..d5dba2d5c8f 100644 --- a/content/manuals/admin/company/organizations.md +++ b/content/manuals/admin/company/organizations.md @@ -1,7 +1,7 @@ --- -description: Learn how to manage organization in a company. +description: Learn how to manage organizations in a company. keywords: company, multiple organizations, manage organizations -title: Manage organizations +title: Manage company organizations --- You can manage the organizations in a company in the Docker Admin Console. @@ -11,40 +11,36 @@ You can manage the organizations in a company in the Docker Admin Console. ## View all organizations 1. Sign in to the [Admin Console](https://admin.docker.com). -2. In the left navigation, select your company in the drop-down menu. +2. Select your company on the **Choose profile** page. 3. Under **Organizations**, select **Overview**. +The organization overview page displays all organizations under your company. + ## Add seats to an organization -When you have a [self-serve](../../subscription/details.md#self-serve) subscription that has no pending subscription changes, you can add seats using the following steps. +When you have a [self-serve](../../subscription/details.md#self-serve) subscription that has no pending subscription changes, you can add seats using the following steps. If you have a sales-assisted subscription, you can contact Docker support or sales to add seats. -1. Sign in to the [Admin Console](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**. +For more information about adding seats, see [Manage seats](/manuals/subscription/manage-seats.md#add-seats). ## Add organizations to a company ->[!IMPORTANT] -> -> You must be a company owner to add an organization to a company. You must also be an organization owner of the organization you want to add. - -There is no limit to the number of organizations you can have under a company layer. All organizations must have a Business subscription. +You must be a company owner to add an organization to a company. You must also be an organization owner of the organization you want to add. There is no limit to the number of organizations you can have under a company layer. All organizations must have a Business subscription. ->[!IMPORTANT] +> [!IMPORTANT] > > Once you add an organization to a company, you can't remove it from the company. 1. Sign in to the [Admin Console](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. -5. Select **Add organization** to confirm. +2. Select your company on the **Choose profile** page. +3. Select **Organizations**, then **Overview**. +4. Select **Add organization**. +5. Choose the organization you want to add from the drop-down menu. +6. Select **Add organization** to confirm. ## Manage an organization 1. Sign in to the [Admin Console](https://admin.docker.com). -2. In the left navigation, select your company in the drop-down menu. +2. Select your company on the **Choose profile** page. 3. Select the organization that you want to manage. For more details about managing an organization, see [Organization administration](../organization/_index.md). diff --git a/content/manuals/admin/company/owners.md b/content/manuals/admin/company/owners.md index fdacaa77c8f..ba028a727aa 100644 --- a/content/manuals/admin/company/owners.md +++ b/content/manuals/admin/company/owners.md @@ -18,7 +18,7 @@ member in an organization, they don't occupy a seat. ## Add a company owner 1. Sign in to the [Admin Console](https://admin.docker.com). -2. In the left navigation, select your company in the drop-down menu. +2. Select your company on the **Choose profile** page. 3. Select **Company owners**. 4. Select **Add owner**. 5. Specify the user's Docker ID to search for the user. @@ -27,7 +27,7 @@ member in an organization, they don't occupy a seat. ## Remove a company owner 1. Sign in to the [Admin Console](https://admin.docker.com). -2. In the left navigation, select your company in the drop-down menu. +2. Select your company on the **Choose profile** page. 3. Select **Company owners**. 4. Select the **Action** icon in the row of the company owner that your want to remove. 5. Select **Remove as company owner**. diff --git a/content/manuals/admin/company/users.md b/content/manuals/admin/company/users.md index 5144baa442a..9f7b6ec1294 100644 --- a/content/manuals/admin/company/users.md +++ b/content/manuals/admin/company/users.md @@ -4,12 +4,12 @@ keywords: company, company users, users, admin, Admin Console title: Manage company users --- -{{< include "admin-early-access.md" >}} - You can manage users at the company-level in the Docker Admin Console. {{% admin-users product="admin" layer="company" %}} +{{< include "admin-early-access.md" >}} + ## 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](../organization/members.md#manage-members-on-a-team). diff --git a/content/manuals/admin/deactivate-account.md b/content/manuals/admin/deactivate-account.md index 585dcd1dd26..0aa4b64fe8c 100644 --- a/content/manuals/admin/deactivate-account.md +++ b/content/manuals/admin/deactivate-account.md @@ -8,7 +8,7 @@ aliases: You can deactivate an account at any time. This section describes the prerequisites and steps to deactivate an organization account. For information on deactivating a user account, see [Deactivate a user account](../accounts/deactivate-user-account.md). ->[!WARNING] +> [!WARNING] > > All Docker products and services that use your Docker account or organization account will be inaccessible after deactivating your account. @@ -44,7 +44,7 @@ Once you have completed all the previous steps, you can deactivate your organiza 4. Select **Deactivate organization**. {{< /tab >}} -{{< tab name="Hub" >}} +{{< tab name="Docker Hub" >}} 1. On Docker Hub, select **Organizations**. 2. Choose the organization you want to deactivate. diff --git a/content/manuals/admin/faqs/company-faqs.md b/content/manuals/admin/faqs/company-faqs.md index 26170740863..9e8efcbc7f2 100644 --- a/content/manuals/admin/faqs/company-faqs.md +++ b/content/manuals/admin/faqs/company-faqs.md @@ -32,7 +32,7 @@ You can add a maximum of 10 company owners to a single company account. ### Do company owners occupy a subscription seat? -Company owners don't occupy a seat in any organization unless they are added as +Company owners don't occupy a seat in any organization unless they are added as a member of the organization. Since company owners have the same access as organization owners for all organizations associated with the company, it is not necessary to add company owners to an organization. @@ -43,7 +43,7 @@ you're an organization owner. ### What permissions does the company owner have in the associated/nested organizations? -Company owners can navigate to the **Organizations** page to view all their nested organizations in a single location. They can also view or edit organization members and change single sign-on (SSO) and System for Cross-domain Identity Management (SCIM) settings. Changes to company settings impact all users in each organization under the company. See [Roles and permissions](../../security/for-admins/roles-and-permissions.md). +Company owners can navigate to the **Organizations** page to view all their nested organizations in a single location. They can also view or edit organization members and change single sign-on (SSO) and System for Cross-domain Identity Management (SCIM) settings. Changes to company settings impact all users in each organization under the company. For more information, see [Roles and permissions](../../security/for-admins/roles-and-permissions.md). ### What features are supported at the company level? @@ -64,9 +64,9 @@ A company name must be unique to that of its child organization. If a child orga ### How does a company owner add an organization to the company? -You can add organizations to a company in the [Admin Console](../../admin/company/organizations.md#add-organizations-to-a-company.md). +You can add organizations to a company in the Admin Console. For more information, see [Add organizations to a company](../../admin/company/organizations.md#add-organizations-to-a-company.md). -### How does a company owner manage SSO/SCIM settings from a company? +### How does a company owner manage SSO/SCIM settings for a company? See your [SCIM](scim.md) and [SSO](../../security/for-admins/single-sign-on/configure/_index.md) settings. @@ -74,6 +74,6 @@ See your [SCIM](scim.md) and [SSO](../../security/for-admins/single-sign-on/conf See [SCIM](scim.md) and [group mapping](../../security/for-admins/provisioning/group-mapping.md) for more information. -### What's the definition of a company vs an organization? +### What's the definition of a company versus an organization? A company is a collection of organizations that are managed together. An organization is a collection of repositories and teams that are managed together. diff --git a/content/manuals/admin/faqs/general-faqs.md b/content/manuals/admin/faqs/general-faqs.md index 7a8152bac7a..28b6c0f3128 100644 --- a/content/manuals/admin/faqs/general-faqs.md +++ b/content/manuals/admin/faqs/general-faqs.md @@ -13,8 +13,7 @@ aliases: ### What is a Docker ID? -A Docker ID is a username for your Docker account that lets you access Docker products. All you need is an email address to create a Docker ID, or you can sign up with your Google or GitHub account. Your Docker ID must be between 4 and 30 characters long, and can only contain -numbers and lowercase letters. You can't use any special characters or spaces. +A Docker ID is a username for your Docker account that lets you access Docker products. To create a Docker ID, you need an email address or you can sign up with your social or GitHub accounts. Your Docker ID must be between 4 and 30 characters long, and can only contain numbers and lowercase letters. You can't use any special characters or spaces. For more information, see [Docker ID](/accounts/create-account/). If your administrator enforces [single sign-on (SSO)](../../security/for-admins/single-sign-on/_index.md), this provisions a Docker ID for new users. @@ -66,6 +65,10 @@ information, see [Configure SSO](../../security/for-admins/single-sign-on/config ### What is a service account? +> [!IMPORTANT] +> +> As of December 10, 2024, service accounts are no longer available. Existing Service Account agreements will be honored until their current term expires, but new purchases or renewals of service accounts no longer available and customers must renew under a new subscription plan. It is recommended to transition to Organization Access Tokens (OATs), which can provide similar functionality. For more information, see [Organization access tokens (Beta)](/manuals/security/for-admins/access-tokens.md). + A [service account](../../docker-hub/service-accounts.md) is a Docker ID used for automated management of container images or containerized applications. Service accounts are typically used in automated workflows, and don't share Docker IDs with the members in the Team or Business plan. Common use cases for service accounts include mirroring content on Docker Hub, or tying in image pulls from your CI/CD process. ### Can I delete or deactivate a Docker account for another user? @@ -76,4 +79,4 @@ If the user is a member of your organization, you can remove the user from your ### How do I manage settings for a user account? -You can manage your account settings any time when you sign in to your [Docker account](https://app.docker.com/login). In Docker Home, select your avatar in the top-right navigation, then select **My Account**. You can also access this menu from any Docker web applications when you're signed in to your account. See [Manage your Docker account](/accounts/manage-account). If your account is associated with an organization that uses SSO, you may have limited access to the settings that you can control. +You can manage your account settings anytime when you sign in to your [Docker account](https://app.docker.com/login). In Docker Home, select your avatar in the top-right navigation, then select **My Account**. You can also access this menu from any Docker web applications when you're signed in to your account. See [Manage your Docker account](/accounts/manage-account). If your account is associated with an organization that uses SSO, you may have limited access to the settings that you can control. diff --git a/content/manuals/admin/faqs/organization-faqs.md b/content/manuals/admin/faqs/organization-faqs.md index faf1a79f45e..0f6261fcb6b 100644 --- a/content/manuals/admin/faqs/organization-faqs.md +++ b/content/manuals/admin/faqs/organization-faqs.md @@ -12,7 +12,7 @@ aliases: ### What if the Docker ID I want for my organization or company is taken? -All Docker IDs are first-come, first-served except for companies that have a US Trademark on a username. If you have a trademark for your namespace, [Docker Support](https://hub.docker.com/support/contact/) can retrieve the Docker ID for you. +All Docker IDs are first-come, first-served except for companies that have a U.S. Trademark on a username. If you have a trademark for your namespace, [Docker Support](https://hub.docker.com/support/contact/) can retrieve the Docker ID for you. ### How do I add an organization owner? @@ -24,11 +24,11 @@ If your organization uses a Software Asset Management tool, you can use it to fi ### Do users first need to authenticate with Docker before an owner can add them to an organization? -No. Organization owners can invite users with their email address, and also assign them to a team during the invite process. +No. Organization owners can invite users with their email addresses, and also assign them to a team during the invite process. ### Can I force my organization's members to authenticate before using Docker Desktop and are there any benefits? -Yes. You can [enforce sign-in](../../security/for-admins/enforce-sign-in/_index.md) and some benefits are: +Yes. You can [enforce sign-in](../../security/for-admins/enforce-sign-in/_index.md). Some benefits of enforcing sign-in are: - Administrators can enforce features like [Image Access Management](/manuals/security/for-admins/hardened-desktop/image-access-management.md) and [Registry Access Management](../../security/for-admins/hardened-desktop/registry-access-management.md). - Administrators can ensure compliance by blocking Docker Desktop usage for users who don't sign in as members of the organization. @@ -46,9 +46,7 @@ revert it to a personal user account. For prerequisites and instructions, see ### Our users create Docker Hub accounts through self-service. How do we know when the total number of users for the requested licenses has been met? Is it possible to add more members to the organization than the total number of licenses? -There isn't any automatic notification when the total number of users for the requested licenses has been met. However, if the number of team -members exceed the number of licenses, you will receive an error informing you -to contact the administrator due to lack of seats. You can [add seats](../../subscription/manage-seats.md) if needed. +There isn't any automatic notification when the total number of users for the requested licenses has been met. However, if the number of team members exceed the number of licenses, you will receive an error informing you to contact the administrator due to lack of seats. You can [add seats](../../subscription/manage-seats.md) if needed. ### How can I merge organization accounts? @@ -66,13 +64,13 @@ Yes. Organization owners will take up a seat. ### What is the difference between user, invitee, seat, and member? -User may refer to a Docker user with a Docker ID. +User refers to a Docker user with a Docker ID. -An invitee is a user that an administrator has invited to join an organization, but has not yet accepted their invitation. +An invitee is a user that an administrator has invited to join an organization but has not yet accepted their invitation. -Seats is the number of planned members within an organization. +Seats are the number of planned members within an organization. -Member may refer to a user that has received and accepted an invitation to join an organization. Member can also refer to a member of a team within an organization. +Member may refer to a user who has received and accepted an invitation to join an organization. Member can also refer to a member of a team within an organization. ### If there are two organizations and a user belongs to both organizations, do they take up two seats? diff --git a/content/manuals/admin/images/team-repo-permission.png b/content/manuals/admin/images/team-repo-permission.png deleted file mode 100644 index e5fab746671..00000000000 Binary files a/content/manuals/admin/images/team-repo-permission.png and /dev/null differ diff --git a/content/manuals/admin/convert-account.md b/content/manuals/admin/organization/convert-account.md similarity index 99% rename from content/manuals/admin/convert-account.md rename to content/manuals/admin/organization/convert-account.md index f259f171852..aaf8d5f3219 100644 --- a/content/manuals/admin/convert-account.md +++ b/content/manuals/admin/organization/convert-account.md @@ -2,6 +2,7 @@ description: Convert your Docker Hub user account into an organization title: Convert an account into an organization keywords: docker hub, hub, organization, convert account, migrate account +weight: 35 aliases: - /docker-hub/convert-account/ --- @@ -12,7 +13,7 @@ When you convert a user account to an organization, the account is migrated to a > [!IMPORTANT] > -> Once you convert your account to an organization, you can’t revert it to a user account. +> Once you convert your account to an organization, you can’t revert it to a user account. ## Prerequisites diff --git a/content/manuals/admin/organization/general-settings.md b/content/manuals/admin/organization/general-settings.md index 9b26bc8b0ef..ada92c672a6 100644 --- a/content/manuals/admin/organization/general-settings.md +++ b/content/manuals/admin/organization/general-settings.md @@ -11,7 +11,7 @@ This section describes how to manage organization settings in the Docker Admin C ## Configure general information -General organization information appears on your organization landing page in Docker Hub. +General organization information appears on your organization landing page in the Admin Console. This information includes: - Organization Name @@ -23,7 +23,7 @@ This information includes: To edit this information: 1. Sign in to the [Admin Console](https://admin.docker.com). -2. In the left navigation, select your organization in the drop-down menu. +2. Select your company on the **Choose profile** page. 3. Under **Organization settings**, select **General**. 4. Specify the organization information and select **Save**. diff --git a/content/manuals/admin/organization/insights.md b/content/manuals/admin/organization/insights.md index 5b63d23cf5a..478f8101b47 100644 --- a/content/manuals/admin/organization/insights.md +++ b/content/manuals/admin/organization/insights.md @@ -15,37 +15,39 @@ productivity and efficiency across the organization. Key benefits include: -* Uniform working environment. Establish and maintain standardized +- Uniform working environment. Establish and maintain standardized configurations across teams. -* Best practices. Promote and enforce usage guidelines to ensure optimal +- Best practices. Promote and enforce usage guidelines to ensure optimal performance. -* Increased visibility. Monitor and drive adoption of organizational +- Increased visibility. Monitor and drive adoption of organizational configurations and policies. -* Optimized license use. Ensure that developers have access to advanced +- Optimized license use. Ensure that developers have access to advanced features provided by a Docker subscription. ## View Insights for organization users +{{< include "admin-early-access.md" >}} + 1. Go to the [Admin Console](https://app.docker.com/admin/) and sign in to an account that is an organization owner. -2. In the Admin Console, select your organization from the drop-down in the left - navigation. +2. Select your company on the **Choose profile** page. 3. Select **Insights**. 4. On the **Insights** page, select the period of time for the data. > [!NOTE] +> > Insights data is not real-time and is updated daily. At the top-right of the > Insights page, view the **Last updated** date to understand when the data was > last updated. You can view data in the following charts: - * [Docker Desktop users](#docker-desktop-users) - * [Builds](#builds) - * [Containers](#containers) - * [Docker Desktop usage](#docker-desktop-usage) - * [Docker Hub images](#docker-hub-images) - * [Extensions](#extensions) + - [Docker Desktop users](#docker-desktop-users) + - [Builds](#builds) + - [Containers](#containers) + - [Docker Desktop usage](#docker-desktop-usage) + - [Docker Hub images](#docker-hub-images) + - [Extensions](#extensions) ### Docker Desktop users @@ -57,13 +59,12 @@ counts. The chart contains the following data. -| Data | Description | +| Data | Description | |:-----------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Total active users | The number of users that have actively used Docker Desktop and either signed in with a Docker account that has a license in your organization or signed in to a Docker account with an email address from a domain associated with your organization.

Users who don’t sign in to an account associated with your organization are not represented in the data. To ensure users sign in with an account associated with your organization, you can [enforce sign-in](/security/for-admins/enforce-sign-in/). | -| Active with license | The number of users that have actively used Docker Desktop and have signed in to a Docker account with a license in your organization. | -| Active without license | The number of users that have actively used Docker Desktop, are linked to a Docker account with an email address from a domain associated with your organization, and don’t have a license assigned to their account.

Users without a license don’t receive the benefits of your subscription. You can use [domain audit](/security/for-admins/domain-audit/) to identify users without a license. You can also use [Just-in-Time provisioning](/security/for-admins/provisioning/just-in-time/) or [SCIM](/security/for-admins/provisioning/scim/) to help automatically provision users with a license. Note that when SSO is configured and enforced, active without license will be 0. | -| Users opted out of analytics | The number of users that are a member of your organization that have opted out of sending analytics.

When users opt out of sending analytics, you won't see any of their data in Insights. To ensure that the data includes all users, you can use [Settings Management](/desktop/hardened-desktop/settings-management/) to set `analyticsEnabled` for all your users. | -| Active users (graph) | The view over time for total active users. | +| Active user | The number of users that have actively used Docker Desktop and either signed in with a Docker account that has a license in your organization or signed in to a Docker account with an email address from a domain associated with your organization.

Users who don’t sign in to an account associated with your organization are not represented in the data. To ensure users sign in with an account associated with your organization, you can [enforce sign-in](/security/for-admins/enforce-sign-in/). | +| Total organization members | The number of users that have used Docker Desktop, regardless of their Insights activity. | +| Users opted out of analytics | The number of users that are a member of your organization that have opted out of sending analytics.

When users opt out of sending analytics, you won't see any of their data in Insights. To ensure that the data includes all users, you can use [Settings Management](/desktop/hardened-desktop/settings-management/) to set `analyticsEnabled` for all your users. | +| Active users (graph) | The view over time for total active users. | ### Builds diff --git a/content/manuals/admin/organization/manage-a-team.md b/content/manuals/admin/organization/manage-a-team.md index 55fad01c3a6..efc865e0690 100644 --- a/content/manuals/admin/organization/manage-a-team.md +++ b/content/manuals/admin/organization/manage-a-team.md @@ -10,37 +10,36 @@ aliases: You can create teams for your organization in Docker Hub and the Docker Admin Console. You can [configure repository access for a team](#configure-repository-permissions-for-a-team) in Docker Hub. -A team is a group of Docker users that belong to an organization. An -organization can have multiple teams. An -organization owner can then create new teams and add members to an existing team -using their Docker ID or email address and by selecting a team the user should be part of. Members aren't required to be part of a team to be associated with an organization. +A team is a group of Docker users that belong to an organization. An organization can have multiple teams. An organization owner can then create new teams and add members to an existing team using their Docker ID or email address and by selecting a team the user should be part of. Members aren't required to be part of a team to be associated with an organization. The organization owner can add additional organization owners to help them manage users, teams, and repositories in the organization by assigning them the owner role. ## Organization owner -An organization owner is an administrator who is responsible to manage -repositories and add team members to the organization. They have full access to -private repositories, all teams, billing information, and org settings. An org -owner can also specify [permissions](#permissions-reference) for each team in -the organization. Only an org owner can enable [SSO](../../security/for-admins/single-sign-on/_index.md) -for -the organization. When SSO is enabled for your organization, the org owner can +An organization owner is an administrator who has the following permissions: + +- Manage repositories and add team members to the organization. +- Access private repositories, all teams, billing information, and organization settings. +- Specify [permissions](#permissions-reference) for each team in the organization. +- Enable [SSO](../../security/for-admins/single-sign-on/_index.md) for the organization. + +When SSO is enabled for your organization, the organization owner can also manage users. Docker can auto-provision Docker IDs for new end-users or users who'd like to have a separate Docker ID for company use through SSO enforcement. -The org owner can also add additional org owners to help them manage users, teams, and repositories in the organization. +The organization owner can also add additional organization owners to help them manage users, teams, and repositories in the organization. ## Create a team {{< tabs >}} {{< tab name="Docker Hub" >}} -1. Go to **Organizations** in Docker Hub, and select your organization. -2. Select the **Teams** tab and then select **Create Team**. -3. Fill out your team's information and select **Create**. -4. [Add members to your team](members.md#add-a-member-to-a-team). +1. Sign in to [Docker Hub](https://hub.docker.com). +2. Select **Organizations** and choose your organization. +3. Select the **Teams** tab and then select **Create Team**. +4. Fill out your team's information and select **Create**. +5. [Add members to your team](members.md#add-a-member-to-a-team). {{< /tab >}} {{< tab name="Admin Console" >}} @@ -61,19 +60,18 @@ The org owner can also add additional org owners to help them manage users, team Organization owners can configure repository permissions on a per-team basis. For example, you can specify that all teams within an organization have "Read and Write" access to repositories A and B, whereas only specific teams have "Admin" -access. Note that org owners have full administrative access to all repositories within the organization. +access. Note that organization owners have full administrative access to all repositories within the organization. -To give a team access to a repository +To give a team access to a repository: -1. Navigate to **Organizations** in Docker Hub, and select your organization. -2. Select the **Teams** tab and select the team that you'd like to configure repository access to. -3. Select the **Permissions** tab and select a repository from the +1. Sign in to [Docker Hub](https://hub.docker.com). +2. Select **Organizations** and choose your organization. +3. Select the **Teams** tab and select the team that you'd like to configure repository access to. +4. Select the **Permissions** tab and select a repository from the **Repository** drop-down. -4. Choose a permission from the **Permissions** drop-down list and select +5. Choose a permission from the **Permissions** drop-down list and select **Add**. - ![Team Repo Permissions](../images/team-repo-permission.png) - Organization owners can also assign members the editor role to grant partial administrative access. See [Roles and permissions](../../security/for-admins/roles-and-permissions.md) for more about the editor role. ### Permissions reference @@ -110,8 +108,10 @@ you automatically have "Read-only" permissions: To view a team's permissions across all repositories: -1. Open **Organizations** > **_Your Organization_** > **Teams** > **_Team Name_**. -2. Select the **Permissions** tab, where you can view the repositories this team can access. +1. Sign in to [Docker Hub](https://hub.docker.com). +2. Select **Organizations** and choose your organization. +3. Select **Teams** and choose your team name. +4. Select the **Permissions** tab, where you can view the repositories this team can access. ## Delete a team @@ -120,19 +120,20 @@ Organization owners can delete a team in Docker Hub or Admin Console. When you r {{< tabs >}} {{< tab name="Docker Hub" >}} -1. Go to **Organizations** in Docker Hub, and select your organization. -2. Select the **Teams** tab. -3. Select the name of the team that you want to delete. -4. Select **Settings**. -5. Select **Delete Team**. -6. Review the confirmation message, then select **Delete**. +1. Sign in to [Docker Hub](https://hub.docker.com). +2. Select **Organizations** and choose your organization. +3. Select the **Teams** tab. +4. Select the name of the team that you want to delete. +5. Select **Settings**. +6. Select **Delete Team**. +7. Review the confirmation message, then select **Delete**. {{< /tab >}} {{< tab name="Admin Console" >}} {{< include "admin-early-access.md" >}} -1. In Admin Console, select your organization. +1. In the [Admin Console](https://app.docker.com/admin), select your organization. 2. In the **User management** section, select **Teams**. 3. Select the **Actions** icon next to the name of the team you want to delete. 4. Select **Delete team**. diff --git a/content/manuals/admin/organization/members.md b/content/manuals/admin/organization/members.md index 25d78ce890a..fdb1e19e14c 100644 --- a/content/manuals/admin/organization/members.md +++ b/content/manuals/admin/organization/members.md @@ -70,8 +70,7 @@ To resend an invitation from Docker Hub: To resend an invitation from the Admin Console: -1. Open the [Admin Console](https://app.docker.com/admin) and select your organization from -top-left drop-down menu. +1. In the [Admin Console](https://app.docker.com/admin), select your organization. 2. Select **Members**. 3. Select the **action menu** next to the invitee and select **Resend invitation**. 4. Select **Invite** to confirm. @@ -98,8 +97,7 @@ To remove a member's invitation from Docker Hub: To remove an invitation from the Admin Console: -1. Open the [Admin Console](https://app.docker.com/admin) and select your organization from -top-left drop-down menu. +1. In the [Admin Console](https://app.docker.com/admin), select your organization. 2. Select **Members**. 3. Select the **action menu** next to the invitee and select **Remove invitee**. 4. Select **Remove** to confirm. @@ -207,7 +205,25 @@ Owners can export a CSV file containing all members. The CSV file for a company - Invited to Organizations: All organizations the user is an invitee of within a company - Account Created: The time and date when the user account was created -To export a CSV file of the members: +{{< tabs >}} +{{< tab name="Docker Hub" >}} + +To export a CSV file of your members: + 1. Sign in to [Docker Hub](https://hub.docker.com). 2. Select **Organizations**, your organization, and then **Members**. -3. Select the **Action** icon and then select **Export users as CSV**. \ No newline at end of file +3. Select the **Action** icon and then select **Export users as CSV**. + +{{< /tab >}} +{{< tab name="Admin Console" >}} + +{{< include "admin-early-access.md" >}} + +To export a CSV file of your members: + +1. In the [Admin Console](https://app.docker.com/admin), select your organization. +2. Select **Members**. +3. Select the **download** icon to export a CSV file of all members. + +{{< /tab >}} +{{< /tabs >}} \ No newline at end of file diff --git a/content/manuals/admin/organization/onboard.md b/content/manuals/admin/organization/onboard.md index 6d39acb96df..74a31e69bea 100644 --- a/content/manuals/admin/organization/onboard.md +++ b/content/manuals/admin/organization/onboard.md @@ -15,9 +15,9 @@ aliases: Learn how to onboard your organization using Docker Hub or the Docker Admin Console. -Onboarding your organization lets administrators gain visibility into the activity of your users and enforce security settings. In addition, members of your organization receive increased pull limits and other organization wide benefits. For more details, see [Docker subscriptions and features](../../subscription/details.md). +Onboarding your organization lets administrators gain visibility into user activity and enforce security settings. In addition, members of your organization receive increased pull limits and other organization wide benefits. For more details, see [Docker subscriptions and features](../../subscription/details.md). -In this guide, you'll learn how to get started with the following: +In this guide, you'll learn how to do the following: - Identify your users to help you efficiently allocate your subscription seats - Invite members and owners to your organization @@ -27,7 +27,8 @@ In this guide, you'll learn how to get started with the following: ## Prerequisites Before you start to onboard your organization, ensure that you: -- Have a Docker Team or Business subscription. See [Pricing & Subscriptions](https://www.docker.com/pricing/) for details. + +- Have a Docker Team or Business subscription. See [Docker Pricing](https://www.docker.com/pricing/) for details. > [!NOTE] > @@ -35,24 +36,24 @@ Before you start to onboard your organization, ensure that you: - Familiarize yourself with Docker concepts and terminology in the [glossary](/glossary/) and [FAQs](/faq/admin/general-faqs/). -## Step 1: Identify your Docker users and their Docker accounts +## Step 1: Identify your Docker users Identifying your users will ensure that you allocate your subscription seats efficiently and that all your Docker users receive the benefits of your subscription. 1. Identify the Docker users in your organization. - - If your organization uses device management software, like MDM or JAMF, you may use the device management software to help identify Docker users. See your device management software's documentation for details. You can identify Docker users by checking if Docker Desktop is installed at the following location on each user's machine: + - If your organization uses device management software, like MDM or Jamf, you may use the device management software to help identify Docker users. See your device management software's documentation for details. You can identify Docker users by checking if Docker Desktop is installed at the following location on each user's machine: - Mac: `/Applications/Docker.app` - Windows: `C:\Program Files\Docker\Docker` - Linux: `/opt/docker-desktop` - If your organization doesn't use device management software or your users haven't installed Docker Desktop yet, you may survey your users. -2. Instruct all your Docker users in your organization to update their existing Docker account's email address to an address that's in your organization's domain, or to create a new account using an email address in your organization's domain. +2. Instruct all your organization's Docker users to update their existing Docker account's email address to an address that's in your organization's domain, or to create a new account using an email address in your organization's domain. - To update an account's email address, instruct your users to sign in to [Docker Hub](https://hub.docker.com), and update the email address to their email address in your organization's domain. - To create a new account, instruct your users to go [sign up](https://hub.docker.com/signup) using their email address in your organization's domain. 3. Ask your Docker sales representative or [contact sales](https://www.docker.com/pricing/contact-sales/) to get a list of Docker accounts that use an email address in your organization's domain. ## Step 2: Invite owners -When you create an organization, you are the only owner. You may optionally add additional owners. Owners can help you onboard and manage your organization. +When you create an organization, you are the only owner. It is optional to add additional owners. Owners can help you onboard and manage your organization. To add an owner, invite a user and assign them the owner role. For more details, see [Invite members](/admin/organization/members/). @@ -68,22 +69,22 @@ Configuring SSO and SCIM is optional and only available to Docker Business subsc You can manage your members in your identity provider and automatically provision them to your Docker organization with SSO and SCIM. See the following for more details. - [Configure SSO](/manuals/security/for-admins/single-sign-on/configure.md) to authenticate and add members when they sign in to Docker through your identity provider. - - Optional: [Enforce SSO](/manuals/security/for-admins/single-sign-on/connect.md) to ensure that when users sign in to Docker, they must use SSO. + - Optional. [Enforce SSO](/manuals/security/for-admins/single-sign-on/connect.md) to ensure that when users sign in to Docker, they must use SSO. + > [!NOTE] > > Enforcing single sign-on (SSO) and [Step 5: Enforce sign-in for Docker > Desktop](#step-5-enforce-sign-in-for-docker-desktop) are different > features. For more details, see > [Enforcing sign-in versus enforcing single sign-on (SSO)](/security/for-admins/enforce-sign-in/#enforcing-sign-in-versus-enforcing-single-sign-on-sso). + - [Configure SCIM](/security/for-admins/provisioning/scim/) to automatically provision, add, and de-provision members to Docker through your identity provider. ## Step 5: Enforce sign-in for Docker Desktop By default, members of your organization can use Docker Desktop without signing in. When users don’t sign in as a member of your organization, they don’t -receive the [benefits of your organization’s subscription](../../subscription/details.md) and they can circumvent -[Docker’s security features](/security/for-admins/hardened-desktop/) for your -organization. +receive the [benefits of your organization’s subscription](../../subscription/details.md) and they can circumvent [Docker’s security features](/security/for-admins/hardened-desktop/). There are multiple ways you can enforce sign-in, depending on your company's set up and preferences: diff --git a/content/manuals/admin/organization/orgs.md b/content/manuals/admin/organization/orgs.md index 5cab7b539d3..426a2d80d1e 100644 --- a/content/manuals/admin/organization/orgs.md +++ b/content/manuals/admin/organization/orgs.md @@ -10,68 +10,95 @@ aliases: This section describes how to create an organization. Before you begin: -- You need a [Docker ID](/accounts/create-account/). -- Review the [Docker subscriptions and features](../../subscription/details.md) to determine what plan to choose for your organization. +- You need a [Docker ID](/accounts/create-account/) +- Review the [Docker subscriptions and features](../../subscription/details.md) to determine what plan to choose for your organization ## Create an organization -There are multiple ways to create an organization. You can create a brand new -organization using the **Create Organization** option in Docker Hub, or you can -convert an existing user account to an organization. The following section -contains instructions on how to create a new organization. For prerequisites and +There are multiple ways to create an organization. You can either: +- Create a new organization using the **Create Organization** option in Docker Hub +- Convert an existing user account to an organization + +The following section contains instructions on how to create a new organization. For prerequisites and detailed instructions on converting an existing user account to an organization, see -[Convert an account into an organization](../convert-account.md). +[Convert an account into an organization](/manuals/admin/organization/convert-account.md). -To create an organization: +{{< tabs >}} +{{< tab name="Docker Hub" >}} 1. Sign in to [Docker Hub](https://hub.docker.com/) using your Docker ID, your email address, or your social provider. -2. Select **Organizations** and then **Create Organization** to create a new - organization. -3. Choose a plan for your organization and select **Buy Now**. See -[Docker Pricing](https://www.docker.com/pricing/) -for details on the features offered in the Team and Business plan. +2. Select **Organizations** and then **Create Organization** to create a new organization. +3. Choose a plan for your organization, a billing cycle, and specify how many seats you need. See [Docker Pricing](https://www.docker.com/pricing/) for details on the features offered in the Team and Business plan. +4. Select **Continue to profile**. +5. Enter an **Organization namespace**. This is the official, unique name for +your organization in Docker Hub. It's not possible to change the name of the +organization after you've created it. > [!NOTE] > - > Selecting **Buy Now** isn't an obligation to pay. You can complete - > this step without incurring a payment. + > You can't use the same name for the organization and your Docker ID. If you want to use your Docker ID as the organization name, then you must first [convert your account into an organization](/manuals/admin/organization/convert-account.md). -4. Enter a name for your organization. This is the official, unique name for +6. Enter your **Company name**. This is the full name of your company. Docker +displays the company name on your organization page and in the details of any +public images you publish. You can update the company name anytime by navigating +to your organization's **Settings** page. +7. Select **Continue to billing** to continue. +8. Enter your organization's billing information and select **Continue to payment** to continue to the billing portal. +9. Provide your card details and select **Purchase**. + +You've now created an organization. + +{{< /tab >}} +{{< tab name="Admin Console" >}} + +{{< include "admin-early-access.md" >}} + +To create an organization: + +1. Sign in to [Docker Home](https://app.docker.com/). +2. Under Settings and administration, select **Go to Admin Console**. +3. Select the **Organization** drop-down in the left-hand navigation and then **Create Organization**. +4. Choose a plan for your organization, a billing cycle, and specify how many seats you need. See [Docker Pricing](https://www.docker.com/pricing/) for details on the features offered in the Team and Business plan. +5. Select **Continue to profile**. +6. Enter an **Organization namespace**. This is the official, unique name for your organization in Docker Hub. It's not possible to change the name of the organization after you've created it. > [!NOTE] > - > You can't use the same name for the organization and your Docker ID. If you want to use your Docker ID as the organization name, then you must first [convert your account into an organization](../convert-account.md). + > You can't use the same name for the organization and your Docker ID. If you want to use your Docker ID as the organization name, then you must first [convert your account into an organization](/manuals/admin/organization/convert-account.md). -5. Enter the name of your company. This is the full name of your company. Docker +7. Enter your **Company name**. This is the full name of your company. Docker displays the company name on your organization page and in the details of any public images you publish. You can update the company name anytime by navigating to your organization's **Settings** page. -6. Select **Purchase** to continue. -7. Enter the billing information for your organization. -8. Select **Submit** to continue to the billing portal. -9. In the billing portal, select **Qty** to update the number of seats you require, then select **Update**. -10. (Optional) Select annual or monthly billing cycle. -11. Follow the on-screen instructions to pay for your subscription. +8. Select **Continue to billing** to continue. +9. Enter your organization's billing information and select **Continue to payment** to continue to the billing portal. +10. Provide your card details and select **Purchase**. You've now created an organization. +{{< /tab >}} +{{< /tabs >}} + ## View an organization +{{< tabs >}} +{{< tab name="Docker Hub" >}} + To view an organization: -1. Sign in to Docker Hub with a user account that is a member of any team in the - organization. +1. Sign in to [Docker Hub](https://hub.docker.com) with a user account that is a member of any team in the + organization. > [!NOTE] > - > You can't _directly_ log in to an organization. This is especially + > You can't *directly* sign in to an organization. This is especially > important to note if you create an organization by - [converting a user account](../convert-account.md), as conversion means you lose the ability to log into that - > "account", since it no longer exists. To view the organization you - > need to log in with the new owner account assigned during the - > conversion or another account that was added as a member. If you + [converting a user account](/manuals/admin/organization/convert-account.md), as conversion means you lose the ability to log into that + > "account", since it no longer exists. To view the organization you + > need to sign in with the new owner account assigned during the + > conversion or another account that was added as a member. If you > don't see the organization after logging in, > then you are neither a member or an owner of it. An organization > administrator needs to add you as a member of the organization. @@ -79,7 +106,7 @@ To view an organization: 2. Select **Organizations** in the top navigation bar, then choose your organization from the list. -The organization landing page displays various options that allow you to +The organization landing page displays various options that let you to configure your organization. - **Members**: Displays a list of team members. You @@ -98,7 +125,7 @@ configure your organization. details. - **Settings**: Displays information about your - organization, and allows you to view and change your repository privacy + organization, and you to view and change your repository privacy settings, configure org permissions such as [Image Access Management](/manuals/security/for-admins/hardened-desktop/image-access-management.md), configure notification settings, and [deactivate](../deactivate-account.md#deactivate-an-organization) You can also update your organization name and company name that appear on your organization landing page. You must be an owner to access the organization's **Settings** page. @@ -106,6 +133,38 @@ configure your organization. - **Billing**: Displays information about your existing [Docker subscription (plan)](../../subscription/_index.md), including the number of seats and next payment due date. For how to access the billing history and payment methods for your organization, see [View billing history](../../billing/history.md). +{{< /tab >}} +{{< tab name="Admin Console" >}} + +{{< include "admin-early-access.md" >}} + +To view an organization in the Admin Console: + +1. Sign in to [Docker Home](https://app.docker.com). +2. Under Settings and administration, select **Go to Admin Console**. +3. Select your organization from the **Organization** drop-down in the left-hand navigation. + +The Admin Console displays various options that let you to +configure your organization. + +- **Members**: Displays a list of team members. You + can invite new members using the **Invite members** button. See [Manage members](./members.md) for details. + +- **Teams**: Displays a list of existing teams and the number of + members in each team. See [Create a team](./manage-a-team.md) for details. + +- **Activity** Displays the audit logs, a chronological list of activities that + occur at organization and repository levels. It provides the org owners a + report of all their team member activities. See [Audit logs](./activity-logs.md) for + details. + +- **Security and access**: Manage security settings. For more information, see [Security](/manuals/security/_index.md). + +- **Organization settings**: Update general settings, manage your company settings, or [deactivate your organization](/manuals/admin/deactivate-account.md). + +{{< /tab >}} +{{< /tabs >}} + ## Merge organizations > [!WARNING] diff --git a/content/manuals/build-cloud/ci.md b/content/manuals/build-cloud/ci.md index 03b2064cc85..bd66ec53f42 100644 --- a/content/manuals/build-cloud/ci.md +++ b/content/manuals/build-cloud/ci.md @@ -74,7 +74,6 @@ jobs: - name: Set up Docker Buildx uses: docker/setup-buildx-action@v3 with: - version: "lab:latest" driver: cloud endpoint: "/default" install: true diff --git a/content/manuals/build/builders/_index.md b/content/manuals/build/builders/_index.md index e1a9334eabe..c926822df0e 100644 --- a/content/manuals/build/builders/_index.md +++ b/content/manuals/build/builders/_index.md @@ -65,6 +65,48 @@ To switch between builders, use the `docker buildx use ` command. After running this command, the builder you specify is automatically selected when you invoke builds. +### Difference between `docker build` and `docker buildx build` + +Even though `docker build` is an alias for `docker buildx build`, there are +subtle differences between the two commands. With Buildx, the build client and +the and daemon (BuildKit) are decoupled. This means you can use multiple +builders from a single client, even remote ones. + +The `docker build` command always defaults to using the default builder that +comes bundled with the Docker Engine, for ensuring backwards compatibility with +older versions of the Docker CLI. The `docker buildx build` command, on the +other hand, checks whether you've set a different builder as the default +builder before it sends your build to BuildKit. + +To use the `docker build` command with a non-default builder, you must either: + +- Specify the builder explicitly, using the `--builder` flag or the `BUILDX_BUILDER` environment variable: + + ```console + $ BUILDX_BUILDER=my_builder docker build . + $ docker build --builder my_builder . + ``` + +- Configure Buildx as the default client by running the following command: + + ```console + $ docker buildx install + ``` + + This updates your [Docker CLI configuration file](/reference/cli/docker/_index.md#configuration-files) + to ensure all of your build-related commands are routed via Buildx. + + > [!TIP] + > To undo this change, run `docker buildx uninstall`. + + + +In general, we recommend that you use the `docker buildx build` command when +you want to use custom builders. This ensures that your [selected +builder](#selected-builder) configuration is interpreted correctly. + + + ## Additional information - For information about how to interact with and manage builders, diff --git a/content/manuals/build/builders/drivers/kubernetes.md b/content/manuals/build/builders/drivers/kubernetes.md index 12da0a79ce4..f15f83f9ebe 100644 --- a/content/manuals/build/builders/drivers/kubernetes.md +++ b/content/manuals/build/builders/drivers/kubernetes.md @@ -43,7 +43,7 @@ can pass to `--driver-opt`: | `limits.memory` | Memory size | | Sets the limit memory value specified in bytes or with a valid suffix. For example `requests.memory=500Mi` or `requests.memory=4G` | | `limits.ephemeral-storage` | Storage size | | Sets the limit ephemeral-storage value specified in bytes or with a valid suffix. For example `requests.ephemeral-storage=100M` | | `nodeselector` | CSV string | | Sets the pod's `nodeSelector` label(s). See [node assignment][2]. | -| `annotation` | CSV string | | Sets additional annotations on the deployments and pods. | +| `annotations` | CSV string | | Sets additional annotations on the deployments and pods. | | `labels` | CSV string | | Sets additional labels on the deployments and pods. | | `tolerations` | CSV string | | Configures the pod's taint toleration. See [node assignment][2]. | | `serviceaccount` | String | | Sets the pod's `serviceAccountName`. | diff --git a/content/manuals/build/building/base-images.md b/content/manuals/build/building/base-images.md index 96174bd03d1..32ae78d8c46 100644 --- a/content/manuals/build/building/base-images.md +++ b/content/manuals/build/building/base-images.md @@ -20,10 +20,12 @@ FROM debian For most cases, you don't need to create your own base image. Docker Hub contains a vast library of Docker images that are suitable for use as a base -image in your build. [Docker Official Images](../../trusted-content/official-images/_index.md) +image in your build. [Docker Official +Images](../../docker-hub/image-library/trusted-content.md#docker-official-images) are specifically designed as a set of hardened, battle-tested images that support a wide variety of platforms, languages, and frameworks. There are also -[Docker Verified Publisher](https://hub.docker.com/search?q=&image_filter=store) +[Docker Verified +Publisher](../../docker-hub/image-library/trusted-content.md#verified-publisher-images) images, created by trusted publishing partners, verified by Docker. ## Create a base image @@ -123,4 +125,4 @@ For more information about building images and writing Dockerfiles, see: * [Dockerfile reference](/reference/dockerfile.md) * [Dockerfile best practices](/manuals/build/building/best-practices.md) -* [Docker Official Images](../../trusted-content/official-images/_index.md) +* [Docker Official Images](../../docker-hub/image-library/trusted-content.md#docker-official-images) diff --git a/content/manuals/build/building/best-practices.md b/content/manuals/build/building/best-practices.md index 7661677ebb4..343c42b62c5 100644 --- a/content/manuals/build/building/best-practices.md +++ b/content/manuals/build/building/best-practices.md @@ -57,7 +57,7 @@ it small. - [Docker-Sponsored Open Source](https://hub.docker.com/search?image_filter=open_source) are published and maintained by open source projects sponsored by Docker - through an [open source program](../../trusted-content/dsos-program). + through an [open source program](../../docker-hub/image-library/trusted-content.md#docker-sponsored-open-source-software-images). When you pick your base image, look out for the badges indicating that the image is part of these programs. diff --git a/content/manuals/build/cache/garbage-collection.md b/content/manuals/build/cache/garbage-collection.md index d0b1e59b823..9e35068d24c 100644 --- a/content/manuals/build/cache/garbage-collection.md +++ b/content/manuals/build/cache/garbage-collection.md @@ -8,36 +8,155 @@ aliases: While [`docker builder prune`](/reference/cli/docker/builder/prune.md) or [`docker buildx prune`](/reference/cli/docker/buildx/prune.md) -commands run at once, garbage collection runs periodically and follows an -ordered list of prune policies. +commands run at once, Garbage Collection (GC) runs periodically and follows an +ordered list of prune policies. The BuildKit daemon clears the build cache when +the cache size becomes too big, or when the cache age expires. -Garbage collection runs in the BuildKit daemon. The daemon clears the build -cache when the cache size becomes too big, or when the cache age expires. The -following sections describe how you can configure both the size and age -parameters by defining garbage collection policies. +For most users, the default GC behavior is sufficient and doesn't require any +intervention. Advanced users, particularly those working with large-scale +builds, self-managed builders, or constrained storage environments, might +benefit from customizing these settings to better align with their workflow +needs. The following sections explain how GC works and provide guidance on +tailoring its behavior through custom configuration. -Each of the policy's parameters corresponds with a `docker buildx prune` command line -argument. Details can be found in the -`docker buildx prune` [documentation](/reference/cli/docker/buildx/prune.md). +## Garbage collection policies + +GC policies define a set of rules that determine how the build cache is managed +and cleaned up. These policies include criteria for when to remove cache +entries, such as the age of the cache, the amount of space being used, and the +type of cache records to prune. + +Each GC policy is evaluated in sequence, starting with the most specific +criteria, and proceeds to broader rules if previous policies do not free up +enough cache. This lets BuildKit prioritize cache entries, preserving the most +valuable cache while ensuring the system maintains performance and +availability. + +For example, say you have the following GC policies: + +1. Find "stale" cache records that haven't been used in the past 48 hours, and + delete records until there's maximum 5GB of "stale" cache left. +2. If the build cache size exceeds 10GB, delete records until the total cache + size is no more than 10GB. + +The first rule is more specific, prioritizing stale cache records and setting a +lower limit for a less valuable type of cache. The second rule imposes a higher +hard limit that applies to any type of cache records. With these policies, if +you have 11GB worth of build cache, where: + +- 7GB of which is "stale" cache +- 4GB is other, more valuable cache + +A GC sweep would delete 5GB of stale cache as part of the 1st policy, with a +remainder of 6GB, meaning the 2nd policy does not need to clear any more cache. + +The default GC policies are (approximately): + +1. Remove cache that can be easily regenerated, such as build contexts from + local directories or remote Git repositories, and cache mounts, if hasn't + been used for more than 48 hours. +2. Remove cache that hasn't been used in a build for more than 60 days. +3. Remove unshared cache that exceeds the build cache size limit. Unshared + cache records refers to layer blobs that are not used by other resources + (typically, as image layers). +4. Remove any build cache that exceeds the build cache size limit. + +The precise algorithm and the means of configuring the policies differ slightly +depending on what kind of builder you're using. Refer to +[Configuration](#configuration) for more details. ## Configuration -Depending on the [driver](../builders/drivers/_index.md) used by your builder instance, -the garbage collection will use a different configuration file. +> [!NOTE] +> If you're satisfied with the default garbage collection behavior and don't +> need to fine-tune its settings, you can skip this section. Default +> configurations work well for most use cases and require no additional setup. + +Depending on the type of [build driver](../builders/drivers/_index.md) you use, +you will use different configuration files to change the builder's GC settings: + +- If you use the default builder for Docker Engine (the `docker` driver), use + the [Docker daemon configuration file](#docker-daemon-configuration-file). +- If you use a custom builder, use a [BuildKit configuration file](#buildkit-configuration-file). + +### Docker daemon configuration file + +If you're using the default [`docker` driver](../builders/drivers/docker.md), +GC is configured in the [`daemon.json` configuration file](/reference/cli/dockerd.md#daemon-configuration-file), +or if you use Docker Desktop, in [**Settings > Docker Engine**](/manuals/desktop/settings-and-maintenance/settings.md). + +The following snippet shows the default builder configuration for the `docker` +driver for Docker Desktop users: + +```json +{ + "builder": { + "gc": { + "defaultKeepStorage": "20GB", + "enabled": true + } + } +} +``` + +The `defaultKeepStorage` option configures the size limit of the build cache, +which influences the GC policies. The default policies for the `docker` driver +work as follows: + +1. Remove ephemeral, unused build cache older than 48 hours if it exceeds 13.8% + of `defaultKeepStorage`, or at minimum 512MB. +2. Remove unused build cache older than 60 days. +3. Remove unshared build cache that exceeds the `defaultKeepStorage` limit. +4. Remove any build cache that exceeds the `defaultKeepStorage` limit. + +Given the Docker Desktop default value for `defaultKeepStorage` of 20GB, the +default GC policies resolve to: + +```json +{ + "builder": { + "gc": { + "enabled": true, + "policy": [ + { + "keepStorage": "2.764GB", + "filter": [ + "unused-for=48h", + "type==source.local,type==exec.cachemount,type==source.git.checkout" + ] + }, + { "keepStorage": "20GB", "filter": ["unused-for=1440h"] }, + { "keepStorage": "20GB" }, + { "keepStorage": "20GB", "all": true } + ] + } + } +} +``` + +The easiest way to tweak the build cache configuration for the `docker` driver +is to adjust the `defaultKeepStorage` option: + +- Increase the limit if you feel like you think the GC is too aggressive. +- Decrease the limit if you need to preserve space. -If you're using the [`docker` driver](../builders/drivers/docker.md), garbage collection -can be configured in the [Docker Daemon configuration](/reference/cli/dockerd.md#daemon-configuration-file). -file: +If you need even more control, you can define your own GC policies directly. +The following example defines a more conservative GC configuration with the +following policies: + +1. Remove unused cache entries older than 1440 hours, or 60 days, if build cache exceeds 50GB. +2. Remove unshared cache entries if build cache exceeds 50GB. +3. Remove any cache entries if build cache exceeds 100GB. ```json { "builder": { "gc": { "enabled": true, - "defaultKeepStorage": "10GB", + "defaultKeepStorage": "50GB", "policy": [ - { "keepStorage": "10GB", "filter": ["unused-for=2200h"] }, - { "keepStorage": "50GB", "filter": ["unused-for=3300h"] }, + { "keepStorage": "0", "filter": ["unused-for=1440h"] }, + { "keepStorage": "0" }, { "keepStorage": "100GB", "all": true } ] } @@ -45,52 +164,127 @@ file: } ``` -For other drivers, garbage collection can be configured using the -[BuildKit configuration](../buildkit/toml-configuration.md) file: +Policies 1 and 2 here set `keepStorage` to `0`, which means they'll fall back +to the default limit of 50GB as defined by `defaultKeepStorage`. + +### BuildKit configuration file + +For build drivers other than `docker`, GC is configured using a +[`buildkitd.toml`](../buildkit/toml-configuration.md) configuration file. This +file uses the following high-level configuration options that you can use to +tweak the thresholds for how much disk space BuildKit should use for cache: + +| Option | Description | Default value | +| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | +| `reservedSpace` | The minimum amount of disk space BuildKit is allowed to allocate for cache. Usage below this threshold will not be reclaimed during garbage collection. | 10% of total disk space or 10GB (whichever is lower) | +| `maxUsedSpace` | The maximum amount of disk space that BuildKit is allowed to use. Usage above this threshold will be reclaimed during garbage collection. | 60% of total disk space or 100GB (whichever is lower) | +| `minFreeSpace` | The amount of disk space that must be kept free. | 20GB | + +You can set these options either as number of bytes, a unit string (for +example, `512MB`), or as a percentage of the total disk size. Changing these +options influences the default GC policies used by the BuildKit worker. With +the default thresholds, the GC policies resolve as follows: ```toml +# Global defaults [worker.oci] gc = true - gckeepstorage = 10000 - [[worker.oci.gcpolicy]] - keepBytes = 512000000 - keepDuration = 172800 - filters = [ "type==source.local", "type==exec.cachemount", "type==source.git.checkout"] - [[worker.oci.gcpolicy]] - all = true - keepBytes = 1024000000 + reservedSpace = "10GB" + maxUsedSpace = "100GB" + minFreeSpace = "20%" + +# Policy 1 +[[worker.oci.gcpolicy]] + filters = [ "type==source.local", "type==exec.cachemount", "type==source.git.checkout" ] + keepDuration = "48h" + maxUsedSpace = "512MB" + +# Policy 2 +[[worker.oci.gcpolicy]] + keepDuration = "1440h" # 60 days + reservedSpace = "10GB" + maxUsedSpace = "100GB" + +# Policy 3 +[[worker.oci.gcpolicy]] + reservedSpace = "10GB" + maxUsedSpace = "100GB" + +# Policy 4 +[[worker.oci.gcpolicy]] + all = true + reservedSpace = "10GB" + maxUsedSpace = "100GB" ``` -## Default policies - -Default garbage collection policies apply to all builders if not set: - -```text -GC Policy rule#0: - All: false - Filters: type==source.local,type==exec.cachemount,type==source.git.checkout - Keep Duration: 48h0m0s - Keep Bytes: 512MB -GC Policy rule#1: - All: false - Keep Duration: 1440h0m0s - Keep Bytes: 26GB -GC Policy rule#2: - All: false - Keep Bytes: 26GB -GC Policy rule#3: - All: true - Keep Bytes: 26GB +In practical terms, this means: + +- Policy 1: If the build cache exceeds 512MB, BuildKit removes cache records + for local build contexts, remote Git contexts, and cache mounts that haven’t + been used in the last 48 hours. +- Policy 2: If disk usage exceeds 100GB, unshared build cache older than 60 + days is removed, ensuring at least 10GB of disk space is reserved for cache. +- Policy 3: If disk usage exceeds 100GB, any unshared cache is removed, + ensuring at least 10GB of disk space is reserved for cache. +- Policy 4: If disk usage exceeds 100GB, all cache—including shared and + internal records—is removed, ensuring at least 10GB of disk space is reserved + for cache. + +`reservedSpace` has the highest priority in defining the lower limit for build +cache size. If `maxUsedSpace` or `minFreeSpace` would define a lower value, the +minimum cache size would never be brought below `reservedSpace`. + +If both `reservedSpace` and `maxUsedSpace` are set, a GC sweep results in a +cache size between those thresholds. For example, if `reservedSpace` is set to +10GB, and `maxUsedSpace` is set to 20GB, the resulting amount of cache after a +GC run is less than 20GB, but at least 10GB. + +You can also define completely custom GC policies. Custom policies also let you +define filters, which lets you pinpoint the types of cache entries that a given +policy is allowed to prune. + +#### Custom GC policies in BuildKit + +Custom GC policies let you fine-tune how BuildKit manages its cache, and gives +you full control over cache retention based on criteria such as cache type, +duration, or disk space thresholds. If you need full control over the cache +thresholds and how cache records should be prioritized, defining custom GC +policies is the way to go. + +To define a custom GC policy, use the `[[worker.oci.gcpolicy]]` configuration +block in `buildkitd.toml`. Each policy define the thresholds that will be used +for that policy. The global values for `reservedSpace`, `maxUsedSpace`, and +`minFreeSpace` do not apply if you use custom policies. + +Here’s an example configuration: + +```toml +# Custom GC Policy 1: Remove unused local contexts older than 24 hours +[[worker.oci.gcpolicy]] + filters = ["type==source.local"] + keepDuration = "24h" + reservedSpace = "5GB" + maxUsedSpace = "50GB" + +# Custom GC Policy 2: Remove remote Git contexts older than 30 days +[[worker.oci.gcpolicy]] + filters = ["type==source.git.checkout"] + keepDuration = "720h" + reservedSpace = "5GB" + maxUsedSpace = "30GB" + +# Custom GC Policy 3: Aggressively clean all cache if disk usage exceeds 90GB +[[worker.oci.gcpolicy]] + all = true + reservedSpace = "5GB" + maxUsedSpace = "90GB" ``` -- `rule#0`: if build cache uses more than 512MB delete the most easily - reproducible data after it has not been used for 2 days. -- `rule#1`: remove any data not used for 60 days. -- `rule#2`: keep the unshared build cache under cap. -- `rule#3`: if previous policies were insufficient start deleting internal data - to keep build cache under cap. +In addition to the `reservedSpace`, `maxUsedSpace`, and `minFreeSpace` threshold, +when defining a GC policy you have two additional configuration options: -> [!NOTE] -> -> `Keep Bytes` defaults to 10% of the size of the disk. If the disk size cannot -> be determined, it uses 2GB as a fallback. +- `all`: By default, BuildKit will exclude some cache records from being pruned + during GC. Setting this option to `true` will allow any cache records to be + pruned. +- `filters`: Filters let you specify specific types of cache records that a GC + policy is allowed to prune. diff --git a/content/manuals/build/ci/github-actions/multi-platform.md b/content/manuals/build/ci/github-actions/multi-platform.md index e6d44b7ea47..a04c73562cb 100644 --- a/content/manuals/build/ci/github-actions/multi-platform.md +++ b/content/manuals/build/ci/github-actions/multi-platform.md @@ -109,7 +109,10 @@ each platform across multiple runners and create manifest list using the The following workflow will build the image for each platform on a dedicated runner using a matrix strategy and push by digest. Then, the `merge` job will -create a manifest list and push it to Docker Hub. +create manifest lists and push them to two registries: + +- Docker Hub: `docker.io/docker-user/my-app` +- GitHub Container Registry: `ghcr.io/gh-user/my-app` This example also uses the [`metadata` action](https://github.com/docker/metadata-action) to set tags and labels. @@ -121,7 +124,8 @@ on: push: env: - REGISTRY_IMAGE: user/app + DOCKERHUB_REPO: docker-user/my-app + GHCR_REPO: ghcr.io/gh-user/my-app jobs: build: @@ -131,8 +135,6 @@ jobs: matrix: platform: - linux/amd64 - - linux/arm/v6 - - linux/arm/v7 - linux/arm64 steps: - name: Prepare @@ -144,7 +146,9 @@ jobs: id: meta uses: docker/metadata-action@v5 with: - images: ${{ env.REGISTRY_IMAGE }} + images: | + ${{ env.DOCKERHUB_REPO }} + ${{ env.GHCR_REPO }} - name: Login to Docker Hub uses: docker/login-action@v3 @@ -152,6 +156,13 @@ jobs: username: ${{ vars.DOCKERHUB_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} + - name: Login to GHCR + uses: docker/login-action@v3 + with: + registry: ghcr.io + username: ${{ github.repository_owner }} + password: ${{ secrets.GITHUB_TOKEN }} + - name: Set up QEMU uses: docker/setup-qemu-action@v3 @@ -164,7 +175,7 @@ jobs: with: platforms: ${{ matrix.platform }} labels: ${{ steps.meta.outputs.labels }} - outputs: type=image,name=${{ env.REGISTRY_IMAGE }},push-by-digest=true,name-canonical=true,push=true + outputs: type=image,"name=${{ env.DOCKERHUB_REPO }},${{ env.GHCR_REPO }}",push-by-digest=true,name-canonical=true,push=true - name: Export digest run: | @@ -198,6 +209,13 @@ jobs: username: ${{ vars.DOCKERHUB_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} + - name: Login to GHCR + uses: docker/login-action@v3 + with: + registry: ghcr.io + username: ${{ github.repository_owner }} + password: ${{ secrets.GITHUB_TOKEN }} + - name: Set up Docker Buildx uses: docker/setup-buildx-action@v3 @@ -205,17 +223,27 @@ jobs: id: meta uses: docker/metadata-action@v5 with: - images: ${{ env.REGISTRY_IMAGE }} + images: | + ${{ env.DOCKERHUB_REPO }} + ${{ env.GHCR_REPO }} + tags: | + type=ref,event=branch + type=ref,event=pr + type=semver,pattern={{version}} + type=semver,pattern={{major}}.{{minor}} - name: Create manifest list and push working-directory: /tmp/digests run: | docker buildx imagetools create $(jq -cr '.tags | map("-t " + .) | join(" ")' <<< "$DOCKER_METADATA_OUTPUT_JSON") \ - $(printf '${{ env.REGISTRY_IMAGE }}@sha256:%s ' *) + $(printf '${{ env.DOCKERHUB_REPO }}@sha256:%s ' *) + docker buildx imagetools create $(jq -cr '.tags | map("-t " + .) | join(" ")' <<< "$DOCKER_METADATA_OUTPUT_JSON") \ + $(printf '${{ env.GHCR_REPO }}@sha256:%s ' *) - name: Inspect image run: | - docker buildx imagetools inspect ${{ env.REGISTRY_IMAGE }}:${{ steps.meta.outputs.version }} + docker buildx imagetools inspect ${{ env.DOCKERHUB_REPO }}:${{ steps.meta.outputs.version }} + docker buildx imagetools inspect ${{ env.GHCR_REPO }}:${{ steps.meta.outputs.version }} ``` ### With Bake diff --git a/content/manuals/build/concepts/overview.md b/content/manuals/build/concepts/overview.md index 8b30d385405..e8a101e649f 100644 --- a/content/manuals/build/concepts/overview.md +++ b/content/manuals/build/concepts/overview.md @@ -38,6 +38,11 @@ the CLI plugin from source, or grab a binary from the GitHub repository and install it manually. See [Buildx README](https://github.com/docker/buildx#manual-download) on GitHub for more information. +> [!NOTE] +> While `docker build` invokes Buildx under the hood, there are subtle +> differences between this command and the canonical `docker buildx build`. +> For details, see [Difference between `docker build` and `docker buildx build`](../builders/_index.md#difference-between-docker-build-and-docker-buildx-build). + ## BuildKit BuildKit is the daemon process that executes the build workloads. diff --git a/content/manuals/build/images/build-variables.svg b/content/manuals/build/images/build-variables.svg index 6bd6d77689c..13197975fb1 100644 --- a/content/manuals/build/images/build-variables.svg +++ b/content/manuals/build/images/build-variables.svg @@ -1,3 +1,3 @@ - Global scope# Build arguments declared here are in the global scopeARG GLOBAL_ARG="global default value"ARG VERSION="3.19"# You can't declare environment variables in the global scopeENV GLOBAL_ENV=false# GLOBAL_ARG was not redeclared in this stageRUN echo $GLOBAL_ARG# LOCAL_ARG was declared in stage-aRUN echo $LOCAL_ARGstage-bFROM --platform=$BUILDPLATFORM alpine:${VERSION} as stage-bstage-a# FROM-lines belong to the global scope and have access to global ARGsFROM alpine:${VERSION} as stage-a# Redeclaring GLOBAL_ARG without a value inherits the global defaultARG GLOBAL_ARGRUN echo $GLOBAL_ARG# ARG here this scope creates a local argumentARG LOCAL_ARG="local arg in stage-a"# Set an environment variable in this scopeENV LOCAL_ENV=true# Set an environment variable to the value of a build argumentENV MY_VAR=$LOCAL_ARGstage-c# New stage based on "stage-a"FROM stage-a AS stage-c# Arguments and variables are inherited from parent stagesRUN echo $LOCAL_ARGRUN echo $LOCAL_ENV<- prints an emptry string<- prints an emptry string<- prints "global default value"<- prints "local arg in stage-a"<- prints "true"ARG TARGETPLATFORM# You must redeclare pre-defined arguments to use them in a stageRUN echo $TARGETPLATFORM<- prints os/arch/variant of --platform# Pre-defined multi-platform arguments like $BUILDPLATFORM are global + Global scope# Build arguments declared here are in the global scopeARG GLOBAL_ARG="global default value"ARG VERSION="3.19"# You can't declare environment variables in the global scopeENV GLOBAL_ENV=false# GLOBAL_ARG was not redeclared in this stageRUN echo $GLOBAL_ARG# LOCAL_ARG was declared in stage-aRUN echo $LOCAL_ARGstage-bFROM --platform=$BUILDPLATFORM alpine:${VERSION} as stage-bstage-a# FROM-lines belong to the global scope and have access to global ARGsFROM alpine:${VERSION} as stage-a# Redeclaring GLOBAL_ARG without a value inherits the global defaultARG GLOBAL_ARGRUN echo $GLOBAL_ARG# ARG here this scope creates a local argumentARG LOCAL_ARG="local arg in stage-a"# Set an environment variable in this scopeENV LOCAL_ENV=true# Set an environment variable to the value of a build argumentENV MY_VAR=$LOCAL_ARGstage-c# New stage based on "stage-a"FROM stage-a AS stage-c# Arguments and variables are inherited from parent stagesRUN echo $LOCAL_ARGRUN echo $LOCAL_ENV<- prints an empty string<- prints an empty string<- prints "global default value"<- prints "local arg in stage-a"<- prints "true"ARG TARGETPLATFORM# You must redeclare pre-defined arguments to use them in a stageRUN echo $TARGETPLATFORM<- prints os/arch/variant of --platform# Pre-defined multi-platform arguments like $BUILDPLATFORM are global diff --git a/content/manuals/compose/how-tos/environment-variables/envvars.md b/content/manuals/compose/how-tos/environment-variables/envvars.md index a0fa287780e..54a2a5e446a 100644 --- a/content/manuals/compose/how-tos/environment-variables/envvars.md +++ b/content/manuals/compose/how-tos/environment-variables/envvars.md @@ -30,7 +30,7 @@ This page contains information on how you can set or change the following pre-de ## Methods to override You can set or change the pre-defined environment variables: -- With an [`.env` file located in your working director](/manuals/compose/how-tos/environment-variables/variable-interpolation.md) +- With an [`.env` file located in your working directory](/manuals/compose/how-tos/environment-variables/variable-interpolation.md) - From the command line - From your [shell](variable-interpolation.md#substitute-from-the-shell) diff --git a/content/manuals/compose/how-tos/environment-variables/variable-interpolation.md b/content/manuals/compose/how-tos/environment-variables/variable-interpolation.md index 8ecc782cba1..a13e51a9305 100644 --- a/content/manuals/compose/how-tos/environment-variables/variable-interpolation.md +++ b/content/manuals/compose/how-tos/environment-variables/variable-interpolation.md @@ -203,7 +203,7 @@ $ docker compose --env-file ./config/.env.dev up $ docker compose --env-file .env.dev up -e DATABASE_URL=mysql://new_user:new_password@new_db:3306/new_database ``` -### local `.env` file versus `.env` file +### local `.env` file versus <project directory> `.env` file An `.env` file can also be used to declare [pre-defined environment variables](envvars.md) used to control Compose behavior and files to be loaded. diff --git a/content/manuals/compose/how-tos/use-secrets.md b/content/manuals/compose/how-tos/use-secrets.md index 321aab0095b..fe677ff8a40 100644 --- a/content/manuals/compose/how-tos/use-secrets.md +++ b/content/manuals/compose/how-tos/use-secrets.md @@ -17,6 +17,8 @@ Environment variables are often available to all processes, and it can be diffic ## Use secrets +Secrets are mounted as a file in `/run/secrets/` inside the container. + Getting a secret into a container is a two-step process. First, define the secret using the [top-level secrets element in your Compose file](/reference/compose-file/secrets.md). Next, update your service definitions to reference the secrets they require with the [secrets attribute](/reference/compose-file/services.md#secrets). Compose grants access to secrets on a per-service basis. Unlike the other methods, this permits granular access control within a service container via standard filesystem permissions. diff --git a/content/manuals/compose/releases/release-notes.md b/content/manuals/compose/releases/release-notes.md index ff14e92aca6..70af2b3680f 100644 --- a/content/manuals/compose/releases/release-notes.md +++ b/content/manuals/compose/releases/release-notes.md @@ -13,6 +13,54 @@ aliases: For more detailed information, see the [release notes in the Compose repo](https://github.com/docker/compose/releases/). +## 2.32.2 + +{{< release-date date="2025-01-07" >}} + +### Update + +- Dependencies upgrade: bump compose-go to v2.4.7 +- Dependencies upgrade: bump golang to v1.22.10 + +### Bug fixes and enhancements + +- Added `--pull` flag to the `docker compose run` command +- Fixed a bug which meant the `restart` action of `watch` mode didn't monitor bind mounts +- Fixed an issue recreating containers when using anonymous volumes + +## 2.32.1 + +{{< release-date date="2024-12-16" >}} + +### Bug fixes and enhancements + +- Fixed a bug recreating containers when not needed + +## 2.32.0 + +{{< release-date date="2024-12-13" >}} + +### Update + +- Dependencies upgrade: bump docker + buildx to latest release +- Dependencies upgrade: bump otel dependencies to v1.28.0 and v0.53.0 +- Dependencies upgrade: bump golang.org/x/sys 0.28.0 +- Dependencies upgrade: bump golang.org/x/crypto to 0.31.0 +- Dependencies upgrade: bump google.golang.org/grpc to 1.68.1 +- Dependencies upgrade: bump golang.org/x/sync 0.10.0 +- Dependencies upgrade: bump xx to v1.6.1 + +### Bug fixes and enhancements + +- Improved support when building with [Bake](/manuals/build/bake.md) +- Added `restart` and `sync+exec` watch actions +- Compose now recreates containers when the volume or network configuration changes +- Fixed support for `mac_address` +- Fixed `pull --quiet` to only hide progress, not global status +- Fixed an issue where only the `rebuild` watch action now requires a build declaration +- Compose now logs `watch` configuration error when enabled through the Compose menu + + ## 2.31.0 {{< release-date date="2024-11-28" >}} diff --git a/content/manuals/desktop/features/desktop-cli.md b/content/manuals/desktop/features/desktop-cli.md new file mode 100644 index 00000000000..1c6d428ac47 --- /dev/null +++ b/content/manuals/desktop/features/desktop-cli.md @@ -0,0 +1,42 @@ +--- +title: Using the Docker Desktop CLI +linkTitle: Docker Desktop CLI +weight: 120 +description: How to use the Docker Desktop CLI +keywords: cli, docker desktop, macos, windows, linux +params: + sidebar: + badge: + color: green + text: New +--- + +{{% experimental title="Beta" %}} +Docker Desktop CLI is currently in [Beta](../../release-lifecycle.md#beta). +{{% /experimental %}} + +The Docker Desktop CLI lets you perform key operations such as starting, stopping, restarting, and checking the status of Docker Desktop directly from the command line. It is available with Docker Desktop version 4.37 and later. + +The Docker Desktop CLI provides: + +- Enhanced automation and CI/CD integration: Perform Docker Desktop operations directly in CI/CD pipelines for better workflow automation. +- An improved developer experience: Restart, quit, or reset Docker Desktop from the command line, reducing dependency on the Docker Desktop Dashboard and improving flexibility and efficiency. + +## Usage + +```console +docker desktop COMMAND [OPTIONS] +``` + +## Commands + +| Command | Description | +|:---------------------|:-----------------------------------------| +| `start` | Starts Docker Desktop | +| `stop` | Stops Docker Desktop | +| `restart` | Restarts Docker Desktop | +| `status` | Displays whether Docker Desktop is running or stopped. | +| `engine ls` | Lists available engines (Windows only) | +| `engine use` | Switch between Linux and Windows containers (Windows only) | + +For more details on each command, see the [Docker Desktop CLI reference](/reference/cli/docker/desktop/_index.md). diff --git a/content/manuals/desktop/features/gordon.md b/content/manuals/desktop/features/gordon.md new file mode 100644 index 00000000000..469a9ac6ee6 --- /dev/null +++ b/content/manuals/desktop/features/gordon.md @@ -0,0 +1,292 @@ +--- +title: Ask Gordon +description: Learn how to streamline your workflow with Docker's AI-powered assistant. +weight: 10 +params: + sidebar: + badge: + color: blue + text: Beta +--- + +{{% restricted title=Beta %}} +Ask Gordon is a [Beta](/manuals/release-lifecycle.md) feature, and only members +of the Ask Gordon beta program can access it. Features, user interface, and +behavior are subject to change in future releases. + +{{< button text="Apply for access" url="https://docker.qualtrics.com/jfe/form/SV_dmVHFjQ4fZlrEOy" >}} +{{% /restricted %}} + +Ask Gordon is your personal AI assistant embedded in Docker Desktop and the +Docker CLI. It's designed to streamline your workflow and help you make the +most of the Docker ecosystem. + +## What is Ask Gordon? + +Ask Gordon is a suite of AI-powered capabilities integrated into Docker's +tools. These features, currently in Beta, are not enabled by default, and are +not production-ready. You may also encounter the term "Docker AI" as a broader +reference to this technology. + +The goal of Ask Gordon is to make Docker's tools for managing images and +containers more intuitive and accessible. It provides contextual assistance +tailored to your local environment, including Dockerfiles, containers, and +applications. + +Ask Gordon integrates directly with Docker's tools to help you perform specific +tasks. It understands your local setup, such as your local source code and +images. For example, you can ask Gordon to help you identify vulnerabilities in +your project or how to optimize a Dockerfile in your local repository. This +tight integration ensures responses are practical and actionable. + +> [!NOTE] +> Ask Gordon is powered by Large Language Models (LLMs). Like all LLM-based +> tools, its responses may sometimes be inaccurate. Always verify the +> information provided. + +### What data does Gordon access? + +When you use Ask Gordon, the data it accesses depends on the context of your +query: + +- Local files: If you use the `docker ai` command, Ask Gordon can access + files and directories in the current working directory where the command is + executed. In Docker Desktop, if you ask about a specific file or directory in + the **Ask Gordon** view, you'll be prompted to select the relevant context. +- Local images: Gordon integrates with Docker Desktop and can view all images + in your local image store. This includes images you've built or pulled from a + registry. + +To provide accurate responses, Ask Gordon may send relevant files, directories, +or image metadata to the Gordon backend along with your query. This data +transfer occurs over the network but is never stored persistently or shared +with third parties. It is used exclusively to process your request and +formulate a response. + +All data transferred is encrypted in transit. + +### How your data is collected and used + +Docker collects anonymized data from your interactions with Ask Gordon to +enhance the service. This includes the following: + +- Your queries: Questions you ask Gordon. +- Responses: Answers provided by Gordon. +- Feedback: Thumbs-up and thumbs-down ratings. + +To ensure privacy and security: + +- Data is anonymized and cannot be traced back to you or your account. +- Docker does not use this data to train AI models or share it with third + parties. + +By using Ask Gordon, you help improve Docker AI's reliability and accuracy, +making it more effective for all users. + +If you have concerns about data collection or usage, you can +[disable](#disable-ask-gordon) the feature at any time. + +## Setup + +To use this feature, you must have: + +- [Access to the Ask Gordon beta program](https://docker.qualtrics.com/jfe/form/SV_dmVHFjQ4fZlrEOy). + +- Docker Desktop version 4.37 or later. + +Ask Gordon is not enabled by default. After having received access to the beta +program, you must enable the feature: + +1. [Sign in](#sign-in) to your Docker account. +2. [Enable the feature](#enable-the-feature) in the Docker Desktop settings. +3. [Accept the terms of service](#accept-the-terms-of-service). + +### Sign in + +1. Open Docker Desktop. +2. Select the **Sign in** button. +3. Complete the sign-in process in your web browser. + +### Enable the feature + +After signing in to your Docker Account, enable the Docker AI feature: + +1. Open the **Settings** view in Docker Desktop. +2. Navigate to **Features in development**. +3. Check the **Enable Docker AI** checkbox. +4. Select **Apply & restart**. + +### Accept the terms of service + +To start using Docker AI, you need to accept the terms of service. You can do +this in one of two ways: + +- Open the **Ask Gordon** view in Docker Desktop and ask a question. +- Use the `docker ai` CLI command to issue a query. + +The first time you interact with Docker AI, you'll see a prompt to accept the +terms of service. For example: + +```console +$ docker ai what can you do? + + Before using Gordon, please accept the terms of service +``` + +After accepting the terms, you can begin using Ask Gordon. + +## Using Ask Gordon + +The primary interfaces to Docker's AI capabilities are through the **Ask +Gordon** view in Docker Desktop, or if you prefer to use the CLI: the `docker +ai` CLI command. + +If you've used an AI chatbot before, these interfaces will be pretty familiar +to you. You can chat with the Docker AI to get help with your Docker tasks. + +### Contextual help + +Once you've enabled the Docker AI features, you'll also find references to +**Ask Gordon** in various other places throughout the Docker Desktop user +interface. Whenever you encounter a button with the "sparkles" (✨) icon in the +user interface, you can use the button to get contextual support from Ask +Gordon. + +## Example workflows + +Ask Gordon is a general-purpose AI assistant created to help you with all your +Docker-related tasks and workflows. If you need some inspiration, here are a +few ways things you can try: + +- [Troubleshoot a crashed container](#troubleshoot-a-crashed-container) +- [Get help with running a container](#get-help-with-running-a-container) +- [Improve a Dockerfile](#improve-a-dockerfile) + +For more examples, try asking Gordon directly. For example: + +```console +$ docker ai "What can you do?" +``` + +### Troubleshoot a crashed container + +If you try to start a container with an invalid configuration or command, you +can use Ask Gordon to troubleshoot the error. For example, try starting a +Postgres container without specifying a database password: + +```console +$ docker run postgres +Error: Database is uninitialized and superuser password is not specified. + You must specify POSTGRES_PASSWORD to a non-empty value for the + superuser. For example, "-e POSTGRES_PASSWORD=password" on "docker run". + + You may also use "POSTGRES_HOST_AUTH_METHOD=trust" to allow all + connections without a password. This is *not* recommended. + + See PostgreSQL documentation about "trust": + https://www.postgresql.org/docs/current/auth-trust.html +``` + +In the **Containers** view in Docker Desktop, select the ✨ icon next to the +container's name, or inspect the container and open the **Ask Gordon** tab. + +### Get help with running a container + +If you want to run a specific image but you're not sure how, Gordon might be +able to help you get set up: + +1. Pull an image from Docker Hub (for example, `postgres`). +2. Open the **Images** view in Docker Desktop and select the image. +3. Select the **Run** button. + +In the _Run a new container_ dialog that opens, you should see a message about +**Ask Gordon**. + +![Ask Gordon hint in Docker Desktop](../images/gordon-run-ctr.png) + +The linked text in the hint is a suggested prompt to start a conversation with +Ask Gordon. + +### Improve a Dockerfile + +Gordon can analyze your Dockerfile and suggest improvements. To have Gordon +evaluate your Dockerfile using the `docker ai` command: + +1. Navigate to your project directory: + + ```console + $ cd path/to/my/project + ``` + +2. Use the `docker ai` command to rate your Dockerfile: + + ```console + $ docker ai rate my Dockerfile + ``` + +Gordon will analyze your Dockerfile and identify opportunities for improvement +across several dimensions: + +- Build cache optimization +- Security +- Image size efficiency +- Best practices compliance +- Maintainability +- Reproducibility +- Portability +- Resource efficiency + +## Disable Ask Gordon + +If you've enabled Ask Gordon and you want to disable it again: + +1. Open the **Settings** view in Docker Desktop. +2. Navigate to **Features in development**. +3. Clear the **Enable Docker AI** checkbox. +4. Select **Apply & restart**. + +If you want to disable Ask Gordon for your entire Docker organization, using +[Settings Management](/manuals/security/for-admins/hardened-desktop/settings-management/_index.md), +add the following property to your `admin-settings.json` file: + +```json +{ + "enableDockerAI": { + "value": false, + "locked": true + } +} +``` + +Alternatively, you can disable all Beta features by setting `allowBetaFeatures` to false: + +```json +{ + "allowBetaFeatures": { + "value": false, + "locked": true + } +} +``` + +## Feedback + + + +We value your input on Ask Gordon and encourage you to share your experience. +Your feedback helps us improve and refine Ask Gordon for all users. If you +encounter issues, have suggestions, or simply want to share what you like, +here's how you can get in touch: + +- Thumbs-up and thumbs-down buttons + + Rate Ask Gordon's responses using the thumbs-up or thumbs-down buttons in the + response. + +- Feedback survey + + You can access the Ask Gordon survey by following the _Give feedback_ link in + the **Ask Gordon** view in Docker Desktop, or from the CLI by running the + `docker ai feedback` command. + +Thank you for helping us improve Ask Gordon. diff --git a/content/manuals/desktop/features/synchronized-file-sharing.md b/content/manuals/desktop/features/synchronized-file-sharing.md index 789a9c159f9..91a98a39c62 100644 --- a/content/manuals/desktop/features/synchronized-file-sharing.md +++ b/content/manuals/desktop/features/synchronized-file-sharing.md @@ -94,6 +94,8 @@ In general, use your `.syncignore` file to exclude items that aren't critical to - POSIX-style Windows paths are not supported. Avoid setting the [`COMPOSE_CONVERT_WINDOWS_PATHS`](/manuals/compose/how-tos/environment-variables/envvars.md#compose_convert_windows_paths) environment variable in Docker Compose. +- If you don't have the correct permissions to create symbolic links and your container attempts to create symbolic links in your file share instance, an **unable to create symbolic link** error message displays. For Windows users, see Microsoft's [Create symbolic links documentation](https://learn.microsoft.com/en-us/previous-versions/windows/it-pro/windows-10/security/threat-protection/security-policy-settings/create-symbolic-links) for best practices and location of the **Create symbolic links** security policy setting. For Mac and Linux users, check that you have write permissions on the folder. + ## Feedback and support To give feedback or report bugs, visit: diff --git a/content/manuals/desktop/features/usbip.md b/content/manuals/desktop/features/usbip.md index fe6024c05b5..12483da06bf 100644 --- a/content/manuals/desktop/features/usbip.md +++ b/content/manuals/desktop/features/usbip.md @@ -1,7 +1,7 @@ --- title: Using USB/IP with Docker Desktop linkTitle: USB/IP support -weight: 80 +weight: 100 description: How to use USB/IP in Docker Desktop keywords: usb, usbip, docker desktop, macos, windows, linux toc_max: 3 diff --git a/content/manuals/desktop/features/vmm.md b/content/manuals/desktop/features/vmm.md index 1af1d399b51..ab88b8b4b8e 100644 --- a/content/manuals/desktop/features/vmm.md +++ b/content/manuals/desktop/features/vmm.md @@ -8,7 +8,7 @@ params: text: New keywords: virtualization software, resource allocation, mac, docker desktop, vm monitoring, vm performance, apple silicon description: Discover Docker Desktop for Mac's Virtual Machine Manager (VMM) options, including the new Docker VMM for Apple Silicon, offering enhanced performance and efficiency -weight: 90 +weight: 110 aliases: - /desktop/vmm/ --- @@ -31,6 +31,8 @@ These improvements directly impact developers who rely on frequent file access a > > Docker VMM requires a minimum of 4GB of memory to be allocated to the Docker Linux VM. The memory needs to be increased before Docker VMM is enabled, and this can be done from the **Resources** tab in **Settings**. +Docker VMM is based on [libkrun](https://github.com/containers/libkrun). + ### Known issues As Docker VMM is still in Beta, there are a few known limitations: diff --git a/content/manuals/desktop/features/wsl/_index.md b/content/manuals/desktop/features/wsl/_index.md index 0d53cb15d4a..74a5eae3e9d 100644 --- a/content/manuals/desktop/features/wsl/_index.md +++ b/content/manuals/desktop/features/wsl/_index.md @@ -5,7 +5,7 @@ keywords: wsl, wsl2, installing wsl2, wsl installation, docker wsl2, wsl docker, tech preview, wsl install docker, install docker wsl, how to install docker in wsl title: Docker Desktop WSL 2 backend on Windows linkTitle: WSL -weight: 100 +weight: 90 aliases: - /docker-for-windows/wsl/ - /docker-for-windows/wsl-tech-preview/ @@ -90,6 +90,7 @@ Docker Desktop does not require any particular Linux distributions to be install ```console $ wsl --set-default ``` + If **WSL integrations** isn't available under **Resources**, Docker may be in Windows container mode. In your taskbar, select the Docker menu and then **Switch to Linux containers**. 3. Select **Apply & Restart**. diff --git a/content/manuals/desktop/images/dashboard.webp b/content/manuals/desktop/images/dashboard.webp index e76911ae84b..ac3346c820c 100644 Binary files a/content/manuals/desktop/images/dashboard.webp and b/content/manuals/desktop/images/dashboard.webp differ diff --git a/content/manuals/desktop/images/gordon-run-ctr.png b/content/manuals/desktop/images/gordon-run-ctr.png new file mode 100644 index 00000000000..5369a82a7b0 Binary files /dev/null and b/content/manuals/desktop/images/gordon-run-ctr.png differ diff --git a/content/manuals/desktop/release-notes.md b/content/manuals/desktop/release-notes.md index 7d029ae6073..7e051dcb67d 100644 --- a/content/manuals/desktop/release-notes.md +++ b/content/manuals/desktop/release-notes.md @@ -23,6 +23,68 @@ Docker Desktop versions older than 6 months from the latest release are not avai Take a look at the [Docker Public Roadmap](https://github.com/orgs/docker/projects/51/views/1?filterQuery=) to see what's coming next. +## 4.37.1 + +{{< release-date date="2024-12-17" >}} + +{{< desktop-install-v2 all=true beta_win_arm=true version="4.37.1" build_path="/178610/" >}} + +### Bug fixes and enhancements + +#### For all platforms + +- Fixed an issue that caused the AI Catalog in Docker Hub to be unavailable in Docker Desktop. +- Fixed an issue that caused Docker Desktop to panic with `index out of range [0] with length 0` when using [Enhanced Container Isolation](/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/_index.md). + +## 4.37.0 + +{{< release-date date="2024-12-12" >}} + +{{< desktop-install-v2 all=true beta_win_arm=true version="4.37.0" build_path="/178034/" >}} + +### New + +- You can now perform key operations such as starting, stopping, restarting, and checking the status of Docker Desktop directly from the [command line](/manuals/desktop/features/desktop-cli.md) (Beta). +- The AI Catalog in Docker Hub is available directly through Docker Desktop. + +### Upgrades + +- [Docker Buildx v0.19.2](https://github.com/docker/buildx/releases/tag/v0.19.2) +- [Docker Compose v2.31.0](https://github.com/docker/compose/releases/tag/v2.31.0) +- [Docker Engine v27.4.0](https://docs.docker.com/engine/release-notes/27/#2740) +- [Docker Scout CLI v1.15.1](https://github.com/docker/scout-cli/releases/tag/v1.15.1) +- [NVIDIA Container Toolkit v1.17.2](https://github.com/NVIDIA/nvidia-container-toolkit/releases/tag/v1.17.2) + +### Bug fixes and enhancements + +#### For all platforms + +- The default disk usage limit for Docker Engine in new installations is now 1TB. +- Fixed an issue where containers could not establish loopback `AF_VSOCK` connections. +- Fixed a bug where resetting default settings would also reset the CLI context. +- Fixed a bug where the Docker Desktop Dashboard would get out of sync with the Docker daemon after restarting the engine while in Resource Saver mode (Windows with WSL2 backend only) or after switching engines (macOS). +- Fixed a bug where Resource Saver mode would fail to re-engage after restarting the engine while in Resource Saver mode. + +#### For Mac + +- Fixed a bug that would create certain user directories with root permission when running the uninstaller binary twice with `sudo`. + +#### For Windows + +- Added support for Windows on ARM using WSL 2 version 2.3.24 and later to single distribution mode on WSL 2. +- Fixed an issue where Docker Desktop would fail to start. Fixes [docker/for-win#14453](https://github.com/docker/for-win/issues/14453) + +### Known issues + +- Kubernetes cluster may not start if **Registry Access Manager** is enabled. As a workaround, add `registry.k8s.io` and `-docker.pkg.dev` to **Registry Access Management** policies. + +### Deprecation + +#### For Mac + +- QEMU (Legacy) as a VMM on Apple Silicon will be removed in a future version. It is recommended that you switch to the Apple Virtualization Framework for increased performance and stability. If you encounter an issue, [contact Docker Support](https://www.docker.com/support/) or [file a GitHub issue](https://github.com/docker/for-mac/issues). +- osxfs (Legacy) will be removed in a future version. It is recommended that you switch to VirtioFS for increased performance. If you encounter an issue, [contact Docker Support](https://www.docker.com/support/) or [file a GitHub issue](https://github.com/docker/for-mac/issues). + ## 4.36.0 {{< release-date date="2024-11-18" >}} diff --git a/content/manuals/desktop/use-desktop/_index.md b/content/manuals/desktop/use-desktop/_index.md index 70d13dcf225..b7b309cf6b1 100644 --- a/content/manuals/desktop/use-desktop/_index.md +++ b/content/manuals/desktop/use-desktop/_index.md @@ -20,7 +20,7 @@ The **Volumes** view displays a list of volumes and allows you to easily create The **Builds** view lets you inspect your build history and manage builders. By default, it displays a list of all your ongoing and completed builds. [Explore builds](builds.md). -In addition, the Docker Desktop Dashboard let you: +In addition, the Docker Desktop Dashboard lets you: - Navigate to the **Settings** menu to configure your Docker Desktop settings. Select the **Settings** icon in the Dashboard header. - Access the **Troubleshoot** menu to debug and perform restart operations. Select the **Troubleshoot** icon in the Dashboard header. @@ -30,6 +30,8 @@ In addition, the Docker Desktop Dashboard let you: For a more detailed guide about getting started, see [Get started](/get-started/introduction/_index.md). - Get to the [Docker Scout](../../scout/_index.md) dashboard. - Check the status of Docker services. +- Access [Docker Hub](/manuals/docker-hub/_index.md) to search, browse, pull, run, or view details + of images. ## Quick search diff --git a/content/manuals/desktop/use-desktop/images.md b/content/manuals/desktop/use-desktop/images.md index 7fbfe2c0c98..c44b7b477d8 100644 --- a/content/manuals/desktop/use-desktop/images.md +++ b/content/manuals/desktop/use-desktop/images.md @@ -87,10 +87,10 @@ To remove individual images, select the bin icon. The **Images** view also allows you to manage and interact with images in Docker Hub repositories. By default, when you go to **Images** in Docker Desktop, you see a list of images that exist in your local image store. -The **Local** and **Hub** tabs near the top toggles between viewing images in your local image store, +The **Local** and **Hub repositories** tabs near the top toggles between viewing images in your local image store, and images in remote Docker Hub repositories that you have access to. -Switching to the **Hub** tab prompts you to sign in to your Docker Hub account, if you're not already signed in. +Switching to the **Hub repositories** tab prompts you to sign in to your Docker Hub account, if you're not already signed in. When signed in, it shows you a list of images in Docker Hub organizations and repositories that you have access to. Select an organization from the drop-down to view a list of repositories for that organization. diff --git a/content/manuals/docker-hub/_index.md b/content/manuals/docker-hub/_index.md index c6ab1a08381..c47f97f76dc 100644 --- a/content/manuals/docker-hub/_index.md +++ b/content/manuals/docker-hub/_index.md @@ -11,6 +11,10 @@ grid: description: Step-by-step instructions on getting started on Docker Hub. icon: explore link: /docker-hub/quickstart +- title: Library + description: Explore the content library, featuring millions of images for operating systems, frameworks, databases, and more. + icon: book + link: /docker-hub/image-library/ - title: Repositories description: Create a repository to share your images with your team, customers, or the Docker community. diff --git a/content/manuals/docker-hub/image-library/_index.md b/content/manuals/docker-hub/image-library/_index.md new file mode 100644 index 00000000000..3d41410ff1f --- /dev/null +++ b/content/manuals/docker-hub/image-library/_index.md @@ -0,0 +1,22 @@ +--- +description: Learn about Docker Hub's library of images, extensions, and plugins. +keywords: Docker Hub, Hub, content library +title: Content library +linkTitle: Library +weight: 20 +--- + +Docker Hub's content library is the world's largest collection of +container images, extensions, and plugins. It provides a central location to +discover pre-built images and tools designed to streamline your container +workflows, making it easier to share and collaborate. + +In this section, learn about: + +- [Search](./search.md): Discover how to browse and search Docker Hub's extensive resources. +- [Trusted content](./trusted-content.md): Dive into Docker Official Images, + Verified Publisher content, and Sponsored Open Source images, all vetted for + security and reliability to streamline your workflows. +- [Catalogs](./catalogs.md): Explore specialized collections like the generative AI catalog. +- [Mirroring](./mirror.md): Learn how to create a mirror of Docker Hub's + container image library as a pull-through cache. \ No newline at end of file diff --git a/content/manuals/docker-hub/image-library/catalogs.md b/content/manuals/docker-hub/image-library/catalogs.md new file mode 100644 index 00000000000..066ce8c5647 --- /dev/null +++ b/content/manuals/docker-hub/image-library/catalogs.md @@ -0,0 +1,59 @@ +--- +description: Explore specialized Docker Hub collections like the Generative AI catalog. +keywords: Docker Hub, Hub, catalog +title: Docker Hub catalogs +linkTitle: Catalogs +weight: 60 +--- + +Docker Hub catalogs are your go-to collections of trusted, ready-to-use +container images and resources, tailored to meet specific development needs. +They make it easier to find high-quality, pre-verified content so you can +quickly build, deploy, and manage your applications with confidence. Catalogs in +Docker Hub: + +- Simplify content discovery: Organized and curated content makes it easy to + discover tools and resources tailored to your specific domain or technology. +- Reduce complexity: Trusted resources, vetted by Docker and its partners, + ensure security, reliability, and adherence to best practices. +- Accelerate development: Quickly integrate advanced capabilities into your + applications without the hassle of extensive research or setup. + +The generative AI catalog is the first catalog in Docker Hub, offering +specialized content for AI development. + +## Generative AI catalog + +The [generative AI catalog](https://hub.docker.com/catalogs/gen-ai) makes it +easy to explore and add AI capabilities to your applications. With trusted, +ready-to-use content and comprehensive documentation, you can skip the hassle of +sorting through countless tools and configurations. Instead, focus your time and +energy on creating innovative AI-powered applications. + +The generative AI catalog provides a wide range of trusted content, organized +into key areas to support diverse AI development needs: + +- Demos: Ready-to-deploy examples showcasing generative AI capabilities. These + demos provide a hands-on way to explore AI tools and frameworks, making it + easier to understand how they can be integrated into real-world applications. +- Models: Pre-trained AI models for tasks like text generation, + Natural Language Processing (NLP), and conversational AI. These models + provide a foundation for + AI applications without requiring developers to train models from scratch. +- Applications and end-to-end platforms: Comprehensive platforms and tools that + simplify AI application development, including low-code solutions and + frameworks for building multi-agent and Retrieval-Augmented Generation (RAG) + applications. +- Model deployment and serving: Tools and frameworks that enable developers to + efficiently deploy and serve AI models in production environments. These + resources include pre-configured stacks for GPUs and other specialized + hardware, ensuring performance at scale. +- Orchestration: Solutions for managing complex AI workflows, such as workflow + engines, Large Language Model (LLM) application frameworks, and lifecycle management + tools, to help streamline development and operations. +- Machine learning frameworks: Popular frameworks like TensorFlow and PyTorch + that provide the building blocks for creating, training, and fine-tuning + machine learning models. +- Databases: Databases optimized for AI workloads, including vector databases + for similarity search, time-series databases for analytics, and NoSQL + solutions for handling unstructured data. \ No newline at end of file diff --git a/content/manuals/docker-hub/mirror.md b/content/manuals/docker-hub/image-library/mirror.md similarity index 97% rename from content/manuals/docker-hub/mirror.md rename to content/manuals/docker-hub/image-library/mirror.md index 71cd160db95..7b993055cc9 100644 --- a/content/manuals/docker-hub/mirror.md +++ b/content/manuals/docker-hub/image-library/mirror.md @@ -2,12 +2,13 @@ description: Setting-up a local mirror for Docker Hub images keywords: registry, on-prem, images, tags, repository, distribution, mirror, Hub, recipe, advanced -title: Registry as a pull through cache -linkTitle: Mirroring +title: Mirror the Docker Hub library +linkTitle: Mirror weight: 80 aliases: - /engine/admin/registry_mirror/ - /registry/recipes/mirror/ +- /docker-hub/mirror/ --- ## Use-case @@ -37,7 +38,7 @@ Hub can be mirrored. > [!NOTE] > -> Mirrors of Docker Hub are still subject to Docker's [fair use policy](./download-rate-limit.md#fair-use). +> Mirrors of Docker Hub are still subject to Docker's [fair use policy](/manuals/docker-hub/download-rate-limit.md#fair-use). ### Solution diff --git a/content/manuals/docker-hub/image-library/search.md b/content/manuals/docker-hub/image-library/search.md new file mode 100644 index 00000000000..fff381ae49d --- /dev/null +++ b/content/manuals/docker-hub/image-library/search.md @@ -0,0 +1,167 @@ +--- +description: Discover how to browse and search Docker Hub's extensive resources. +keywords: Docker Hub, Hub, explore, search, image library +title: Docker Hub search +linkTitle: Search +weight: 10 +--- + +The [Docker Hub search interface](https://hub.docker.com/search) lets you +explore millions of resources. To help you find exactly what you need, it offers +a variety of filters that let you narrow your results or discover different +types of content. + +## Filters + +The search functionality includes filters to narrow down +results based on your requirements, such as products, categories, and trusted +content. This ensures that you can quickly find and access the resources best +suited to your project. + +### Products + +Docker Hub's content library features three products, each designed to meet +specific needs of developers and organizations. These products include images, +plugins, and extensions. + +#### Images + +Docker Hub hosts millions of container images, making it the go-to repository +for containerized applications and solutions. These images include: + +- Operating system images: Foundational images for Linux distributions like + Ubuntu, Debian, and Alpine, or Windows Server images. +- Database and storage images: Pre-configured databases such as MySQL, + PostgreSQL, and MongoDB to simplify application development. +- Languages and frameworks-based images: Popular images for Java, Python, + Node.js, Ruby, .NET, and more, offering pre-built environments for faster + development. + +Images in Docker Hub simplify the development process by providing pre-built, +reusable building blocks, reducing the need to start from scratch. Whether +you're a beginner building your first container or an enterprise managing +complex architectures, Docker Hub images provide a reliable foundation. + +#### Plugins + +Plugins in Docker Hub let you extend and customize Docker Engine to suit +specialized requirements. Plugins integrate directly with the Docker Engine and +provide capabilities such as: + +- Network plugins: Enhance networking functionality, enabling integration with + complex network infrastructures. +- Volume plugins: Provide advanced storage options, supporting persistent and + distributed storage across various backends. +- Authorization plugins: Offer fine-grained access control to secure Docker + environments. + +By leveraging Docker plugins, teams can tailor Docker Engine to meet their +specific operational needs, ensuring compatibility with existing infrastructures +and workflows. + +To learn more about plugins, see [Docker Engine managed plugin +system](/manuals/engine/extend/_index.md). + +#### Extensions + +Docker Hub offers extensions for Docker Desktop, which enhance its core +functionality. These extensions are purpose-built to streamline the software +development lifecycle. Extensions provide tools for: + +- System optimization and monitoring: Manage resources and optimize Docker + Desktop’s performance. +- Container management: Simplify container deployment and monitoring. +- Database management: Facilitate efficient database operations within + containers. +- Kubernetes and cloud integration: Bridge local environments with cloud-native + and Kubernetes workflows. +- Visualization tools: Gain insights into container resource usage through + graphical representations. + +Extensions help developers and teams create a more efficient and unified +workflow by reducing context switching and bringing essential tools into Docker +Desktop's interface. + +To learn more about extensions, see [Docker +Extensions](/manuals/extensions/_index.md). + +### Trusted content + +Docker Hub's trusted content provides a curated selection of high-quality, +secure images designed to give developers confidence in the reliability and +security of the resources they use. These images are stable, regularly updated, +and adhere to industry best practices, making them a strong foundation for +building and deploying applications. Docker Hub's trusted content includes, +Docker Official Images, Verified Publisher images, and Docker-Sponsored Open +Source Software images. + +For more details, see [Trusted content](./trusted-content.md). + +### Categories + +Docker Hub makes it easy to find and explore container images with categories. +Categories group images based on their primary use case, helping you quickly +locate the tools and resources you need to build, deploy, and run your +applications. + +{{< include "hub-categories.md" >}} + +### Operating systems + +The **Operating systems** filter lets you narrow your search to container +images compatible with specific host operating systems. This filter ensures that +the images you use align with your target environment, whether you're developing +for Linux-based systems, Windows, or both. + +- **Linux**: Access a wide range of images tailored for Linux environments. + These images provide foundational environments for building and running + Linux-based applications in containers. +- **Windows**: Explore Windows container images. + +> [!NOTE] +> +> The **Operating systems** filter is only available for images. If you select +> the **Extensions** or **Plugins** filter, then the **Operating systems** +> filter isn't available. + +### Architectures + +The **Architectures** filter lets you find images built to support specific CPU +architectures. This ensures compatibility with your hardware environment, from +development machines to production servers. + +- **ARM**: Select images compatible with ARM processors, commonly used in IoT + devices and embedded systems. +- **ARM 64**: Locate 64-bit ARM-compatible images for modern ARM processors, + such as those in AWS Graviton or Apple Silicon. +- **IBM POWER**: Find images optimized for IBM Power Systems, offering + performance and reliability for enterprise workloads. +- **PowerPC 64 LE**: Access images designed for the little-endian PowerPC 64-bit + architecture. +- **IBM Z**: Discover images tailored for IBM Z mainframes, ensuring + compatibility with enterprise-grade hardware. +- **x86**: Choose images compatible with 32-bit x86 architectures, suitable for + older systems or lightweight environments. +- **x86-64**: Filter images for modern 64-bit x86 systems, widely used in + desktops, servers, and cloud infrastructures. + +> [!NOTE] +> +> The **Architectures** filter is only available for images. If you select the +> **Extensions** or **Plugins** filter, then the **Architectures** filter isn't +> available. + +### Reviewed by Docker + +The **Reviewed by Docker** filter provides an extra layer of assurance when +selecting extensions. This filter helps you identify whether a Docker Desktop +extension has been reviewed by Docker for quality and reliability. + +- **Reviewed**: Extensions that have undergone Docker's review process, ensuring + they meet high standards. +- **Not Reviewed**: Extensions that have not been reviewed by Docker. + +> [!NOTE] +> +> The **Reviewed by Docker** filter is only available for extensions. To make +> the filter available, you must select only the **Extensions** filter in **Products**. \ No newline at end of file diff --git a/content/manuals/trusted-content/official-images/using.md b/content/manuals/docker-hub/image-library/trusted-content.md similarity index 53% rename from content/manuals/trusted-content/official-images/using.md rename to content/manuals/docker-hub/image-library/trusted-content.md index 21d0a2689ba..518ccfce6db 100644 --- a/content/manuals/trusted-content/official-images/using.md +++ b/content/manuals/docker-hub/image-library/trusted-content.md @@ -1,18 +1,62 @@ --- -title: Using Docker Official Images -description: | - Learn about building applications with Docker Official images - and how to interpret the tag names they use. -keywords: docker official images, doi, tags, slim, feedback, troubleshooting -weight: 10 +description: Learn about Docker Hub's trusted content. +keywords: Docker Hub, Hub, trusted content +title: Trusted content +weight: 15 +aliases: +- /trusted-content/official-images/using/ +- /trusted-content/official-images/ --- -Docker recommends you use the Docker Official Images in your projects. -These images have clear documentation, promote best practices, and are regularly updated. -Docker Official Images support most common use cases, making them perfect for new Docker users. -Advanced users can benefit from more specialized image variants as well as review Docker Official Images as part of your `Dockerfile` learning process. +Docker Hub's trusted content provides a curated selection of high-quality, +secure images designed to give developers confidence in the reliability and +security of the resources they use. These images are stable, regularly updated, +and adhere to industry best practices, making them a strong foundation for +building and deploying applications. Docker Hub's trusted content includes, +Docker Official Images, Verified Publisher images, and Docker-Sponsored Open +Source Software images. -## Tags +## Docker Official Images + +The Docker Official Images are a curated set of Docker repositories hosted on +Docker Hub. + +Docker recommends you use the Docker Official Images in your projects. These +images have clear documentation, promote best practices, and are regularly +updated. Docker Official Images support most common use cases, making them +perfect for new Docker users. Advanced users can benefit from more specialized +image variants as well as review Docker Official Images as part of your +`Dockerfile` learning process. + +> [!NOTE] +> +> Use of Docker Official Images is subject to [Docker's Terms of Service](https://www.docker.com/legal/docker-terms-service/). + +These images provide essential base repositories that serve as the starting +point for the majority of users. + +These include operating systems such as +[Ubuntu](https://hub.docker.com/_/ubuntu/) and +[Alpine](https://hub.docker.com/_/alpine/), programming language runtimes such as +[Python](https://hub.docker.com/_/python) and +[Node](https://hub.docker.com/_/node), and other essential tools such as +[memcached](https://hub.docker.com/_/memcached) and +[MySQL](https://hub.docker.com/_/mysql). + +The images are some of the [most secure images](https://www.docker.com/blog/enhancing-security-and-transparency-with-docker-official-images/) +on Docker Hub. This is particularly important as Docker Official Images are +some of the most popular on Docker Hub. Typically, Docker Official images have +few or no packages containing CVEs. + +The images exemplify [Dockerfile best practices](/manuals/build/building/best-practices.md) +and provide clear documentation to serve as a reference for other Dockerfile authors. + +Images that are part of this program have a special badge on Docker Hub making +it easier for you to identify projects that are part of Docker Official Images. + +![Docker official image badge](../images/official-image-badge-iso.png) + +### Supported tags and respective Dockerfile links The repository description for each Docker Official Image contains a **Supported tags and respective Dockerfile links** section that lists all the @@ -34,7 +78,7 @@ use or are unfamiliar with the underlying software, you should probably start wi the `latest` image. As your understanding of the software and image variants advances, you may find other image variants better suit your needs. -## Slim images +### Slim images A number of language stacks such as [Node.js](https://hub.docker.com/_/node/), @@ -62,7 +106,7 @@ COPY --from=build /app /app CMD ["node", "app.js"] ``` -## Alpine images +### Alpine images Many Docker Official Images repositories also offer `alpine` variants. These images are built on top of the [Alpine Linux](https://www.alpinelinux.org/) @@ -90,7 +134,7 @@ to make your program compatible with Alpine Linux and musl: Refer to the `alpine` image [description](https://hub.docker.com/_/alpine) on Docker Hub for examples on how to install packages if you are unfamiliar. -## Codenames +### Codenames Tags with words that look like Toy Story characters (for example, `bookworm`, `bullseye`, and `trixie`) or adjectives (such as `focal`, `jammy`, and @@ -103,11 +147,37 @@ Linux distribution indicators are helpful because many Docker Official Images provide variants built upon multiple underlying distribution versions (for example, `postgres:bookworm` and `postgres:bullseye`). -## Other tags +### Other tags Docker Official Images tags may contain other hints to the purpose of their image variant in addition to those described here. Often these tag variants are explained in the Docker Official Images repository -documentation. Reading through the “How to use this image” and -“Image Variants” sections will help you to understand how to use these +documentation. Reading through the "How to use this image" and +"Image Variants" sections will help you to understand how to use these variants. + +## Verified Publisher images + +The Docker Verified Publisher program provides high-quality images from +commercial publishers verified by Docker. + +These images help development teams build secure software supply chains, +minimizing exposure to malicious content early in the process to save time and +money later. + +Images that are part of this program have a special badge on Docker Hub making +it easier for users to identify projects that Docker has verified as +high-quality commercial publishers. + +![Docker-Sponsored Open Source badge](../images/verified-publisher-badge-iso.png) + +## Docker-Sponsored Open Source Software images + +The Docker-Sponsored Open Source Software (OSS) program provides images that are +published and maintained by open-source projects sponsored by Docker. + +Images that are part of this program have a special badge on Docker Hub making +it easier for users to identify projects that Docker has verified as trusted, +secure, and active open-source projects. + +![Docker-Sponsored Open Source badge](../images/sponsored-badge-iso.png) \ No newline at end of file diff --git a/content/manuals/trusted-content/images/chart-share-icon.png b/content/manuals/docker-hub/images/chart-share-icon.png similarity index 100% rename from content/manuals/trusted-content/images/chart-share-icon.png rename to content/manuals/docker-hub/images/chart-share-icon.png diff --git a/content/manuals/trusted-content/images/chart.png b/content/manuals/docker-hub/images/chart.png similarity index 100% rename from content/manuals/trusted-content/images/chart.png rename to content/manuals/docker-hub/images/chart.png diff --git a/content/manuals/trusted-content/images/clear_logo_sm.png b/content/manuals/docker-hub/images/clear_logo_sm.png similarity index 100% rename from content/manuals/trusted-content/images/clear_logo_sm.png rename to content/manuals/docker-hub/images/clear_logo_sm.png diff --git a/content/manuals/trusted-content/images/default_logo_sm.png b/content/manuals/docker-hub/images/default_logo_sm.png similarity index 100% rename from content/manuals/trusted-content/images/default_logo_sm.png rename to content/manuals/docker-hub/images/default_logo_sm.png diff --git a/content/manuals/trusted-content/images/download-analytics-data.png b/content/manuals/docker-hub/images/download-analytics-data.png similarity index 100% rename from content/manuals/trusted-content/images/download-analytics-data.png rename to content/manuals/docker-hub/images/download-analytics-data.png diff --git a/content/manuals/trusted-content/images/official-image-badge-iso.png b/content/manuals/docker-hub/images/official-image-badge-iso.png similarity index 100% rename from content/manuals/trusted-content/images/official-image-badge-iso.png rename to content/manuals/docker-hub/images/official-image-badge-iso.png diff --git a/content/manuals/trusted-content/images/organization-tabs.png b/content/manuals/docker-hub/images/organization-tabs.png similarity index 100% rename from content/manuals/trusted-content/images/organization-tabs.png rename to content/manuals/docker-hub/images/organization-tabs.png diff --git a/content/manuals/trusted-content/images/sponsored-badge-iso.png b/content/manuals/docker-hub/images/sponsored-badge-iso.png similarity index 100% rename from content/manuals/trusted-content/images/sponsored-badge-iso.png rename to content/manuals/docker-hub/images/sponsored-badge-iso.png diff --git a/content/manuals/trusted-content/images/sponsored-badge.png b/content/manuals/docker-hub/images/sponsored-badge.png similarity index 100% rename from content/manuals/trusted-content/images/sponsored-badge.png rename to content/manuals/docker-hub/images/sponsored-badge.png diff --git a/content/manuals/trusted-content/images/supported_tags.webp b/content/manuals/docker-hub/images/supported_tags.webp similarity index 100% rename from content/manuals/trusted-content/images/supported_tags.webp rename to content/manuals/docker-hub/images/supported_tags.webp diff --git a/content/manuals/trusted-content/images/upload_logo_sm.png b/content/manuals/docker-hub/images/upload_logo_sm.png similarity index 100% rename from content/manuals/trusted-content/images/upload_logo_sm.png rename to content/manuals/docker-hub/images/upload_logo_sm.png diff --git a/content/manuals/trusted-content/images/verified-publisher-badge-iso.png b/content/manuals/docker-hub/images/verified-publisher-badge-iso.png similarity index 100% rename from content/manuals/trusted-content/images/verified-publisher-badge-iso.png rename to content/manuals/docker-hub/images/verified-publisher-badge-iso.png diff --git a/content/manuals/trusted-content/images/verified-publisher-badge.png b/content/manuals/docker-hub/images/verified-publisher-badge.png similarity index 100% rename from content/manuals/trusted-content/images/verified-publisher-badge.png rename to content/manuals/docker-hub/images/verified-publisher-badge.png diff --git a/content/manuals/docker-hub/quickstart.md b/content/manuals/docker-hub/quickstart.md index 91e3a37e374..6d1f1d29fd0 100644 --- a/content/manuals/docker-hub/quickstart.md +++ b/content/manuals/docker-hub/quickstart.md @@ -22,14 +22,16 @@ through creating a custom image and sharing it through Docker Hub. ## Step 1: Find an image in Docker Hub's library You can search for content in Docker Hub itself, in the Docker Desktop -Dashboard, or by using the `docker search` CLI command. Searching on Docker Hub -itself offers the most options to explore content. +Dashboard, or by using the CLI. To search or browse for content on Docker Hub: +{{< tabs >}} +{{< tab name="Docker Hub" >}} + 1. Navigate to the [Docker Hub Explore page](https://hub.docker.com/explore). - On the Explore page, you can browse by catalog or category, or use the search + On the **Explore** page, you can browse by catalog or category, or use the search to quickly find content. 2. Under **Categories**, select **Web servers**. @@ -48,11 +50,88 @@ To search or browse for content on Docker Hub: to use the image. On the page, you'll also find the `docker pull` command to pull the image. +{{< /tab >}} +{{< tab name="Docker Desktop" >}} + +1. Open the Docker Desktop Dashboard. +2. Select the **Docker Hub** view. + + In the **Docker Hub** view, you can browse by catalog or category, or use the search + to quickly find content. + +3. Leave the search box empty and then select **Search**. + + The search results are shown with additional filters now next to the search box. + +4. Select the search filter icon, and then select **Docker Official Image** and **Web Servers**. +5. In the results, select the **nginx** image. + +{{< /tab >}} +{{< tab name="CLI" >}} + +1. Open a terminal window. + + > [!TIP] + > + > The Docker Desktop Dashboard contains a built-in terminal. At the bottom of + > the Dashboard, select **>_ Terminal** to open it. + +2. In the terminal, run the following command. + + ```console + $ docker search --filter is-official=true nginx + ``` + + Unlike the Docker Hub and Docker Desktop interfaces, you can't browse by + category using the `docker search` command. For more details about the + command, see [docker search](/reference/cli/docker/search/). + +{{< /tab >}} +{{< /tabs >}} + Now that you've found an image, it's time to pull and run it on your device. ## Step 2: Pull and run an image from Docker Hub -1. In your terminal, run the following command to pull and run the Nginx image. +You can run images from Docker Hub using the CLI or Docker Desktop Dashboard. + +{{< tabs >}} +{{< tab name="Docker Desktop" >}} + +1. In the Docker Desktop Dashboard, select the **nginx** image in the **Docker + Hub** view. For more details, see [Step 1: Find an image in Docker Hub's + library](#step-1-find-an-image-in-docker-hubs-library). + +2. On the **nginx** screen, select **Run**. + + If the image doesn't exist on your device, it is automatically pulled from + Docker Hub. Pulling the image may take a few seconds or minutes depending on + your connection. After the image has been pulled, a window appears in Docker + Desktop and you can specify run options. + +3. In the **Host port** option, specify `8080`. +4. Select **Run**. + + The container logs appear after the container starts. + +5. Select the **8080:80** link to open the server, or visit + [https://localhost:8080](https://localhost:8080) in your web browser. + +6. In the Docker Desktop Dashboard, select the **Stop** button to stop the + container. + + +{{< /tab >}} +{{< tab name="CLI" >}} + +1. Open a terminal window. + + > [!TIP] + > + > The Docker Desktop Dashboard contains a built-in terminal. At the bottom of + > the Dashboard, select **>_ Terminal** to open it. + +2. In your terminal, run the following command to pull and run the Nginx image. ```console $ docker run -p 8080:80 --rm nginx @@ -95,22 +174,26 @@ Now that you've found an image, it's time to pull and run it on your device. ... ``` -2. Visit [https://localhost:8080](https://localhost:8080) to view the default +3. Visit [https://localhost:8080](https://localhost:8080) to view the default Nginx page and verify that the container is running. -3. In the terminal, press CTRL+C to stop the container. +4. In the terminal, press Ctrl+C to stop the container. -You've now run a web server without any set up or configuration, all from a -single command. Docker Hub provides instant access to pre-built, ready-to-use -container images, letting you quickly pull and run applications without needing -to install or configure software manually. With Docker Hub's vast library of -images, you can experiment with and deploy applications effortlessly, boosting -productivity and making it easy to try out new tools, set up development -environments, or build on top of existing software. +{{< /tab >}} +{{< /tabs >}} + +You've now run a web server without any set up or configuration. Docker Hub +provides instant access to pre-built, ready-to-use container images, letting you +quickly pull and run applications without needing to install or configure +software manually. With Docker Hub's vast library of images, you can experiment +with and deploy applications effortlessly, boosting productivity and making it +easy to try out new tools, set up development environments, or build on top of +existing software. You can also extend images from Docker Hub, letting you quickly build and customize your own images to suit specific needs. + ## Step 3: Build and push an image to Docker Hub 1. Create a [Dockerfile](/reference/dockerfile.md) to specify your application: @@ -201,6 +284,11 @@ customize your own images to suit specific needs. ## Step 4: View your repository on Docker Hub and explore options +You can view your Docker Hub repositories in the Docker Hub or Docker Desktop interface. + +{{< tabs >}} +{{< tab name="Docker Hub" >}} + 1. Go to [Docker Hub](https://hub.docker.com) and sign in. After signing in, you should be on the **Repositories** page. If not, then go @@ -211,6 +299,22 @@ customize your own images to suit specific needs. After selecting the repository, you should see more details and options for your repository. +{{< /tab >}} +{{< tab name="Docker Desktop" >}} + +1. Sign in to Docker Desktop. +2. Select the **Images** view. +3. Select the **Hub repositories** tab. + + A list of your Docker Hub repositories appears. + +4. Find the **nginx-custom** repository, hover over the row, and then select **View in Hub**. + + Docker Hub opens and you are able to view more details about the image. + +{{< /tab >}} +{{< /tabs >}} + You've now verified that your repository exists on Docker Hub, and you've discovered more options for it. View the next steps to learn more about some of these options. diff --git a/content/manuals/docker-hub/repos/_index.md b/content/manuals/docker-hub/repos/_index.md index 5ead03bebe3..7554387ac2f 100644 --- a/content/manuals/docker-hub/repos/_index.md +++ b/content/manuals/docker-hub/repos/_index.md @@ -47,6 +47,11 @@ In this section, learn how to: Bitbucket for automated builds. Every code change triggers an image rebuild, supporting continuous integration and delivery. + - [Trusted content](./manage/trusted-content/_index.md): Contribute to Docker + Official Images or manage repositories in the Verified Publisher and + Sponsored Open Source programs, including tasks like setting logos, + accessing analytics, and enabling vulnerability scanning. + - [Archive](./archive.md) an outdated or unsupported repository. - [Delete](./delete.md) a repository. - [Manage personal settings](./settings.md): For your account, you can set personal diff --git a/content/manuals/docker-hub/repos/manage/hub-images/push.md b/content/manuals/docker-hub/repos/manage/hub-images/push.md index 0c3b468ed44..a9a1f028452 100644 --- a/content/manuals/docker-hub/repos/manage/hub-images/push.md +++ b/content/manuals/docker-hub/repos/manage/hub-images/push.md @@ -36,9 +36,9 @@ images with others or use them in different environments. Example: ```console - $ docker push my-app my-namespace/my-repo:v1.0 + $ docker push my-namespace/my-repo:v1.0 ``` This command pushes the image tagged `v1.0` to the `my-namespace/my-repo` repository. -3. Verify the image on Docker Hub. \ No newline at end of file +3. Verify the image on Docker Hub. diff --git a/content/manuals/docker-hub/repos/manage/information.md b/content/manuals/docker-hub/repos/manage/information.md index 0edff44ca97..06f494da5a4 100644 --- a/content/manuals/docker-hub/repos/manage/information.md +++ b/content/manuals/docker-hub/repos/manage/information.md @@ -113,40 +113,8 @@ explore content for the problem domain that they're interested in. ### Available categories The Docker Hub content team maintains a curated list of categories. -The available categories are: - -- **API Management**: Tools for creating, publishing, analyzing, and securing - APIs. -- **Content Management System:** Software applications to create and manage - digital content through templates, procedures, and standard formats. -- **Data Science:** Tools and software to support analyzing data and generating - actionable insights. -- **Databases & Storage:** Systems for storing, retrieving, and managing data. -- **Languages & Frameworks:** Programming language runtimes and frameworks. -- **Integrations & Delivery:** Tools for Continuous Integration (CI) and - Continuous Delivery (CD). -- **Internet of Things:** Tools supporting Internet of Things (IoT) - applications. -- **Machine Learning & AI:** Tools and frameworks optimized for artificial - intelligence and machine learning projects, such as pre-installed libraries - and frameworks for data analysis, model training, and deployment. -- **Message Queues:** Message queuing systems optimized for reliable, scalable, - and efficient message handling. -- **Monitoring & Observability:** Tools to track software and system performance - through metrics, logs, and traces, as well as observability to explore the - system’s state and diagnose issues. -- **Networking:** Repositories that support data exchange and connecting - computers and other devices to share resources. -- **Operating Systems:** Software that manages all other programs on a computer - and serves as an intermediary between users and the computer hardware, while - overseeing applications and system resources. -- **Security:** Tools to protect a computer system or network from theft, - unauthorized access, or damage to their hardware, software, or electronic - data, as well as from service disruption. -- **Web Servers:** Software to serve web pages, HTML files, and other assets to - users or other systems. -- **Web Analytics:** Tools to collect, measure, analyze, and report on web data - and website visitor engagement. + +{{< include "hub-categories.md" >}} ### Auto-generated categories diff --git a/content/manuals/docker-hub/repos/manage/trusted-content/_index.md b/content/manuals/docker-hub/repos/manage/trusted-content/_index.md new file mode 100644 index 00000000000..3b29c8873da --- /dev/null +++ b/content/manuals/docker-hub/repos/manage/trusted-content/_index.md @@ -0,0 +1,30 @@ +--- +description: Learn how to manage and contribute to trusted content. +keywords: Docker Hub, Hub, trusted content +title: Trusted content +weight: 100 +--- + +Docker's trusted content programs ensure that container images meet the highest +standards for security, quality, and reliability. These programs provide +opportunities for publishers and contributors to share their images with +millions of developers worldwide while gaining valuable insights into their +content's usage. By participating, you can enhance your content's visibility, +build credibility, and access tools to optimize its impact within the container +ecosystem. + +In this section, learn about: + +- [Docker Official Images](./official-images.md): Learn how to contribute, + propose, and maintain Docker Official Images to serve as reliable foundations + for containerized applications. +- [Docker-Sponsored Open Source (DSOS) Program](dsos-program.md): Discover how + open source projects can gain perks like verified badges, insights, and access + to Docker Scout, enhancing visibility and trust on Docker Hub. +- [Docker Verified Publisher (DVP) Program](./dvp-program.md): Explore how to + join the DVP program to showcase trusted, high-quality images with a verified + badge, gain priority in search results, access insights, and enhance security + through vulnerability analysis. +- [Insights and analytics](./insights-analytics.md): Access detailed metrics on + image and extension usage, including pull counts, geolocation, and client + data, to understand user behavior and optimize your content. \ No newline at end of file diff --git a/content/manuals/trusted-content/dsos-program.md b/content/manuals/docker-hub/repos/manage/trusted-content/dsos-program.md similarity index 87% rename from content/manuals/trusted-content/dsos-program.md rename to content/manuals/docker-hub/repos/manage/trusted-content/dsos-program.md index 8b686508a41..ee404d7db33 100644 --- a/content/manuals/trusted-content/dsos-program.md +++ b/content/manuals/docker-hub/repos/manage/trusted-content/dsos-program.md @@ -4,15 +4,14 @@ title: Docker-Sponsored Open Source Program keywords: docker hub, hub, insights, analytics, open source, Docker sponsored, program aliases: - /docker-hub/dsos-program/ + - /trusted-content/dsos-program/ --- -[Docker Sponsored Open Source images](https://hub.docker.com/search?q=&image_filter=open_source) are published and maintained by open-source projects sponsored by Docker through the program. +[Docker-Sponsored Open Source images](https://hub.docker.com/search?q=&image_filter=open_source) are published and maintained by open-source projects sponsored by Docker through the program. Images that are part of this program have a special badge on Docker Hub making it easier for users to identify projects that Docker has verified as trusted, secure, and active open-source projects. -![Docker-Sponsored Open Source badge](images/sponsored-badge-iso.png) - -## For content publishers +![Docker-Sponsored Open Source badge](../../../images/sponsored-badge-iso.png) The Docker-Sponsored Open Source (DSOS) Program provides several features and benefits to non-commercial open source developers. @@ -47,25 +46,25 @@ over the repository can change the repository logo. 1. Sign in to [Docker Hub](https://hub.docker.com). 2. Go to the page of the repository that you want to change the logo for. 3. Select the upload logo button, represented by a camera icon - ({{< inline-image src="images/upload_logo_sm.png" alt="camera icon" >}}) + ({{< inline-image src="../../../images/upload_logo_sm.png" alt="camera icon" >}}) overlaying the current repository logo. 4. In the dialog that opens, select the PNG image that you want to upload to set it as the logo for the repository. #### Remove the logo -Select the **Clear** button ({{< inline-image src="images/clear_logo_sm.png" +Select the **Clear** button ({{< inline-image src="../../../images/clear_logo_sm.png" alt="clear button" >}}) to remove a logo. Removing the logo makes the repository default to using the organization logo, if set, or the following default logo if not. -![Default logo which is a 3D grey cube](images/default_logo_sm.png) +![Default logo which is a 3D grey cube](../../../images/default_logo_sm.png) ### Verified Docker-Sponsored Open Source badge Docker verifies that developers can trust images with this badge on Docker Hub as an active open source project. -![Fluent org with a Docker-Sponsored Open Source badge](images/sponsored-badge.png) +![Fluent org with a Docker-Sponsored Open Source badge](../../../images/sponsored-badge.png) ### Insights and analytics @@ -75,8 +74,6 @@ the community uses Docker images, granting insight into user behavior. The usage metrics show the number of image pulls by tag or by digest, and breakdowns by geolocation, cloud provider, client, and more. -![The insights and analytics tab on the Docker Hub website](images/insights-and-analytics-tab.png) - You can select the time span for which you want to view analytics data. You can also export the data in either a summary or raw format. ### Docker Scout diff --git a/content/manuals/trusted-content/dvp-program.md b/content/manuals/docker-hub/repos/manage/trusted-content/dvp-program.md similarity index 86% rename from content/manuals/trusted-content/dvp-program.md rename to content/manuals/docker-hub/repos/manage/trusted-content/dvp-program.md index ed92b925957..39f75d10d30 100644 --- a/content/manuals/trusted-content/dvp-program.md +++ b/content/manuals/docker-hub/repos/manage/trusted-content/dvp-program.md @@ -13,6 +13,7 @@ aliases: - /docker-hub/publish/ - /docker-hub/publish/repository-logos/ - /docker-hub/dvp-program/ +- /trusted-content/dvp-program/ --- [The Docker Verified Publisher Program](https://hub.docker.com/search?q=&image_filter=store) provides high-quality images from commercial publishers verified by Docker. @@ -21,9 +22,7 @@ These images help development teams build secure software supply chains, minimiz Images that are part of this program have a special badge on Docker Hub making it easier for users to identify projects that Docker has verified as high-quality commercial publishers. -![Docker-Sponsored Open Source badge](./images/verified-publisher-badge-iso.png) - -## For content publishers +![Docker-Sponsored Open Source badge](../../../images/verified-publisher-badge-iso.png) The Docker Verified Publisher Program (DVP) provides several features and benefits to Docker Hub publishers. The program grants the following perks based on participation tier: @@ -57,37 +56,35 @@ over the repository can change the repository logo. 1. Sign in to [Docker Hub](https://hub.docker.com). 2. Go to the page of the repository that you want to change the logo for. 3. Select the upload logo button, represented by a camera icon ({{< inline-image - src="./images/upload_logo_sm.png" alt="camera icon" >}}) overlaying the + src="../../../images/upload_logo_sm.png" alt="camera icon" >}}) overlaying the current repository logo. 4. In the dialog that opens, select the PNG image that you want to upload to set it as the logo for the repository. #### Remove the logo -Select the **Clear** button ({{< inline-image src="images/clear_logo_sm.png" +Select the **Clear** button ({{< inline-image src="../../../images/clear_logo_sm.png" alt="clear button" >}}) to remove a logo. Removing the logo makes the repository default to using the organization logo, if set, or the following default logo if not. -![Default logo which is a 3D grey cube](images/default_logo_sm.png) +![Default logo which is a 3D grey cube](../../../images/default_logo_sm.png) ### Verified publisher badge Images that are part of this program have a badge on Docker Hub making it easier for developers to identify projects that Docker has verified as high quality publishers and with content they can trust. -![Docker, Inc. org with a verified publisher badge](./images/verified-publisher-badge.png) +![Docker, Inc. org with a verified publisher badge](../../../images/verified-publisher-badge.png) ### Insights and analytics -The [insights and analytics](/docker-hub/publish/insights-analytics) service provides usage metrics for how +The [insights and analytics](./insights-analytics.md) service provides usage metrics for how the community uses Docker images, granting insight into user behavior. The usage metrics show the number of image pulls by tag or by digest, and breakdowns by geolocation, cloud provider, client, and more. -![The insights and analytics tab on the Docker Hub website](./images/insights-and-analytics-tab.png) - You can select the time span for which you want to view analytics data. You can also export the data in either a summary or raw format. ### Vulnerability analysis diff --git a/content/manuals/trusted-content/insights-analytics.md b/content/manuals/docker-hub/repos/manage/trusted-content/insights-analytics.md similarity index 98% rename from content/manuals/trusted-content/insights-analytics.md rename to content/manuals/docker-hub/repos/manage/trusted-content/insights-analytics.md index c2dead2bbdc..0ffd17abcb5 100644 --- a/content/manuals/trusted-content/insights-analytics.md +++ b/content/manuals/docker-hub/repos/manage/trusted-content/insights-analytics.md @@ -5,6 +5,7 @@ keywords: docker hub, hub, insights, analytics, api, verified publisher aliases: - /docker-hub/publish/insights-analytics/ - /docker-hub/insights-analytics/ +- /trusted-content/insights-analytics/ --- Insights and analytics provides usage analytics for Docker Verified @@ -31,7 +32,7 @@ To view data in the chart: - Select the time interval: 3, 6, or 12 months - Select one or more repositories in the list -![Insights and analytics chart visualization](./images/chart.png) +![Insights and analytics chart visualization](../../../images/chart.png) > [!TIP] @@ -44,7 +45,7 @@ To view data in the chart: You can share the visualization with others using the **Share** icon above the chart. This is a convenient way to share statistics with others in your organization. -![Chart share icon](./images/chart-share-icon.png) +![Chart share icon](../../../images/chart-share-icon.png) Selecting the icon generates a link that's copied to your clipboard. The link preserves the display selections you made. When someone follows the link, the @@ -75,14 +76,14 @@ Export usage data for your organization's images using the Docker Hub website by 2. Choose your organization and select **Insights and analytics**. - ![Organization overview page, with the Insights and Analytics tab](./images/organization-tabs.png) + ![Organization overview page, with the Insights and Analytics tab](../../../images/organization-tabs.png) 3. Set the time span for which you want to export analytics data. The downloadable CSV files for summary and raw data appear on the right-hand side. - ![Filtering options and download links for analytics data](./images/download-analytics-data.png) + ![Filtering options and download links for analytics data](../../../images/download-analytics-data.png) ### Export data using the API diff --git a/content/manuals/trusted-content/official-images/contributing.md b/content/manuals/docker-hub/repos/manage/trusted-content/official-images.md similarity index 95% rename from content/manuals/trusted-content/official-images/contributing.md rename to content/manuals/docker-hub/repos/manage/trusted-content/official-images.md index 48189a44218..206ee0eaa55 100644 --- a/content/manuals/trusted-content/official-images/contributing.md +++ b/content/manuals/docker-hub/repos/manage/trusted-content/official-images.md @@ -1,9 +1,13 @@ --- -title: Contributing to Docker Official Images +title: Docker Official Images description: | This article describes how Docker Official Images are created, and how you can contribute or leave feedback. keywords: docker official images, doi, contributing, upstream, open source +aliases: +- /trusted-content/official-images/contributing/ +- /docker-hub/official_repos/ +- /docker-hub/official_images/ --- Docker, Inc. sponsors a dedicated team that's responsible for reviewing and diff --git a/content/manuals/docker-hub/service-accounts.md b/content/manuals/docker-hub/service-accounts.md index a9f4d5db9bb..845ebd96670 100644 --- a/content/manuals/docker-hub/service-accounts.md +++ b/content/manuals/docker-hub/service-accounts.md @@ -20,10 +20,6 @@ weight: 50 A service account is a Docker ID used for automated management of container images or containerized applications. Service accounts are typically used in automated workflows, and don't share Docker IDs with the members in the organization. Common use cases for service accounts include mirroring content on Docker Hub, or tying in image pulls from your CI/CD process. -> [!NOTE] -> -> All paid Docker subscriptions include up to 5000 pulls per day per authenticated user. If you require a higher number of pulls, you can purchase an Enhanced Service Account add-on. Note that you can only purchase an Enhanced Service Account add-on if you are on a current Service Account agreement. - ## Enhanced Service Account add-on tiers Refer to the following table for details on the Enhanced Service Account add-ons: @@ -36,4 +32,4 @@ Refer to the following table for details on the Enhanced Service Account add-ons | 4 | 50,000-100,000 | | 5 | 100,000+ | -*The service account may exceed Pulls by up to 25% for up to 20 days during the year without incurring additional fees. Reports on consumption are available upon request. +*The service account may exceed Pulls by up to 25% for up to 20 days during the year without incurring additional fees. Reports on consumption are available upon request. \ No newline at end of file diff --git a/content/manuals/engine/daemon/prometheus.md b/content/manuals/engine/daemon/prometheus.md index a4dbdeb6210..5e194d627da 100644 --- a/content/manuals/engine/daemon/prometheus.md +++ b/content/manuals/engine/daemon/prometheus.md @@ -48,8 +48,10 @@ Add the following configuration: Save the file, or in the case of Docker Desktop for Mac or Docker Desktop for Windows, save the configuration. Restart Docker. -Docker now exposes Prometheus-compatible metrics on port 9323 on the loopback -interface. +Docker now exposes Prometheus-compatible metrics on port 9323 via the loopback +interface. You can configure it to use the wildcard address `0.0.0.0` instead, +but this will expose the Prometheus port to the wider network. Consider your +threat model carefully when deciding which option best suits your environment. ### Create a Prometheus configuration diff --git a/content/manuals/engine/install/centos.md b/content/manuals/engine/install/centos.md index 08246fbe3cd..a79b2cd0535 100644 --- a/content/manuals/engine/install/centos.md +++ b/content/manuals/engine/install/centos.md @@ -119,8 +119,8 @@ $ sudo dnf config-manager --add-repo {{% param "download-url-base" %}}/docker-ce ```console $ dnf list docker-ce --showduplicates | sort -r - docker-ce.x86_64 3:27.4.0-1.el9 docker-ce-stable - docker-ce.x86_64 3:27.3.1-1.el9 docker-ce-stable + docker-ce.x86_64 3:{{% param "docker_ce_version" %}}-1.el9 docker-ce-stable + docker-ce.x86_64 3:{{% param "docker_ce_version_prev" %}}-1.el9 docker-ce-stable <...> ``` @@ -129,7 +129,7 @@ $ sudo dnf config-manager --add-repo {{% param "download-url-base" %}}/docker-ce Install a specific version by its fully qualified package name, which is the package name (`docker-ce`) plus the version string (2nd column), - separated by a hyphen (`-`). For example, `docker-ce-3:27.4.0-1.el9`. + separated by a hyphen (`-`). For example, `docker-ce-3:{{% param "docker_ce_version" %}}-1.el9`. Replace `` with the desired version and then run the following command to install: diff --git a/content/manuals/engine/install/debian.md b/content/manuals/engine/install/debian.md index 8ba4241e5b6..1a0e17c9f10 100644 --- a/content/manuals/engine/install/debian.md +++ b/content/manuals/engine/install/debian.md @@ -155,15 +155,15 @@ Docker from the repository. # List the available versions: $ apt-cache madison docker-ce | awk '{ print $3 }' - 5:27.4.0-1~debian.12~bookworm - 5:27.3.1-1~debian.12~bookworm + 5:{{% param "docker_ce_version" %}}-1~debian.12~bookworm + 5:{{% param "docker_ce_version_prev" %}}-1~debian.12~bookworm ... ``` Select the desired version and install: ```console - $ VERSION_STRING=5:27.4.0-1~debian.12~bookworm + $ VERSION_STRING=5:{{% param "docker_ce_version" %}}-1~debian.12~bookworm $ sudo apt-get install docker-ce=$VERSION_STRING docker-ce-cli=$VERSION_STRING containerd.io docker-buildx-plugin docker-compose-plugin ``` diff --git a/content/manuals/engine/install/fedora.md b/content/manuals/engine/install/fedora.md index d2b1d80963a..9ee612c60cf 100644 --- a/content/manuals/engine/install/fedora.md +++ b/content/manuals/engine/install/fedora.md @@ -116,8 +116,8 @@ $ sudo dnf-3 config-manager --add-repo {{% param "download-url-base" %}}/docker- ```console $ dnf list docker-ce --showduplicates | sort -r - docker-ce.x86_64 3:27.4.0-1.fc41 docker-ce-stable - docker-ce.x86_64 3:27.3.1-1.fc41 docker-ce-stable + docker-ce.x86_64 3:{{% param "docker_ce_version" %}}-1.fc41 docker-ce-stable + docker-ce.x86_64 3:{{% param "docker_ce_version_prev" %}}-1.fc41 docker-ce-stable <...> ``` @@ -126,7 +126,7 @@ $ sudo dnf-3 config-manager --add-repo {{% param "download-url-base" %}}/docker- Install a specific version by its fully qualified package name, which is the package name (`docker-ce`) plus the version string (2nd column), - separated by a hyphen (`-`). For example, `docker-ce-3:27.4.0-1.fc41`. + separated by a hyphen (`-`). For example, `docker-ce-3:{{% param "docker_ce_version" %}}-1.fc41`. Replace `` with the desired version and then run the following command to install: diff --git a/content/manuals/engine/install/raspberry-pi-os.md b/content/manuals/engine/install/raspberry-pi-os.md index 9cfd020e907..ca4d69caedd 100644 --- a/content/manuals/engine/install/raspberry-pi-os.md +++ b/content/manuals/engine/install/raspberry-pi-os.md @@ -143,15 +143,15 @@ Docker from the repository. # List the available versions: $ apt-cache madison docker-ce | awk '{ print $3 }' - 5:27.4.0-1~raspbian.12~bookworm - 5:27.3.1-1~raspbian.12~bookworm + 5:{{% param "docker_ce_version" %}}-1~raspbian.12~bookworm + 5:{{% param "docker_ce_version_prev" %}}-1~raspbian.12~bookworm ... ``` Select the desired version and install: ```console - $ VERSION_STRING=5:27.4.0-1~raspbian.12~bookworm + $ VERSION_STRING=5:{{% param "docker_ce_version" %}}-1~raspbian.12~bookworm $ sudo apt-get install docker-ce=$VERSION_STRING docker-ce-cli=$VERSION_STRING containerd.io docker-buildx-plugin docker-compose-plugin ``` diff --git a/content/manuals/engine/install/rhel.md b/content/manuals/engine/install/rhel.md index 9e9877038e3..e0678357fc2 100644 --- a/content/manuals/engine/install/rhel.md +++ b/content/manuals/engine/install/rhel.md @@ -119,8 +119,8 @@ $ sudo dnf config-manager --add-repo {{% param "download-url-base" %}}/docker-ce ```console $ dnf list docker-ce --showduplicates | sort -r - docker-ce.x86_64 3:27.4.0-1.el9 docker-ce-stable - docker-ce.x86_64 3:27.3.1-1.el9 docker-ce-stable + docker-ce.x86_64 3:{{% param "docker_ce_version" %}}-1.el9 docker-ce-stable + docker-ce.x86_64 3:{{% param "docker_ce_version_prev" %}}-1.el9 docker-ce-stable <...> ``` @@ -129,7 +129,7 @@ $ sudo dnf config-manager --add-repo {{% param "download-url-base" %}}/docker-ce Install a specific version by its fully qualified package name, which is the package name (`docker-ce`) plus the version string (2nd column), - separated by a hyphen (`-`). For example, `docker-ce-3:27.4.0-1.el9`. + separated by a hyphen (`-`). For example, `docker-ce-3:{{% param "docker_ce_version" %}}-1.el9`. Replace `` with the desired version and then run the following command to install: diff --git a/content/manuals/engine/install/sles.md b/content/manuals/engine/install/sles.md index 6a9313fb0b7..b148e60a1b1 100644 --- a/content/manuals/engine/install/sles.md +++ b/content/manuals/engine/install/sles.md @@ -140,8 +140,8 @@ $ sudo zypper addrepo {{% param "download-url-base" %}}/docker-ce.repo ```console $ sudo zypper search -s --match-exact docker-ce | sort -r - v | docker-ce | package | 3:27.4.0-1 | s390x | Docker CE Stable - s390x - v | docker-ce | package | 3:27.3.1-1 | s390x | Docker CE Stable - s390x + v | docker-ce | package | 3:{{% param "docker_ce_version" %}}-1 | s390x | Docker CE Stable - s390x + v | docker-ce | package | 3:{{% param "docker_ce_version_prev" %}}-1 | s390x | Docker CE Stable - s390x ``` The list returned depends on which repositories are enabled, and is specific @@ -149,7 +149,7 @@ $ sudo zypper addrepo {{% param "download-url-base" %}}/docker-ce.repo Install a specific version by its fully qualified package name, which is the package name (`docker-ce`) plus the version string (2nd column), - separated by a hyphen (`-`). For example, `docker-ce-3:27.4.0`. + separated by a hyphen (`-`). For example, `docker-ce-3:{{% param "docker_ce_version" %}}`. Replace `` with the desired version and then run the following command to install: diff --git a/content/manuals/engine/install/ubuntu.md b/content/manuals/engine/install/ubuntu.md index 2e290a43b5b..ae89082b26d 100644 --- a/content/manuals/engine/install/ubuntu.md +++ b/content/manuals/engine/install/ubuntu.md @@ -158,15 +158,15 @@ Docker from the repository. # List the available versions: $ apt-cache madison docker-ce | awk '{ print $3 }' - 5:27.4.0-1~ubuntu.24.04~noble - 5:27.3.1-1~ubuntu.24.04~noble + 5:{{% param "docker_ce_version" %}}-1~ubuntu.24.04~noble + 5:{{% param "docker_ce_version_prev" %}}-1~ubuntu.24.04~noble ... ``` Select the desired version and install: ```console - $ VERSION_STRING=5:27.4.0-1~ubuntu.24.04~noble + $ VERSION_STRING=5:{{% param "docker_ce_version" %}}-1~ubuntu.24.04~noble $ sudo apt-get install docker-ce=$VERSION_STRING docker-ce-cli=$VERSION_STRING containerd.io docker-buildx-plugin docker-compose-plugin ``` diff --git a/content/manuals/engine/release-notes/27.md b/content/manuals/engine/release-notes/27.md index 5630c551eb1..7e2fe362696 100644 --- a/content/manuals/engine/release-notes/27.md +++ b/content/manuals/engine/release-notes/27.md @@ -27,6 +27,28 @@ For more information about: Release notes for Docker Engine version 27.4 releases. +### 27.4.1 + +{{< release-date date="2024-12-18" >}} + +For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones: + +- [docker/cli, 27.4.1 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A27.4.1) +- [moby/moby, 27.4.1 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A27.4.1) + +#### Bug fixes and enhancements + +- Fix excessive memory allocations when OTel is not configured. [moby/moby#49079](https://github.com/moby/moby/pull/49079) +- The `docker info` command and the corresponding `GET /info` API endpoint no longer include warnings when `bridge-nf-call-iptables` or `bridge-nf-call-ip6tables` are disabled at the daemon is started. The `br_netfilter` kernel module is now attempted to be loaded when needed, which made those warnings inaccurate. [moby/moby#49090](https://github.com/moby/moby/pull/49090) +- Attempt to load kernel modules, including `ip6_tables` and `br_netfilter` when required, using a method that is likely to succeed inside a Docker-in-Docker container. [moby/moby#49043](https://github.com/moby/moby/pull/49043) +- Fix a bug that could result in an iptables `DOCKER FILTER` chain not being cleaned up on failure. [moby/moby#49110](https://github.com/moby/moby/pull/49110) + +#### Packaging updates + +- Update Compose to [v2.32.1](https://github.com/docker/compose/releases/tag/v2.32.1). [docker/docker-ce-packaging#1130](https://github.com/docker/docker-ce-packaging/pull/1130) +- Update Buildx to [v0.19.3](https://github.com/docker/buildx/releases/tag/v0.19.3). [docker/docker-ce-packaging#1132](https://github.com/docker/docker-ce-packaging/pull/1132) +- Update runc (static binaries only) to [v1.2.3](https://github.com/opencontainers/runc/releases/tag/v1.2.3) [moby/moby#49085](https://github.com/moby/moby/pull/49085) + ### 27.4.0 {{< release-date date="2024-12-09" >}} diff --git a/content/manuals/engine/security/rootless.md b/content/manuals/engine/security/rootless.md index 4b78bdf34e6..6f42a9296b8 100644 --- a/content/manuals/engine/security/rootless.md +++ b/content/manuals/engine/security/rootless.md @@ -98,9 +98,6 @@ testuser:231072:65536 {{< tab name="Debian GNU/Linux" >}} - Install `dbus-user-session` package if not installed. Run `sudo apt-get install -y dbus-user-session` and relogin. -- For Debian 10, add `kernel.unprivileged_userns_clone=1` to `/etc/sysctl.conf` (or - `/etc/sysctl.d`) and run `sudo sysctl --system`. This step is not required on Debian 11. - - For Debian 11, installing `fuse-overlayfs` is recommended. Run `sudo apt-get install -y fuse-overlayfs`. This step is not required on Debian 12. diff --git a/content/manuals/engine/security/seccomp.md b/content/manuals/engine/security/seccomp.md index 1ea65a0b9d0..094bdbffe0a 100644 --- a/content/manuals/engine/security/seccomp.md +++ b/content/manuals/engine/security/seccomp.md @@ -26,13 +26,13 @@ protective while providing wide application compatibility. The default Docker profile can be found [here](https://github.com/moby/moby/blob/master/profiles/seccomp/default.json). -In effect, the profile is an allowlist which denies access to system calls by -default, then allowlists specific system calls. The profile works by defining a +In effect, the profile is an allowlist that denies access to system calls by +default and then allows specific system calls. The profile works by defining a `defaultAction` of `SCMP_ACT_ERRNO` and overriding that action only for specific system calls. The effect of `SCMP_ACT_ERRNO` is to cause a `Permission Denied` error. Next, the profile defines a specific list of system calls which are fully allowed, because their `action` is overridden to be `SCMP_ACT_ALLOW`. Finally, -some specific rules are for individual system calls such as `personality`, and others, +some specific rules are for individual system calls such as `personality`, and others, to allow variants of those system calls with specific arguments. `seccomp` is instrumental for running Docker containers with least privilege. It @@ -53,61 +53,61 @@ $ docker run --rm \ Docker's default seccomp profile is an allowlist which specifies the calls that are allowed. The table below lists the significant (but not all) syscalls that -are effectively blocked because they are not on the Allowlist. The table includes +are effectively blocked because they are not on the allowlist. The table includes the reason each syscall is blocked rather than white-listed. -| Syscall | Description | -|---------------------|---------------------------------------------------------------------------------------------------------------------------------------| -| `acct` | Accounting syscall which could let containers disable their own resource limits or process accounting. Also gated by `CAP_SYS_PACCT`. | -| `add_key` | Prevent containers from using the kernel keyring, which is not namespaced. | -| `bpf` | Deny loading potentially persistent bpf programs into kernel, already gated by `CAP_SYS_ADMIN`. | -| `clock_adjtime` | Time/date is not namespaced. Also gated by `CAP_SYS_TIME`. | -| `clock_settime` | Time/date is not namespaced. Also gated by `CAP_SYS_TIME`. | -| `clone` | Deny cloning new namespaces. Also gated by `CAP_SYS_ADMIN` for CLONE_* flags, except `CLONE_NEWUSER`. | -| `create_module` | Deny manipulation and functions on kernel modules. Obsolete. Also gated by `CAP_SYS_MODULE`. | -| `delete_module` | Deny manipulation and functions on kernel modules. Also gated by `CAP_SYS_MODULE`. | -| `finit_module` | Deny manipulation and functions on kernel modules. Also gated by `CAP_SYS_MODULE`. | -| `get_kernel_syms` | Deny retrieval of exported kernel and module symbols. Obsolete. | -| `get_mempolicy` | Syscall that modifies kernel memory and NUMA settings. Already gated by `CAP_SYS_NICE`. | -| `init_module` | Deny manipulation and functions on kernel modules. Also gated by `CAP_SYS_MODULE`. | -| `ioperm` | Prevent containers from modifying kernel I/O privilege levels. Already gated by `CAP_SYS_RAWIO`. | -| `iopl` | Prevent containers from modifying kernel I/O privilege levels. Already gated by `CAP_SYS_RAWIO`. | -| `kcmp` | Restrict process inspection capabilities, already blocked by dropping `CAP_SYS_PTRACE`. | -| `kexec_file_load` | Sister syscall of `kexec_load` that does the same thing, slightly different arguments. Also gated by `CAP_SYS_BOOT`. | -| `kexec_load` | Deny loading a new kernel for later execution. Also gated by `CAP_SYS_BOOT`. | -| `keyctl` | Prevent containers from using the kernel keyring, which is not namespaced. | -| `lookup_dcookie` | Tracing/profiling syscall, which could leak a lot of information on the host. Also gated by `CAP_SYS_ADMIN`. | -| `mbind` | Syscall that modifies kernel memory and NUMA settings. Already gated by `CAP_SYS_NICE`. | -| `mount` | Deny mounting, already gated by `CAP_SYS_ADMIN`. | -| `move_pages` | Syscall that modifies kernel memory and NUMA settings. | -| `nfsservctl` | Deny interaction with the kernel nfs daemon. Obsolete since Linux 3.1. | -| `open_by_handle_at` | Cause of an old container breakout. Also gated by `CAP_DAC_READ_SEARCH`. | -| `perf_event_open` | Tracing/profiling syscall, which could leak a lot of information on the host. | -| `personality` | Prevent container from enabling BSD emulation. Not inherently dangerous, but poorly tested, potential for a lot of kernel vulns. | -| `pivot_root` | Deny `pivot_root`, should be privileged operation. | -| `process_vm_readv` | Restrict process inspection capabilities, already blocked by dropping `CAP_SYS_PTRACE`. | -| `process_vm_writev` | Restrict process inspection capabilities, already blocked by dropping `CAP_SYS_PTRACE`. | +| Syscall | Description | +| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `acct` | Accounting syscall which could let containers disable their own resource limits or process accounting. Also gated by `CAP_SYS_PACCT`. | +| `add_key` | Prevent containers from using the kernel keyring, which is not namespaced. | +| `bpf` | Deny loading potentially persistent BPF programs into kernel, already gated by `CAP_SYS_ADMIN`. | +| `clock_adjtime` | Time/date is not namespaced. Also gated by `CAP_SYS_TIME`. | +| `clock_settime` | Time/date is not namespaced. Also gated by `CAP_SYS_TIME`. | +| `clone` | Deny cloning new namespaces. Also gated by `CAP_SYS_ADMIN` for CLONE\_\* flags, except `CLONE_NEWUSER`. | +| `create_module` | Deny manipulation and functions on kernel modules. Obsolete. Also gated by `CAP_SYS_MODULE`. | +| `delete_module` | Deny manipulation and functions on kernel modules. Also gated by `CAP_SYS_MODULE`. | +| `finit_module` | Deny manipulation and functions on kernel modules. Also gated by `CAP_SYS_MODULE`. | +| `get_kernel_syms` | Deny retrieval of exported kernel and module symbols. Obsolete. | +| `get_mempolicy` | Syscall that modifies kernel memory and NUMA settings. Already gated by `CAP_SYS_NICE`. | +| `init_module` | Deny manipulation and functions on kernel modules. Also gated by `CAP_SYS_MODULE`. | +| `ioperm` | Prevent containers from modifying kernel I/O privilege levels. Already gated by `CAP_SYS_RAWIO`. | +| `iopl` | Prevent containers from modifying kernel I/O privilege levels. Already gated by `CAP_SYS_RAWIO`. | +| `kcmp` | Restrict process inspection capabilities, already blocked by dropping `CAP_SYS_PTRACE`. | +| `kexec_file_load` | Sister syscall of `kexec_load` that does the same thing, slightly different arguments. Also gated by `CAP_SYS_BOOT`. | +| `kexec_load` | Deny loading a new kernel for later execution. Also gated by `CAP_SYS_BOOT`. | +| `keyctl` | Prevent containers from using the kernel keyring, which is not namespaced. | +| `lookup_dcookie` | Tracing/profiling syscall, which could leak a lot of information on the host. Also gated by `CAP_SYS_ADMIN`. | +| `mbind` | Syscall that modifies kernel memory and NUMA settings. Already gated by `CAP_SYS_NICE`. | +| `mount` | Deny mounting, already gated by `CAP_SYS_ADMIN`. | +| `move_pages` | Syscall that modifies kernel memory and NUMA settings. | +| `nfsservctl` | Deny interaction with the kernel NFS daemon. Obsolete since Linux 3.1. | +| `open_by_handle_at` | Cause of an old container breakout. Also gated by `CAP_DAC_READ_SEARCH`. | +| `perf_event_open` | Tracing/profiling syscall, which could leak a lot of information on the host. | +| `personality` | Prevent container from enabling BSD emulation. Not inherently dangerous, but poorly tested, potential for a lot of kernel vulnerabilities. | +| `pivot_root` | Deny `pivot_root`, should be privileged operation. | +| `process_vm_readv` | Restrict process inspection capabilities, already blocked by dropping `CAP_SYS_PTRACE`. | +| `process_vm_writev` | Restrict process inspection capabilities, already blocked by dropping `CAP_SYS_PTRACE`. | | `ptrace` | Tracing/profiling syscall. Blocked in Linux kernel versions before 4.8 to avoid seccomp bypass. Tracing/profiling arbitrary processes is already blocked by dropping `CAP_SYS_PTRACE`, because it could leak a lot of information on the host. | -| `query_module` | Deny manipulation and functions on kernel modules. Obsolete. | -| `quotactl` | Quota syscall which could let containers disable their own resource limits or process accounting. Also gated by `CAP_SYS_ADMIN`. | -| `reboot` | Don't let containers reboot the host. Also gated by `CAP_SYS_BOOT`. | -| `request_key` | Prevent containers from using the kernel keyring, which is not namespaced. | -| `set_mempolicy` | Syscall that modifies kernel memory and NUMA settings. Already gated by `CAP_SYS_NICE`. | -| `setns` | Deny associating a thread with a namespace. Also gated by `CAP_SYS_ADMIN`. | -| `settimeofday` | Time/date is not namespaced. Also gated by `CAP_SYS_TIME`. | -| `stime` | Time/date is not namespaced. Also gated by `CAP_SYS_TIME`. | -| `swapon` | Deny start/stop swapping to file/device. Also gated by `CAP_SYS_ADMIN`. | -| `swapoff` | Deny start/stop swapping to file/device. Also gated by `CAP_SYS_ADMIN`. | -| `sysfs` | Obsolete syscall. | -| `_sysctl` | Obsolete, replaced by /proc/sys. | -| `umount` | Should be a privileged operation. Also gated by `CAP_SYS_ADMIN`. | -| `umount2` | Should be a privileged operation. Also gated by `CAP_SYS_ADMIN`. | -| `unshare` | Deny cloning new namespaces for processes. Also gated by `CAP_SYS_ADMIN`, with the exception of `unshare --user`. | -| `uselib` | Older syscall related to shared libraries, unused for a long time. | -| `userfaultfd` | Userspace page fault handling, largely needed for process migration. | -| `ustat` | Obsolete syscall. | -| `vm86` | In kernel x86 real mode virtual machine. Also gated by `CAP_SYS_ADMIN`. | -| `vm86old` | In kernel x86 real mode virtual machine. Also gated by `CAP_SYS_ADMIN`. | +| `query_module` | Deny manipulation and functions on kernel modules. Obsolete. | +| `quotactl` | Quota syscall which could let containers disable their own resource limits or process accounting. Also gated by `CAP_SYS_ADMIN`. | +| `reboot` | Don't let containers reboot the host. Also gated by `CAP_SYS_BOOT`. | +| `request_key` | Prevent containers from using the kernel keyring, which is not namespaced. | +| `set_mempolicy` | Syscall that modifies kernel memory and NUMA settings. Already gated by `CAP_SYS_NICE`. | +| `setns` | Deny associating a thread with a namespace. Also gated by `CAP_SYS_ADMIN`. | +| `settimeofday` | Time/date is not namespaced. Also gated by `CAP_SYS_TIME`. | +| `stime` | Time/date is not namespaced. Also gated by `CAP_SYS_TIME`. | +| `swapon` | Deny start/stop swapping to file/device. Also gated by `CAP_SYS_ADMIN`. | +| `swapoff` | Deny start/stop swapping to file/device. Also gated by `CAP_SYS_ADMIN`. | +| `sysfs` | Obsolete syscall. | +| `_sysctl` | Obsolete, replaced by /proc/sys. | +| `umount` | Should be a privileged operation. Also gated by `CAP_SYS_ADMIN`. | +| `umount2` | Should be a privileged operation. Also gated by `CAP_SYS_ADMIN`. | +| `unshare` | Deny cloning new namespaces for processes. Also gated by `CAP_SYS_ADMIN`, with the exception of `unshare --user`. | +| `uselib` | Older syscall related to shared libraries, unused for a long time. | +| `userfaultfd` | Userspace page fault handling, largely needed for process migration. | +| `ustat` | Obsolete syscall. | +| `vm86` | In kernel x86 real mode virtual machine. Also gated by `CAP_SYS_ADMIN`. | +| `vm86old` | In kernel x86 real mode virtual machine. Also gated by `CAP_SYS_ADMIN`. | ## Run without the default seccomp profile @@ -115,6 +115,6 @@ You can pass `unconfined` to run a container without the default seccomp profile. ```console -$ docker run --rm -it --security-opt seccomp=unconfined debian:jessie \ +$ docker run --rm -it --security-opt seccomp=unconfined debian:latest \ unshare --map-root-user --user sh -c whoami ``` diff --git a/content/manuals/engine/storage/drivers/_index.md b/content/manuals/engine/storage/drivers/_index.md index 07ad123cfab..57bf355e7b8 100644 --- a/content/manuals/engine/storage/drivers/_index.md +++ b/content/manuals/engine/storage/drivers/_index.md @@ -48,7 +48,7 @@ CMD python /app/app.py ``` This Dockerfile contains four commands. Commands that modify the filesystem create -a layer. The `FROM` statement starts out by creating a layer from the `ubuntu:22.04` +a new layer. The `FROM` statement starts out by creating a layer from the `ubuntu:22.04` image. The `LABEL` command only modifies the image's metadata, and doesn't produce a new layer. The `COPY` command adds some files from your Docker client's current directory. The first `RUN` command builds your application using the `make` command, diff --git a/content/manuals/engine/storage/drivers/select-storage-driver.md b/content/manuals/engine/storage/drivers/select-storage-driver.md index a4118a301b5..fe441ce5fc8 100644 --- a/content/manuals/engine/storage/drivers/select-storage-driver.md +++ b/content/manuals/engine/storage/drivers/select-storage-driver.md @@ -19,6 +19,12 @@ Docker host. After you have read the [storage driver overview](./_index.md), the next step is to choose the best storage driver for your workloads. Use the storage driver with the best overall performance and stability in the most usual scenarios. +> [!NOTE] +> This page discusses storage drivers for Docker Engine on Linux. If you're +> running the Docker daemon with Windows as the host OS, the only supported +> storage driver is windowsfilter. For more information, see +> [windowsfilter](windowsfilter-driver.md). + The Docker Engine provides the following storage drivers on Linux: | Driver | Description | @@ -189,7 +195,8 @@ to physical or logical disks on the Docker host. ## Related information -- [About images, containers, and storage drivers](./_index.md) -- [`overlay2` storage driver in practice](overlayfs-driver.md) -- [`btrfs` storage driver in practice](btrfs-driver.md) -- [`zfs` storage driver in practice](zfs-driver.md) +- [Storage drivers](./_index.md) +- [`overlay2` storage driver](overlayfs-driver.md) +- [`btrfs` storage driver](btrfs-driver.md) +- [`zfs` storage driver](zfs-driver.md) +- [`windowsfilter` storage driver](windowsfilter-driver.md) diff --git a/content/manuals/engine/storage/drivers/windowsfilter-driver.md b/content/manuals/engine/storage/drivers/windowsfilter-driver.md new file mode 100644 index 00000000000..a38f6d865d5 --- /dev/null +++ b/content/manuals/engine/storage/drivers/windowsfilter-driver.md @@ -0,0 +1,36 @@ +--- +description: Learn about the windowsfilter storage driver +keywords: container, storage, driver, windows, windowsfilter +title: windowsfilter storage driver +--- + +The windowsfilter storage driver is the default storage driver for Docker +Engine on Windows. The windowsfilter driver uses Windows-native file system +layers to for storing Docker layers and volume data on disk. The windowsfilter +storage driver only works on file systems formatted with NTFS. + +## Configure the windowsfilter storage driver + +For most use case, no configuring the windowsfilter storage driver is not +necessary. + +The default storage limit for Docker Engine on Windows is 127GB. To use a +different storage size, set the `size` option for the windowsfilter storage +driver. See [windowsfilter options](/reference/cli/dockerd.md#windowsfilter-options). + +Data is stored on the Docker host in `image` and `windowsfilter` subdirectories +within `C:\ProgramData\docker` by default. You can change the storage location +by configuring the `data-root` option in the [Daemon configuration file](/reference/cli/dockerd.md#on-windows): + +```json +{ + "data-root": "d:\\docker" +} +``` + +You must restart the daemon for the configuration change to take effect. + +## Additional information + +For more information about how container storage works on Windows, refer to +Microsoft's [Containers on Windows documentation](https://learn.microsoft.com/en-us/virtualization/windowscontainers/manage-containers/container-storage). diff --git a/content/manuals/engine/storage/tmpfs.md b/content/manuals/engine/storage/tmpfs.md index 299103c080f..b4e186acb3d 100644 --- a/content/manuals/engine/storage/tmpfs.md +++ b/content/manuals/engine/storage/tmpfs.md @@ -60,10 +60,67 @@ $ docker run --tmpfs ``` In general, `--mount` is preferred. The main difference is that the `--mount` -flag is more explicit and supports all the available options. +flag is more explicit. On the other hand, `--tmpfs` is less verbose and gives +you more flexibility as it lets you set more mount options. The `--tmpfs` flag cannot be used with swarm services. You must use `--mount`. +### Options for --tmpfs + +The `--tmpfs` flag consists of two fields, separated by a colon character +(`:`). + +```console +$ docker run --tmpfs [:opts] +``` + +The first field is the container path to mount into a tmpfs. The second field +is optional and lets you set mount options. Valid mount options for `--tmpfs` +include: + +| Option | Description | +| ------------ | ------------------------------------------------------------------------------------------- | +| `ro` | Creates a read-only tmpfs mount. | +| `rw` | Creates a read-write tmpfs mount (default behavior). | +| `nosuid` | Prevents `setuid` and `setgid` bits from being honored during execution. | +| `suid` | Allows `setuid` and `setgid` bits to be honored during execution (default behavior). | +| `nodev` | Device files can be created but are not functional (access results in an error). | +| `dev` | Device files can be created and are fully functional. | +| `exec` | Allows the execution of executable binaries in the mounted file system. | +| `noexec` | Does not allow the execution of executable binaries in the mounted file system. | +| `sync` | All I/O to the file system is done synchronously. | +| `async` | All I/O to the file system is done asynchronously (default behavior). | +| `dirsync` | Directory updates within the file system are done synchronously. | +| `atime` | Updates file access time each time the file is accessed. | +| `noatime` | Does not update file access times when the file is accessed. | +| `diratime` | Updates directory access times each time the directory is accessed. | +| `nodiratime` | Does not update directory access times when the directory is accessed. | +| `size` | Specifies the size of the tmpfs mount, for example, `size=64m`. | +| `mode` | Specifies the file mode (permissions) for the tmpfs mount (for example, `mode=1777`). | +| `uid` | Specifies the user ID for the owner of the tmpfs mount (for example, `uid=1000`). | +| `gid` | Specifies the group ID for the owner of the tmpfs mount (for example, `gid=1000`). | +| `nr_inodes` | Specifies the maximum number of inodes for the tmpfs mount (for example, `nr_inodes=400k`). | +| `nr_blocks` | Specifies the maximum number of blocks for the tmpfs mount (for example, `nr_blocks=1024`). | + +```console {title="Example"} +$ docker run --tmpfs /data:noexec,size=1024,mode=1777 +``` + +Not all tmpfs mount features available in the Linux mount command are supported +with the `--tmpfs` flag. If you require advanced tmpfs options or features, you +may need to use a privileged container or configure the mount outside of +Docker. + +> [!CAUTION] +> Running containers with `--privileged` grants elevated permissions and can +> expose the host system to security risks. Use this option only when +> absolutely necessary and in trusted environments. + +```console +$ docker run --privileged -it debian sh +/# mount -t tmpfs -o tmpfs /data +``` + ### Options for --mount The `--mount` flag consists of multiple key-value pairs, separated by commas @@ -86,10 +143,6 @@ Valid options for `--mount type=tmpfs` include: $ docker run --mount type=tmpfs,dst=/app,tmpfs-size=21474836480,tmpfs-mode=1770 ``` -### Options for --tmpfs - -The `--tmpfs` flag does not let you specify any options. - ## Use a tmpfs mount in a container To use a `tmpfs` mount in a container, use the `--tmpfs` flag, or use the @@ -109,6 +162,14 @@ $ docker run -d \ nginx:latest ``` +Verify that the mount is a `tmpfs` mount by looking in the `Mounts` section of +the `docker inspect` output: + +```console +$ docker inspect tmptest --format '{{ json .Mounts }}' +[{"Type":"tmpfs","Source":"","Destination":"/app","Mode":"","RW":true,"Propagation":""}] +``` + {{< /tab >}} {{< tab name="`--tmpfs`" >}} @@ -120,17 +181,17 @@ $ docker run -d \ nginx:latest ``` -{{< /tab >}} -{{< /tabs >}} - Verify that the mount is a `tmpfs` mount by looking in the `Mounts` section of the `docker inspect` output: ```console $ docker inspect tmptest --format '{{ json .Mounts }}' -[{"Type":"tmpfs","Source":"","Destination":"/app","Mode":"","RW":true,"Propagation":""}] +{"/app":""} ``` +{{< /tab >}} +{{< /tabs >}} + Stop and remove the container: ```console diff --git a/content/manuals/harmonia/_index.md b/content/manuals/harmonia/_index.md index ba987542bc8..b3a6b88d5f4 100644 --- a/content/manuals/harmonia/_index.md +++ b/content/manuals/harmonia/_index.md @@ -263,7 +263,9 @@ Run `docker harmonia doctor` to print helpful troubleshooting information. - KinD does not run on Project Harmonia due to some hard-coded assumptions to ensure it's running in a privileged container. K3d is a good alternative. - Containers cannot access host through DNS `host.docker.internal`. - File binds (non-directory binds) are currently static, meaning changes will not be reflected until the container is restarted. This also affects Compose configs and secrets directives. -- Bind mounts, such as `-v /localpath:/incontainer` in the `docker run` command, are not supported without using a file-sync. +- Bind _mounts_, such as `-v /localpath:/incontainer` in the `docker run` command, require creating a file-sync. +- Creating a [synchronized file share](/manuals/desktop/features/synchronized-file-sharing.md) for a directory with a large amount of may take extra time to sync and become ready for use in a container. +- Bind _volumes_, such as those created with `docker volume create --driver local --opt type=none --opt o=bind --opt device=/some/host/path myvolname` or via the compose equivalent, are not supported. - Port-forwarding for UDP is not supported. - Docker Compose projects relying on `watch` in `sync` mode are not working with the `tar` synchronizer. Configure it to use `docker cp` instead, disable tar sync by setting `COMPOSE_EXPERIMENTAL_WATCH_TAR=0` in your environment. - Some Docker Engine features that let you access the underlying host, such as `--pid=host`, `--network=host`, and `--ipc=host`, are currently disabled. diff --git a/content/manuals/scout/install.md b/content/manuals/scout/install.md index eeb546ad4e5..078f5db791a 100644 --- a/content/manuals/scout/install.md +++ b/content/manuals/scout/install.md @@ -46,11 +46,16 @@ $ sh install-scout.sh ```json { "cliPluginsExtraDirs": [ - "$HOME/.docker/scout" + "/home//.docker/scout" ] } ``` + Substitute `` with your username on the system. + + > [!NOTE] + > The path for `cliPluginsExtraDirs` must be an absolute path. + {{< /tab >}} {{< tab name="macOS" >}} @@ -65,13 +70,13 @@ $ sh install-scout.sh 4. Make the binary executable: ```console - $ chmod +x $HOME/.docker/scout/docker-scout` + $ chmod +x $HOME/.docker/scout/docker-scout ``` 5. Authorize the binary to be executable on macOS: ```console - xattr -d com.apple.quarantine $HOME/.docker/scout/docker-scout`. + xattr -d com.apple.quarantine $HOME/.docker/scout/docker-scout. ``` 6. Add the `scout` subdirectory to your `.docker/config.json` as a plugin directory: @@ -79,11 +84,16 @@ $ sh install-scout.sh ```json { "cliPluginsExtraDirs": [ - "$HOME/.docker/scout" + "/Users//.docker/scout" ] } ``` + Substitute `` with your username on the system. + + > [!NOTE] + > The path for `cliPluginsExtraDirs` must be an absolute path. + {{< /tab >}} {{< tab name="Windows" >}} @@ -100,11 +110,16 @@ $ sh install-scout.sh ```json { "cliPluginsExtraDirs": [ - "C:\Users\MobyWhale\.docker\scout" + "C:\Users\\.docker\scout" ] } ``` + Substitute `` with your username on the system. + + > [!NOTE] + > The path for `cliPluginsExtraDirs` must be an absolute path. + {{< /tab >}} {{< /tabs >}} diff --git a/content/manuals/security/for-admins/access-tokens.md b/content/manuals/security/for-admins/access-tokens.md index f19bcedb9d9..afdc5eef8ec 100644 --- a/content/manuals/security/for-admins/access-tokens.md +++ b/content/manuals/security/for-admins/access-tokens.md @@ -12,13 +12,15 @@ The organization access tokens feature is currently in [Beta](../../release-life > [!WARNING] > -> Organization access tokens aren't currently compatible with the following services: +> Organization access tokens (OATs) are not intended to be used with Docker Desktop, and are incompatible. +> +> OATs are also currently incompatible with the following services: > > - Docker Build Cloud > - Docker Scout > - Docker REST APIs > -> If you use these services, you must use personal access tokens instead. +> If you use Docker Desktop or one of these services, you must use personal access tokens instead. An organization access token (OAT) is like a [personal access token (PAT)](/security/for-developers/access-tokens/), but an OAT is associated with diff --git a/content/manuals/security/for-admins/hardened-desktop/settings-management/_index.md b/content/manuals/security/for-admins/hardened-desktop/settings-management/_index.md index 2d5b2051474..cb08fa970c9 100644 --- a/content/manuals/security/for-admins/hardened-desktop/settings-management/_index.md +++ b/content/manuals/security/for-admins/hardened-desktop/settings-management/_index.md @@ -46,6 +46,7 @@ Using the `admin-settings.json` file, you can: - Turn off Docker Extensions - Turn off Docker Scout SBOM indexing - Turn off beta and experimental features +- Turn off Docker AI ([Ask Gordon](../../../../desktop/features/gordon.md)) - Turn off Docker Desktop's onboarding survey - Control whether developers can use the Docker terminal - Control the file sharing implementation for your developers on macOS @@ -79,4 +80,4 @@ In addition, if Enhanced Container Isolation is enforced, developers can't use p ## What's next? - [Configure Settings Management with a `.json` file](configure-json-file.md) -- [Configure Settings Management with the Docker Admin Console](configure-admin-console.md) \ No newline at end of file +- [Configure Settings Management with the Docker Admin Console](configure-admin-console.md) diff --git a/content/manuals/security/for-admins/hardened-desktop/settings-management/configure-json-file.md b/content/manuals/security/for-admins/hardened-desktop/settings-management/configure-json-file.md index d52ff4315e7..b59e1293881 100644 --- a/content/manuals/security/for-admins/hardened-desktop/settings-management/configure-json-file.md +++ b/content/manuals/security/for-admins/hardened-desktop/settings-management/configure-json-file.md @@ -258,6 +258,7 @@ The following `admin-settings.json` code and table provides an example of the re |:-------------------------------|---|:-------------------------------|---| | `allowExperimentalFeatures`| | If `value` is set to `false`, experimental features are disabled.| | | `allowBetaFeatures`| | If `value` is set to `false`, beta features are disabled.| | +| `enableDockerAI` | | If `value` is set to `false`, Docker AI (Ask Gordon) features are disabled. | | ### Enhanced Container Isolation diff --git a/content/manuals/security/for-admins/provisioning/just-in-time.md b/content/manuals/security/for-admins/provisioning/just-in-time.md index d412f8b6b7e..dc006697753 100644 --- a/content/manuals/security/for-admins/provisioning/just-in-time.md +++ b/content/manuals/security/for-admins/provisioning/just-in-time.md @@ -63,7 +63,7 @@ You may want to disable JIT provisioning for reasons such as the following: Users are provisioned with JIT by default. If you enable SCIM, you can disable JIT: -1. Sign in to the [Admin Console](https://app.docker.com/). -2. Select your organization or company in the left-hand navigation drop-down, and then select **SSO and SCIM**. +1. In the [Admin Console](https://app.docker.com/admin), select your organization. +2. Select **SSO and SCIM**. 3. In the SSO connections table, select the **Action** icon and then **Disable JIT provisioning**. 4. Select **Disable** to confirm. diff --git a/content/manuals/security/for-admins/single-sign-on/configure.md b/content/manuals/security/for-admins/single-sign-on/configure.md index a5bda5c29b5..ee2905fbc06 100644 --- a/content/manuals/security/for-admins/single-sign-on/configure.md +++ b/content/manuals/security/for-admins/single-sign-on/configure.md @@ -22,7 +22,7 @@ Get started creating a single sign-on (SSO) connection for your organization or {{< include "admin-early-access.md" >}} 1. Sign in to the [Admin Console](https://admin.docker.com/). -2. Select your organization or company from the left-hand drop-down menu. Note that when an organization is part of a company, you must select the company and configure the domain for the organization at the company level. +2. Select your organization or company from the **Choose profile** page. Note that when an organization is part of a company, you must select the company and configure the domain for the organization at the company level. 3. Under **Security and access**, select **Domain management**. 4. Select **Add a domain**. 5. Enter your domain in the text box and select **Add domain**. diff --git a/content/manuals/security/for-admins/single-sign-on/connect.md b/content/manuals/security/for-admins/single-sign-on/connect.md index 1c95c487975..0a698b9653a 100644 --- a/content/manuals/security/for-admins/single-sign-on/connect.md +++ b/content/manuals/security/for-admins/single-sign-on/connect.md @@ -31,7 +31,7 @@ Make sure you have completed the following before you begin: {{< include "admin-early-access.md" >}} 1. Sign in to the [Admin Console](https://admin.docker.com/). -2. Select your organization or company from the left-hand drop-down menu. Note that when an organization is part of a company, you must select the company and configure the domain for the organization at the company level. +2. Select your organization or company from the **Choose profile** page. Note that when an organization is part of a company, you must select the company and configure the domain for the organization at the company level. 3. Under Security and access, select **SSO and SCIM**. 4. Select **Create Connection** and provide a name for the connection. 5. Select an authentication method, **SAML** or **Azure AD (OIDC)**. @@ -201,7 +201,7 @@ You can also test your SSO connection through the command-line interface (CLI). Enforcing SSO requires users to use SSO when signing into Docker. This centralizes authentication and enforces policies set by the IdP. 1. Sign in to the [Admin Console](https://admin.docker.com/). -2. Select your organization or company from the left-hand drop-down menu. Note that when an organization is part of a company, you must select the company and configure the domain for the organization at the company level. +2. Select your organization or company from the **Choose profile** page. Note that when an organization is part of a company, you must select the company and configure the domain for the organization at the company level. 3. Under Security and access, select **SSO and SCIM**. 4. In the SSO connections table, select the **Action** icon and then **Enable enforcement**. When SSO is enforced, your users are unable to modify their email address and password, convert a user account to an organization, or set up 2FA through Docker Hub. If you want to use 2FA, you must enable 2FA through your IdP. 5. Continue with the on-screen instructions and verify you've completed all tasks. diff --git a/content/manuals/security/for-admins/single-sign-on/manage.md b/content/manuals/security/for-admins/single-sign-on/manage.md index 26455b24794..70b4af79abe 100644 --- a/content/manuals/security/for-admins/single-sign-on/manage.md +++ b/content/manuals/security/for-admins/single-sign-on/manage.md @@ -71,7 +71,7 @@ aliases: To add a guest that isn't verified through your IdP: 1. Sign in to the [Admin Console](https://app.docker.com/admin). -2. Select **Organizations**, your organization, and then **Members**. +2. Select your organization or company from the **Choose profile** page, then select **Members**. 3. Select **Invite**. 4. Follow the on-screen instructions to invite the user. @@ -80,7 +80,7 @@ To add a guest that isn't verified through your IdP: To remove a user: 1. Sign in to [Admin Console](https://app.docker.com/admin). -2. Select **Organizations**, your organization, and then **Members**. +2. Select your organization or company from the **Choose profile** page, then select **Members**. 3. Select the action icon next to a user’s name, and then select **Remove member**, if you're an organization, or **Remove user**, if you're a company. 4. Follow the on-screen instructions to remove the user. diff --git a/content/manuals/security/for-admins/single-sign-on/troubleshoot.md b/content/manuals/security/for-admins/single-sign-on/troubleshoot.md index 651bf9d8e37..e5585e36a8a 100644 --- a/content/manuals/security/for-admins/single-sign-on/troubleshoot.md +++ b/content/manuals/security/for-admins/single-sign-on/troubleshoot.md @@ -16,8 +16,7 @@ their service. ## View SSO and SCIM error logs 1. Sign in to the [Admin Console](https://app.docker.com/admin/). -2. Select your organization or company in the left navigation drop-down menu, - and then select **SSO and SCIM**. +2. Select your organization or company from the **Choose profile** page, and then select **SSO and SCIM**. > [!NOTE] > diff --git a/content/manuals/security/security-announcements.md b/content/manuals/security/security-announcements.md index 9c1cbddd060..bc1bb163d82 100644 --- a/content/manuals/security/security-announcements.md +++ b/content/manuals/security/security-announcements.md @@ -59,7 +59,7 @@ If you are using affected versions of runc, BuildKit, Moby, or Docker Desktop, m If you are unable to update to an unaffected version promptly, follow these best practices to mitigate risk: -* Only use trusted Docker images (such as [Docker Official Images](../trusted-content/official-images/_index.md)). +* Only use trusted Docker images (such as [Docker Official Images](../docker-hub/image-library/trusted-content.md#docker-official-images)). * Don’t build Docker images from untrusted sources or untrusted Dockerfiles. * If you are a Docker Business customer using Docker Desktop and unable to update to v4.27.1, make sure to enable [Hardened Docker Desktop](/manuals/security/for-admins/hardened-desktop/_index.md) features such as: * [Enhanced Container Isolation](/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/_index.md), which mitigates the impact of CVE-2024-21626 in the case of running containers from malicious images. @@ -149,7 +149,7 @@ the Text4Shell CVE in the vulnerability report. For detailed instructions, see [ ### Docker Official Images impacted by CVE-2022-42889 -A number of [Docker Official Images](../trusted-content/official-images/_index.md) contain the vulnerable versions of +A number of [Docker Official Images](../docker-hub/image-library/trusted-content.md#docker-official-images) contain the vulnerable versions of Apache Commons Text. The following lists Docker Official Images that may contain the vulnerable versions of Apache Commons Text: @@ -201,7 +201,7 @@ Log4j 2 CVE in the vulnerability report. For detailed instructions, see [Scan im _Last updated December 2021_ -A number of [Docker Official Images](../trusted-content/official-images/_index.md) contain the vulnerable versions of +A number of [Docker Official Images](../docker-hub/image-library/trusted-content.md#docker-official-images) contain the vulnerable versions of Log4j 2 CVE-2021-44228. The following table lists Docker Official Images that may contained the vulnerable versions of Log4j 2. We updated Log4j 2 in these images to the latest version. Some of these images may not be vulnerable for other reasons. We recommend that you also review the guidelines published on the upstream websites. diff --git a/content/manuals/subscription/change.md b/content/manuals/subscription/change.md index d593a9cce49..6328ab3f6c6 100644 --- a/content/manuals/subscription/change.md +++ b/content/manuals/subscription/change.md @@ -41,7 +41,7 @@ To upgrade your Docker subscription: 1. Sign in to [Docker Home](https://app.docker.com/). 2. Under Settings and administration, select **Billing**. -3. Optional. If you're upgrading from a free Personal plan to a Team plan and want to keep your username, [convert your user account into an organization](../admin/convert-account.md). +3. Optional. If you're upgrading from a free Personal plan to a Team plan and want to keep your username, [convert your user account into an organization](../admin/organization/convert-account.md). 4. Select the account you want to upgrade in the drop-down at the top-left of the page. 5. Select **Upgrade**. 6. Follow the on-screen instructions to complete your upgrade. diff --git a/content/manuals/subscription/faq.md b/content/manuals/subscription/faq.md index ee89aeeb0b9..b4713d9b632 100644 --- a/content/manuals/subscription/faq.md +++ b/content/manuals/subscription/faq.md @@ -24,7 +24,7 @@ Contact the [Docker Sales Team](https://www.docker.com/company/contact). ### What ways can I contribute to Docker content? Docker offers two programs: -- [Docker-Sponsored Open Source Program (DSOS)](../trusted-content/dsos-program.md) -- [Docker Verified Publisher (DVP)](../trusted-content/dvp-program.md) +- [Docker-Sponsored Open Source Program (DSOS)](../docker-hub/repos/manage/trusted-content/dsos-program.md) +- [Docker Verified Publisher (DVP)](../docker-hub/repos/manage/trusted-content/dvp-program.md) You can also join the [Developer Preview Program](https://www.docker.com/community/get-involved/developer-preview/) or sign up for early access programs for specific products to participate in research and try out new features. diff --git a/content/manuals/trusted-content/_index.md b/content/manuals/trusted-content/_index.md deleted file mode 100644 index 4fa05af4425..00000000000 --- a/content/manuals/trusted-content/_index.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: Trusted content -description: Optimize your development workflow with secure base images from our selection of trusted content -keywords: doi, dvp, dsos, open source, security, base images -params: - sidebar: - group: Platform -grid: -- title: Docker Official Images - description: A curated set of Docker repositories hosted on Docker Hub. - icon: /trusted-content/images/doi-icon.svg - link: /trusted-content/official-images/ -- title: Docker Verified Publisher - description: High-quality images from verified vendors. - icon: /trusted-content/images/dvp-icon.svg - link: /trusted-content/dvp-program/ -- title: Docker-Sponsored Open Source - description: High-quality images from non-commercial open source projects. - icon: /trusted-content/images/dsos-icon.svg - link: /trusted-content/dsos-program/ ---- - -Trusted content is a selection of high-quality, secure images, curated by -Docker and verified publishing partners. These images are stable, up-to-date, -and follow industry best-practices. They provide a strong foundation for -developing applications. - -{{< grid >}} diff --git a/content/manuals/trusted-content/images/doi-icon.svg b/content/manuals/trusted-content/images/doi-icon.svg deleted file mode 100644 index ccba28f803b..00000000000 --- a/content/manuals/trusted-content/images/doi-icon.svg +++ /dev/null @@ -1,2 +0,0 @@ - - \ No newline at end of file diff --git a/content/manuals/trusted-content/images/dsos-icon.svg b/content/manuals/trusted-content/images/dsos-icon.svg deleted file mode 100644 index f62ff75981a..00000000000 --- a/content/manuals/trusted-content/images/dsos-icon.svg +++ /dev/null @@ -1,2 +0,0 @@ - - \ No newline at end of file diff --git a/content/manuals/trusted-content/images/dvp-icon.svg b/content/manuals/trusted-content/images/dvp-icon.svg deleted file mode 100644 index 17acbd49976..00000000000 --- a/content/manuals/trusted-content/images/dvp-icon.svg +++ /dev/null @@ -1,2 +0,0 @@ - - \ No newline at end of file diff --git a/content/manuals/trusted-content/images/insights-and-analytics-tab.png b/content/manuals/trusted-content/images/insights-and-analytics-tab.png deleted file mode 100644 index a1f52fc832e..00000000000 Binary files a/content/manuals/trusted-content/images/insights-and-analytics-tab.png and /dev/null differ diff --git a/content/manuals/trusted-content/official-images/_index.md b/content/manuals/trusted-content/official-images/_index.md deleted file mode 100644 index c9b05edf0d2..00000000000 --- a/content/manuals/trusted-content/official-images/_index.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -description: Get an overview on Docker Official Images, what they are, and how they differ from other images available on Docker Hub -keywords: Docker, docker, registry, accounts, plans, Dockerfile, Docker Hub, docs, - official,image, documentation -title: Docker Official Images -aliases: -- /docker-hub/official_repos/ -- /docker-hub/official_images/ ---- - -The [Docker Official Images](https://hub.docker.com/search?q=&type=image&image_filter=official) -are a curated set of Docker repositories hosted on Docker Hub. - -> [!NOTE] -> -> Use of Docker Official Images is subject to [Docker's Terms of Service](https://www.docker.com/legal/docker-terms-service/). - -These images provide essential base repositories that serve as the starting -point for the majority of users. - -These include operating systems such as -[Ubuntu](https://hub.docker.com/_/ubuntu/) and -[Alpine](https://hub.docker.com/_/alpine/), programming language runtimes such as -[Python](https://hub.docker.com/_/python) and -[Node](https://hub.docker.com/_/node), and other essential tools such as -[memcached](https://hub.docker.com/_/memcached) and -[MySQL](https://hub.docker.com/_/mysql). - -The images are some of the [most secure images](https://www.docker.com/blog/enhancing-security-and-transparency-with-docker-official-images/) -on Docker Hub. This is particularly important as Docker Official Images are -some of the most popular on Docker Hub. Typically, Docker Official images have -few or no packages containing CVEs. - -The images exemplify [`Dockerfile` best practices](/manuals/build/building/best-practices.md) -and provide clear documentation to serve as a reference for other `Dockerfile` authors. - -Images that are part of this program have a special badge on Docker Hub making -it easier for you to identify projects that are part of Docker Official Images. - -![Docker official image badge](../images/official-image-badge-iso.png) - -## In this section - -{{% sectionlinks %}} diff --git a/content/reference/api/engine/_index.md b/content/reference/api/engine/_index.md index b226065c7e9..2511ce1ba3c 100644 --- a/content/reference/api/engine/_index.md +++ b/content/reference/api/engine/_index.md @@ -40,7 +40,7 @@ The Docker Engine API is a RESTful API accessed by an HTTP client such as `wget` ## View the API reference You can -[view the reference for the latest version of the API](latest/index.html) +[view the reference for the latest version of the API](/reference/api/engine/version/v{{% param latest_engine_api_version %}}.md) or [choose a specific version](/reference/api/engine/version-history/). ## Versioned API and SDK diff --git a/content/reference/api/hub/dvp.yaml b/content/reference/api/hub/dvp.yaml index 3b9becb0418..8ff2030acab 100644 --- a/content/reference/api/hub/dvp.yaml +++ b/content/reference/api/hub/dvp.yaml @@ -561,6 +561,8 @@ components: properties: data: type: array + description: | + List of urls to download the data. When the data is large, the data will be split into multiple files. items: $ref: '#/components/schemas/ResponseDataFile' ResponseDataFile: diff --git a/content/reference/api/hub/latest.yaml b/content/reference/api/hub/latest.yaml index 94f3366a544..7d0099ab8a6 100644 --- a/content/reference/api/hub/latest.yaml +++ b/content/reference/api/hub/latest.yaml @@ -6,112 +6,104 @@ info: url: https://docs.docker.com/assets/images/logo-docker-main.png href: /reference description: | - Docker Hub is a service provided by Docker for finding and sharing container - images with your team. + Docker Hub is a service provided by Docker for finding and sharing container images with your team. It is the world's largest library and community for container images. - In addition to the [Docker Hub UI](https://docs.docker.com/docker-hub/) and [Docker Hub CLI tool](https://github.com/docker/hub-tool#readme) (currently experimental), - - Docker provides an API that allows you to interact with Docker Hub. + In addition to the [Docker Hub UI](https://docs.docker.com/docker-hub/) and [Docker Hub CLI tool](https://github.com/docker/hub-tool#readme) (currently experimental), Docker provides an API that allows you to interact with Docker Hub. Browse through the Docker Hub API documentation to explore the supported endpoints. - +servers: + - description: Docker HUB API + x-audience: public + url: https://hub.docker.com tags: - name: resources x-displayName: Resources description: | The following resources are available to interact with the documented API: - - - Docker Hub CLI tool (currently experimental) + - [Docker Hub CLI tool](https://github.com/docker/hub-tool#readme) (currently experimental) - name: rate-limiting x-displayName: Rate Limiting description: | The Docker Hub API is limited on the amount of requests you can perform per minute against it. - If you haven't hit the limit, each request to the API will return the - - following headers in the response. + If you haven't hit the limit, each request to the API will return the following headers in the response. - `X-RateLimit-Limit` - The limit of requests per minute. - `X-RateLimit-Remaining` - The remaining amount of calls within the limit period. - `X-RateLimit-Reset` - The unix timestamp of when the remaining resets. - If you have hit the limit, you will receive a response status of `429` and the `X-Retry-After` - header in the response. + If you have hit the limit, you will receive a response status of `429` and the `X-Retry-After` header in the response. The `X-Retry-After` header is a unix timestamp of when you can call the API again. - **Note**: These rate limits are separate from anti-abuse and Docker Hub - - download, or pull rate limiting. To learn more about Docker Hub pull rate - - limiting, see [Docker Hub download rate limit](https://docs.docker.com/docker-hub/download-rate-limit/). + **Note**: These rate limits are separate from anti-abuse and Docker Hub download, or pull rate limiting. + To learn more about Docker Hub pull rate limiting, see [Docker Hub download rate limit](https://docs.docker.com/docker-hub/download-rate-limit/). - name: authentication x-displayName: Authentication description: | - Most Docker Hub API endpoints require you to authenticate using your - Docker credentials before using them. + Most Docker Hub API endpoints require you to authenticate using your Docker credentials before using them. - Additionally, similar to the Docker Hub UI features, API endpoint responses may vary depending - on your plan (Personal, Pro, or Team) and your account's permissions. + Additionally, similar to the Docker Hub UI features, API endpoint responses may vary depending on your plan (Personal, Pro, or Team) and your account's permissions. To learn more about the features available in each plan and to upgrade your existing plan, see [Docker Pricing](https://www.docker.com/pricing). - name: access-tokens x-displayName: Personal Access Tokens description: | - The Personal Access Token endpoints lets you manage personal access tokens. For more - information, see [Access Tokens](https://docs.docker.com/security/for-developers/access-tokens/). + The Personal Access Token endpoints lets you manage personal access tokens. For more information, see [Access Tokens](https://docs.docker.com/security/for-developers/access-tokens/). - You can use a personal access token instead of a password in the [Docker CLI](https://docs.docker.com/engine/reference/commandline/cli/) - or in the [Create an authentication token](#operation/PostUsersLogin) route to obtain a bearer - token. + You can use a personal access token instead of a password in the [Docker CLI](https://docs.docker.com/engine/reference/commandline/cli/) or in the [Create an authentication token](#operation/PostUsersLogin) route to obtain a bearer token. ### Scopes - For each scope grouping (in this case "repo"), you only need to define 1 scope as any lower - scopes are assumed. For example: If you define `repo:write`, the API assumes the scope of both - `repo:read` *and* `repo:public_read` as well. If you were to define both `repo:write` *and* - `repo:read`, then `repo:read` is assumed by `repo:write` and ignored. + For each scope grouping (in this case "repo"), you only need to define 1 scope as any lower scopes are assumed. + For example: If you define `repo:write`, the API assumes the scope of both `repo:read` *and* `repo:public_read` as well. + If you were to define both `repo:write` *and* `repo:read`, then `repo:read` is assumed by `repo:write` and ignored. - ***Treat your personal access token like your password and keep it secret. You cannot retrieve - your token after it is generated.*** + ***Treat your personal access token like your password and keep it secret. You cannot retrieve your token after it is generated.*** - name: audit-logs x-displayName: Audit Logs description: | - The Audit Logs API endpoints allow you to query audit log events across a - namespace. + The Audit Logs API endpoints allow you to query audit log events across a namespace. For more information, see [Audit Log](https://docs.docker.com/admin/organization/activity-logs/). - name: org-settings x-displayName: Org Settings description: | - The Org Settings API endpoints allow you to manage your organization's - settings. + The Org Settings API endpoints allow you to manage your organization's settings. - name: repositories x-displayName: Repositories description: | - The repository endpoints allow you to access your repository's - tags. + The repository endpoints allow you to access your repository's tags. + - name: orgs + x-displayName: Organizations + x-audience: public + description: | + The organization endpoints allow you to interact with and manage your organizations. + + For more information, see [Organization administration overview](https://docs.docker.com/admin/organization/). + - name: groups + x-displayName: Groups (Teams) + x-audience: public + description: | + The groups endpoints allow you to manage your organization's teams and their members. + + For more information, seee [Create and manage a team](https://docs.docker.com/admin/organization/manage-a-team/). + - name: invites + x-displayName: Invites + x-audience: public + description: | + The invites endpoints allow you to manage invites for users to join your Docker organization. + + For more information, see [Invite members](https://docs.docker.com/admin/organization/members/#invite-members). - name: scim x-displayName: SCIM + x-audience: public description: | SCIM is a provisioning system that lets you manage users within your identity provider (IdP). + For more information, see [System for Cross-domain Identity management](https://docs.docker.com/security/for-admins/provisioning/scim/). -x-tagGroups: - - name: General - tags: - - resources - - rate-limiting - - name: API - tags: - - authentication - - access-tokens - - images - - audit-logs - - org-settings - - repositories - - scim paths: /v2/users/login: post: @@ -120,36 +112,33 @@ paths: summary: Create an authentication token operationId: PostUsersLogin description: | - Creates and returns a bearer token in JWT format that you can use to - authenticate with Docker Hub APIs. + Creates and returns a bearer token in JWT format that you can use to authenticate with Docker Hub APIs. The returned token is used in the HTTP Authorization header like `Authorization: Bearer {TOKEN}`. - Most Docker Hub APIs require this token either to consume or to get detailed information. For example, to list - images in a private repository. - - _**As of Monday, September 16, 2024, this route requires a PAT instead of a password if your organization has - SSO enforced.**_ + Most Docker Hub APIs require this token either to consume or to get detailed information. For example, to list images in a private repository. + + _**As of September 16, 2024, this route requires a PAT instead of a password if your organization has SSO enforced.**_ requestBody: content: application/json: schema: - $ref: "#/components/schemas/UsersLoginRequest" + $ref: '#/components/schemas/UsersLoginRequest' description: Login details. required: true responses: - 200: + '200': description: Authentication successful content: application/json: schema: - $ref: "#/components/schemas/PostUsersLoginSuccessResponse" - 401: + $ref: '#/components/schemas/PostUsersLoginSuccessResponse' + '401': description: Authentication failed or second factor required content: application/json: schema: - $ref: "#/components/schemas/PostUsersLoginErrorResponse" + $ref: '#/components/schemas/PostUsersLoginErrorResponse' /v2/users/2fa-login: post: tags: @@ -157,8 +146,7 @@ paths: summary: Second factor authentication operationId: PostUsers2FALogin description: | - When a user has two-factor authentication (2FA) enabled, this is the second call to perform after - `/v2/users/login` call. + When a user has two-factor authentication (2FA) enabled, this is the second call to perform after `/v2/users/login` call. Creates and returns a bearer token in JWT format that you can use to authenticate with Docker Hub APIs. @@ -169,22 +157,22 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/Users2FALoginRequest" + $ref: '#/components/schemas/Users2FALoginRequest' description: Login details. required: true responses: - 200: + '200': description: Authentication successful content: application/json: schema: - $ref: "#/components/schemas/PostUsersLoginSuccessResponse" - 401: + $ref: '#/components/schemas/PostUsersLoginSuccessResponse' + '401': description: Authentication failed or second factor required content: application/json: schema: - $ref: "#/components/schemas/PostUsers2FALoginErrorResponse" + $ref: '#/components/schemas/PostUsers2FALoginErrorResponse' /v2/access-tokens: post: summary: Create a personal access token @@ -195,19 +183,19 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/createAccessTokenRequest" + $ref: '#/components/schemas/createAccessTokenRequest' required: true responses: - 201: + '201': description: Created content: application/json: schema: - $ref: "#/components/schemas/createAccessTokensResponse" - 400: - $ref: "#/components/responses/BadRequest" - 401: - $ref: "#/components/responses/Unauthorized" + $ref: '#/components/schemas/createAccessTokensResponse' + '400': + $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/Unauthorized' get: summary: Get a list of personal access tokens description: Returns a paginated list of personal access tokens. @@ -225,16 +213,16 @@ paths: type: number default: 10 responses: - 200: + '200': description: OK content: application/json: schema: - $ref: "#/components/schemas/getAccessTokensResponse" - 400: - $ref: "#/components/responses/BadRequest" - 401: - $ref: "#/components/responses/Unauthorized" + $ref: '#/components/schemas/getAccessTokensResponse' + '400': + $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/Unauthorized' /v2/access-tokens/{uuid}: parameters: - in: path @@ -245,49 +233,48 @@ paths: patch: summary: Update a personal access token description: | - Updates a personal access token partially. You can either update the - token's label or enable/disable it. + Updates a personal access token partially. You can either update the token's label or enable/disable it. tags: - access-tokens requestBody: content: application/json: schema: - $ref: "#/components/schemas/patchAccessTokenRequest" + $ref: '#/components/schemas/patchAccessTokenRequest' required: true responses: - 200: + '200': description: OK content: application/json: schema: - $ref: "#/components/schemas/patchAccessTokenResponse" - 400: - $ref: "#/components/responses/BadRequest" - 401: - $ref: "#/components/responses/Unauthorized" + $ref: '#/components/schemas/patchAccessTokenResponse' + '400': + $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/Unauthorized' get: summary: Get a personal access token description: Returns a personal access token by UUID. tags: - access-tokens responses: - 200: + '200': description: OK content: application/json: schema: allOf: - - $ref: "#/components/schemas/accessToken" + - $ref: '#/components/schemas/accessToken' - type: object properties: token: type: string - example: "" - 401: - $ref: "#/components/responses/Unauthorized" - 404: - $ref: "#/components/responses/NotFound" + example: '' + '401': + $ref: '#/components/responses/Unauthorized' + '404': + $ref: '#/components/responses/NotFound' delete: summary: Delete a personal access token description: | @@ -295,24 +282,24 @@ paths: tags: - access-tokens responses: - 204: + '204': description: A successful response. - 401: - $ref: "#/components/responses/Unauthorized" - 404: - $ref: "#/components/responses/NotFound" + '401': + $ref: '#/components/responses/Unauthorized' + '404': + $ref: '#/components/responses/NotFound' /v2/auditlogs/{account}: get: summary: Returns list of audit log events description: Get audit log events for a given namespace. operationId: AuditLogs_GetAuditLogs responses: - 200: + '200': description: A successful response. content: application/json: schema: - $ref: "#/components/schemas/GetAuditLogsResponse" + $ref: '#/components/schemas/GetAuditLogsResponse' examples: response: value: @@ -324,12 +311,11 @@ paths: data: digest: sha256:c1ae9c435032a276f80220c7d9b40f76266bbe79243d34f9cda30b76fe114dfa tag: latest - timestamp: 2021-02-19T01:34:35Z - action_description: - pushed the tag latest with the digest - sha256:c1ae9c435032a to the repository docker/example - 429: - description: "" + timestamp: '2021-02-19T01:34:35Z' + action_description: | + pushed the tag latest with the digest sha256:c1ae9c435032a to the repository docker/example + '429': + description: '' content: application/json: schema: {} @@ -338,8 +324,8 @@ paths: value: detail: Rate limit exceeded error: false - 500: - description: "" + '500': + description: '' content: application/json: schema: {} @@ -348,7 +334,7 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/rpcStatus" + $ref: '#/components/schemas/rpcStatus' parameters: - name: account description: Namespace to query audit logs for. @@ -357,27 +343,22 @@ paths: schema: type: string - name: action - description: - action name one of ["repo.tag.push", ...]. Optional parameter to - filter specific audit log actions. + description: | + action name one of ["repo.tag.push", ...]. Optional parameter to filter specific audit log actions. in: query required: false schema: type: string - name: name - description: - name. Optional parameter to filter audit log events to a specific - name. For repository events, this is the name of the repository. For - organization events, this is the name of the organization. For team - member events, this is the username of the team member. + description: | + name. Optional parameter to filter audit log events to a specific name. For repository events, this is the name of the repository. For organization events, this is the name of the organization. For team member events, this is the username of the team member. in: query required: false schema: type: string - name: actor - description: - actor name. Optional parameter to filter audit log events to the - specific user who triggered the event. + description: | + actor name. Optional parameter to filter audit log events to the specific user who triggered the event. in: query required: false schema: @@ -417,17 +398,16 @@ paths: /v2/auditlogs/{account}/actions: get: summary: Returns list of audit log actions - description: - Get audit log actions for a namespace to be used as a filter for - querying audit events. + description: | + Get audit log actions for a namespace to be used as a filter for querying audit events. operationId: AuditLogs_GetAuditActions responses: - 200: + '200': description: A successful response. content: application/json: schema: - $ref: "#/components/schemas/GetAuditActionsResponse" + $ref: '#/components/schemas/GetAuditActionsResponse' examples: response: value: @@ -474,8 +454,8 @@ paths: description: contains image tag delete events label: Tag Deleted label: Repository - 429: - description: "" + '429': + description: '' content: application/json: schema: {} @@ -484,8 +464,8 @@ paths: value: detail: Rate limit exceeded error: false - 500: - description: "" + '500': + description: '' content: application/json: schema: {} @@ -494,7 +474,7 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/rpcStatus" + $ref: '#/components/schemas/rpcStatus' parameters: - name: account description: Namespace to query audit log actions for. @@ -519,23 +499,22 @@ paths: tags: - org-settings responses: - 200: + '200': description: OK content: application/json: schema: - $ref: "#/components/schemas/orgSettings" - 401: - $ref: "#/components/responses/Unauthorized" - 403: - $ref: "#/components/responses/Forbidden" - 404: - $ref: "#/components/responses/NotFound" + $ref: '#/components/schemas/orgSettings' + '401': + $ref: '#/components/responses/Unauthorized' + '403': + $ref: '#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/NotFound' put: summary: Update organization settings description: | - Updates an organization's settings. Some settings are only used when the - organization is on a business plan. + Updates an organization's settings. Some settings are only used when the organization is on a business plan. ***Only users with administrative privileges for the organization (owner role) can modify these settings.*** @@ -552,7 +531,7 @@ paths: properties: restricted_images: allOf: - - $ref: "#/components/schemas/restricted_images" + - $ref: '#/components/schemas/restricted_images' - type: object required: - enabled @@ -560,194 +539,713 @@ paths: - allow_verified_publishers required: true responses: - 200: + '200': description: OK content: application/json: schema: - $ref: "#/components/schemas/orgSettings" - 401: - $ref: "#/components/responses/Unauthorized" - 403: - $ref: "#/components/responses/Forbidden" - 404: - $ref: "#/components/responses/NotFound" - - + $ref: '#/components/schemas/orgSettings' + '401': + $ref: '#/components/responses/Unauthorized' + '403': + $ref: '#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/NotFound' /v2/namespaces/{namespace}/repositories/{repository}/tags: parameters: - - $ref: "#/components/parameters/namespace" - - $ref: "#/components/parameters/repository" + - $ref: '#/components/parameters/namespace' + - $ref: '#/components/parameters/repository' get: - summary: "List repository tags" - tags: [ repositories ] + summary: List repository tags + tags: + - repositories parameters: - - $ref: "#/components/parameters/page" - - $ref: "#/components/parameters/page_size" + - in: query + name: page + required: false + schema: + type: integer + description: Page number to get. Defaults to 1. + - in: query + name: page_size + required: false + schema: + type: integer + description: Number of items to get per page. Defaults to 10. Max of 100. responses: - 200: - $ref: "#/components/responses/list_tags" - 403: - $ref: "#/components/responses/Forbidden" - 404: - $ref: "#/components/responses/NotFound" + '200': + $ref: '#/components/responses/list_tags' + '403': + $ref: '#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/NotFound' head: - summary: "Check repository tags" - tags: [ repositories ] + summary: Check repository tags + tags: + - repositories responses: - 200: - description: "Repository contains tags" - 403: - $ref: "#/components/responses/Forbidden" - 404: - $ref: "#/components/responses/NotFound" - + '200': + description: Repository contains tags + '403': + $ref: '#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/NotFound' /v2/namespaces/{namespace}/repositories/{repository}/tags/{tag}: parameters: - - $ref: "#/components/parameters/namespace" - - $ref: "#/components/parameters/repository" - - $ref: "#/components/parameters/tag" + - $ref: '#/components/parameters/namespace' + - $ref: '#/components/parameters/repository' + - $ref: '#/components/parameters/tag' get: - summary: "Read repository tag" - tags: [ repositories ] + summary: Read repository tag + tags: + - repositories responses: - 200: - $ref: "#/components/responses/get_tag" - 403: - $ref: "#/components/responses/Forbidden" - 404: - $ref: "#/components/responses/NotFound" + '200': + $ref: '#/components/responses/get_tag' + '403': + $ref: '#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/NotFound' head: - summary: "Check repository tag" - tags: [ repositories ] + summary: Check repository tag + tags: + - repositories responses: - 200: - description: "Repository tag exists" - 403: - $ref: "#/components/responses/Forbidden" - 404: - $ref: "#/components/responses/NotFound" - - + '200': + description: Repository tag exists + '403': + $ref: '#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/NotFound' + /v2/orgs/{org_name}/members: + x-audience: public + parameters: + - $ref: '#/components/parameters/org_name' + - $ref: '#/components/parameters/search' + - $ref: '#/components/parameters/page' + - $ref: '#/components/parameters/page_size' + - $ref: '#/components/parameters/invites' + - $ref: '#/components/parameters/type' + - $ref: '#/components/parameters/role' + get: + summary: List org members + description: | + Returns a list of members for an organization" + tags: + - orgs + responses: + '200': + description: List of members + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/org_member_paginated' + '400': + $ref: '#/components/responses/bad_request' + '401': + $ref: '#/components/responses/unauthorized' + '403': + $ref: '#/components/responses/forbidden' + '404': + $ref: '#/components/responses/not_found' + /v2/orgs/{org_name}/members/export: + x-audience: public + parameters: + - $ref: '#/components/parameters/org_name' + get: + summary: Export org members CSV + description: | + Export members of an organization as a CSV + tags: + - orgs + responses: + '200': + description: Exported members + content: + text/csv: + schema: + type: array + items: + type: object + required: + - Name + - Username + - Email + - Type + - Role + - Date Joined + properties: + Name: + type: string + description: First and last name of the member + Username: + type: string + description: Username of the member + Email: + type: string + description: Email address of the member + Type: + type: string + description: Type of the member + enum: + - Invitee + - User + Permission: + type: string + description: Permission of the member + enum: + - Owner + - Member + Teams: + type: string + description: Comma-separated list of teams the member is part of + example: team-1, team-2 + Date Joined: + type: string + description: Date the member joined the organization + example: 2020-01-01 15:00:51.193355 +0000 UTC + headers: + Content-Disposition: + schema: + type: string + example: attachment;filename="{org_name}-members-{timestamp}.csv" + '400': + $ref: '#/components/responses/bad_request' + '401': + $ref: '#/components/responses/unauthorized' + '403': + $ref: '#/components/responses/forbidden' + '404': + $ref: '#/components/responses/not_found' + /v2/orgs/{org_name}/members/{username}: + x-audience: public + parameters: + - $ref: '#/components/parameters/org_name' + - $ref: '#/components/parameters/username' + put: + summary: Update org member (role) + description: | + Updates the role of a member in the organization. + ***Only users in the "owners" group of the organization can use this endpoint.*** + tags: + - orgs + requestBody: + required: true + content: + application/json: + schema: + required: + - role + properties: + role: + type: string + description: Role of the member + enum: + - owner + - editor + - member + responses: + '200': + description: Member role updated + content: + application/json: + schema: + $ref: '#/components/schemas/org_member' + '400': + $ref: '#/components/responses/bad_request' + '401': + $ref: '#/components/responses/unauthorized' + '403': + $ref: '#/components/responses/forbidden' + '404': + $ref: '#/components/responses/not_found' + delete: + summary: Remove member from org + description: | + Removes the member from the org, ie. all groups in the org, unless they're the last owner + tags: + - orgs + responses: + '204': + description: Member removed successfully + '400': + $ref: '#/components/responses/bad_request' + '401': + $ref: '#/components/responses/unauthorized' + '403': + $ref: '#/components/responses/forbidden' + '404': + $ref: '#/components/responses/not_found' + /v2/orgs/{org_name}/invites: + x-audience: public + parameters: + - $ref: '#/components/parameters/org_name' + get: + summary: List org invites + description: | + Return all pending invites for a given org, only team owners can call this endpoint + tags: + - invites + responses: + '200': + description: '' + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/invite' + '401': + $ref: '#/components/responses/unauthorized' + '403': + $ref: '#/components/responses/forbidden' + '404': + $ref: '#/components/responses/not_found' + /v2/orgs/{org_name}/groups: + x-audience: public + parameters: + - $ref: '#/components/parameters/org_name' + get: + summary: Get groups of an organization + tags: + - groups + parameters: + - $ref: '#/components/parameters/page' + - $ref: '#/components/parameters/page_size' + - in: query + name: username + schema: + type: string + description: Get groups for the specified username in the organization. + - in: query + name: search + schema: + type: string + description: Get groups for the specified group in the organization. + responses: + '200': + description: '' + content: + application/json: + schema: + properties: + count: + type: number + example: 1 + next: + type: string + example: null + previous: + type: string + example: null + results: + type: array + items: + $ref: '#/components/schemas/org_group' + '401': + $ref: '#/components/responses/unauthorized' + '403': + $ref: '#/components/responses/forbidden' + '404': + $ref: '#/components/responses/not_found' + post: + summary: Create a new group + description: Create a new group within an organization. + tags: + - groups + requestBody: + content: + application/json: + schema: + required: + - name + properties: + name: + type: string + description: + type: string + responses: + '201': + description: Group created successfully + content: + application/json: + schema: + $ref: '#/components/schemas/org_group' + '400': + $ref: '#/components/responses/bad_request' + '401': + $ref: '#/components/responses/unauthorized' + '403': + $ref: '#/components/responses/forbidden' + /v2/orgs/{org_name}/groups/{group_name}: + x-audience: public + parameters: + - $ref: '#/components/parameters/org_name' + - $ref: '#/components/parameters/group_name' + get: + summary: Get a group of an organization + tags: + - groups + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/org_group' + '401': + $ref: '#/components/responses/unauthorized' + '403': + $ref: '#/components/responses/forbidden' + '404': + $ref: '#/components/responses/not_found' + put: + summary: Update the details for an organization group + tags: + - groups + requestBody: + content: + application/json: + schema: + required: + - name + properties: + name: + type: string + description: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/org_group' + '401': + $ref: '#/components/responses/unauthorized' + '403': + $ref: '#/components/responses/forbidden' + '404': + $ref: '#/components/responses/not_found' + patch: + summary: Update some details for an organization group + tags: + - groups + requestBody: + content: + application/json: + schema: + properties: + name: + type: string + description: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/org_group' + '401': + $ref: '#/components/responses/unauthorized' + '403': + $ref: '#/components/responses/forbidden' + '404': + $ref: '#/components/responses/not_found' + delete: + summary: Delete an organization group + tags: + - groups + responses: + '204': + description: Group deleted successfully + '401': + $ref: '#/components/responses/unauthorized' + '403': + $ref: '#/components/responses/forbidden' + '404': + $ref: '#/components/responses/not_found' + /v2/orgs/{org_name}/groups/{group_name}/members: + x-audience: public + get: + parameters: + - $ref: '#/components/parameters/org_name' + - $ref: '#/components/parameters/group_name' + - $ref: '#/components/parameters/page' + - $ref: '#/components/parameters/page_size' + - in: query + name: search + schema: + type: string + description: Search members by username, full_name or email. + summary: List members of a group + description: | + List the members (users) that are in a group. + If user is owner of the org or has otherwise elevated permissions, they can search by email and the result will also contain emails. + tags: + - groups + responses: + '200': + description: '' + content: + application/json: + schema: + properties: + count: + type: number + example: 1 + next: + type: string + example: null + previous: + type: string + example: null + results: + type: array + items: + $ref: '#/components/schemas/group_member' + '401': + $ref: '#/components/responses/unauthorized' + '403': + $ref: '#/components/responses/forbidden' + '404': + $ref: '#/components/responses/not_found' + post: + parameters: + - $ref: '#/components/parameters/org_name' + - $ref: '#/components/parameters/group_name' + summary: Adds a member to a group + tags: + - groups + requestBody: + $ref: '#/components/requestBodies/add_member_to_org_group' + responses: + '200': + description: OK + '401': + $ref: '#/components/responses/unauthorized' + '403': + $ref: '#/components/responses/forbidden' + '404': + $ref: '#/components/responses/not_found' + '500': + $ref: '#/components/responses/internal_error' + /v2/orgs/{org_name}/groups/{group_name}/members/{username}: + x-audience: public + parameters: + - $ref: '#/components/parameters/org_name' + - $ref: '#/components/parameters/group_name' + - $ref: '#/components/parameters/username' + delete: + summary: Removes a user from a group + tags: + - groups + responses: + '204': + description: User removed successfully + '401': + $ref: '#/components/responses/unauthorized' + '403': + $ref: '#/components/responses/forbidden' + '404': + $ref: '#/components/responses/not_found' + /v2/invites/{id}: + x-audience: public + parameters: + - in: path + name: id + required: true + schema: + type: string + delete: + summary: Cancel an invite + description: | + Mark the invite as cancelled so it doesn't show up on the list of pending invites + tags: + - invites + responses: + '204': + description: '' + '401': + $ref: '#/components/responses/unauthorized' + '403': + $ref: '#/components/responses/forbidden' + '404': + $ref: '#/components/responses/not_found' + /v2/invites/{id}/resend: + x-audience: public + parameters: + - in: path + name: id + schema: + type: string + required: true + patch: + summary: Resend an invite + description: | + Resend a pending invite to the user, any org owner can resend an invite + tags: + - invites + responses: + '204': + description: '' + '401': + $ref: '#/components/responses/unauthorized' + '403': + $ref: '#/components/responses/forbidden' + '404': + $ref: '#/components/responses/not_found' + /v2/invites/bulk: + x-audience: public + parameters: + - $ref: '#/components/parameters/bulk_invite' + post: + summary: Bulk create invites + description: | + Create multiple invites by emails or DockerIDs. Only a team owner can create invites. + tags: + - invites + requestBody: + $ref: '#/components/requestBodies/bulk_invite_request' + responses: + '202': + description: Accepted + content: + application/json: + schema: + type: object + properties: + invitees: + $ref: '#/components/schemas/bulk_invite' + '400': + $ref: '#/components/responses/bad_request' + '409': + $ref: '#/components/responses/conflict' /v2/scim/2.0/ServiceProviderConfig: + x-audience: public get: summary: Get service provider config description: | Returns a service provider config for Docker's configuration. - tags: [ scim ] + tags: + - scim security: - - bearerSCIMAuth: [ ] + - bearerSCIMAuth: [] responses: - 200: + '200': $ref: '#/components/responses/scim_get_service_provider_config_resp' - 401: - $ref: "#/components/responses/scim_unauthorized" - 500: - $ref: "#/components/responses/scim_error" - + '401': + $ref: '#/components/responses/scim_unauthorized' + '500': + $ref: '#/components/responses/scim_error' /v2/scim/2.0/ResourceTypes: + x-audience: public get: summary: List resource types description: | Returns all resource types supported for the SCIM configuration. - tags: [ scim ] + tags: + - scim security: - - bearerSCIMAuth: [ ] + - bearerSCIMAuth: [] responses: - 200: - $ref: "#/components/responses/scim_get_resource_types_resp" - 401: - $ref: "#/components/responses/scim_unauthorized" - 500: - $ref: "#/components/responses/scim_error" - + '200': + $ref: '#/components/responses/scim_get_resource_types_resp' + '401': + $ref: '#/components/responses/scim_unauthorized' + '500': + $ref: '#/components/responses/scim_error' /v2/scim/2.0/ResourceTypes/{name}: + x-audience: public get: summary: Get a resource type description: | Returns a resource type by name. - tags: [ scim ] + tags: + - scim parameters: - name: name in: path schema: type: string example: User + required: true security: - - bearerSCIMAuth: [ ] + - bearerSCIMAuth: [] responses: - 200: - $ref: "#/components/responses/scim_get_resource_type_resp" - 401: - $ref: "#/components/responses/scim_unauthorized" - 404: - $ref: "#/components/responses/scim_not_found" - 500: - $ref: "#/components/responses/scim_error" - + '200': + $ref: '#/components/responses/scim_get_resource_type_resp' + '401': + $ref: '#/components/responses/scim_unauthorized' + '404': + $ref: '#/components/responses/scim_not_found' + '500': + $ref: '#/components/responses/scim_error' /v2/scim/2.0/Schemas: + x-audience: public get: summary: List schemas description: | Returns all schemas supported for the SCIM configuration. - tags: [ scim ] + tags: + - scim security: - - bearerSCIMAuth: [ ] + - bearerSCIMAuth: [] responses: - 200: - $ref: "#/components/responses/scim_get_schemas_resp" - 401: - $ref: "#/components/responses/scim_unauthorized" - 500: - $ref: "#/components/responses/scim_error" - + '200': + $ref: '#/components/responses/scim_get_schemas_resp' + '401': + $ref: '#/components/responses/scim_unauthorized' + '500': + $ref: '#/components/responses/scim_error' /v2/scim/2.0/Schemas/{id}: + x-audience: public get: summary: Get a schema description: | Returns a schema by ID. - tags: [ scim ] + tags: + - scim parameters: - name: id in: path schema: type: string example: urn:ietf:params:scim:schemas:core:2.0:User + required: true security: - - bearerSCIMAuth: [ ] + - bearerSCIMAuth: [] responses: - 200: - $ref: "#/components/responses/scim_get_schema_resp" - 401: - $ref: "#/components/responses/scim_unauthorized" - 404: - $ref: "#/components/responses/scim_not_found" - 500: - $ref: "#/components/responses/scim_error" - + '200': + $ref: '#/components/responses/scim_get_schema_resp' + '401': + $ref: '#/components/responses/scim_unauthorized' + '404': + $ref: '#/components/responses/scim_not_found' + '500': + $ref: '#/components/responses/scim_error' /v2/scim/2.0/Users: + x-audience: public get: summary: List users description: | - List users, returns paginated users for an organization. Use `startIndex` - and `count` query parameters to receive paginated results. + Returns paginated users for an organization. Use `startIndex` and `count` query parameters to receive paginated results. + + **Sorting:** - **Sorting:**
- Sorting lets you specify the order of returned resources by specifying - a combination of `sortBy` and `sortOrder` query parameters. + Sorting allows you to specify the order in which resources are returned by specifying a combination of `sortBy` and `sortOrder` query parameters. - The `sortBy` parameter specifies the attribute whose value will be used - to order the returned responses. The `sortOrder` parameter defines the - order in which the `sortBy` parameter is applied. Allowed values are - "ascending" and "descending". + The `sortBy` parameter specifies the attribute whose value will be used to order the returned responses. The `sortOrder` parameter defines the order in which the `sortBy` parameter is applied. Allowed values are "ascending" and "descending". - **Filtering:**
- You can request a subset of resources by specifying the `filter` query - parameter containing a filter expression. Attribute names and attribute - operators used in filters are case insensitive. The filter parameter - must contain at least one valid expression. Each expression must contain - an attribute name followed by an attribute operator and an optional - value. + **Filtering:** + + You can request a subset of resources by specifying the `filter` query parameter containing a filter expression. Attribute names and attribute operators used in filters are case insensitive. The filter parameter must contain at least one valid expression. Each expression must contain an attribute name followed by an attribute operator and an optional value. Supported operators are listed below. @@ -759,16 +1257,17 @@ paths: - `or` Logical "or" - `not` "Not" function - `()` Precedence grouping - tags: [ scim ] + tags: + - scim security: - - bearerSCIMAuth: [ ] + - bearerSCIMAuth: [] parameters: - name: startIndex in: query schema: type: integer minimum: 1 - description: "" + description: '' example: 1 - name: count in: query @@ -776,15 +1275,15 @@ paths: type: integer minimum: 1 maximum: 200 - description: "" + description: '' example: 10 - name: filter in: query schema: type: string - description: "" + description: '' example: userName eq "jon.snow@docker.com" - - $ref: "#/components/parameters/scim_attributes" + - $ref: '#/components/parameters/scim_attributes' - name: sortOrder in: query schema: @@ -796,100 +1295,96 @@ paths: in: query schema: type: string - description: "User attribute to sort by." + description: User attribute to sort by. example: userName responses: - 200: - $ref: "#/components/responses/scim_get_users_resp" - 400: - $ref: "#/components/responses/scim_bad_request" - 401: - $ref: "#/components/responses/scim_unauthorized" - 403: - $ref: "#/components/responses/scim_forbidden" - 404: - $ref: "#/components/responses/scim_not_found" - 500: - $ref: "#/components/responses/scim_error" - + '200': + $ref: '#/components/responses/scim_get_users_resp' + '400': + $ref: '#/components/responses/scim_bad_request' + '401': + $ref: '#/components/responses/scim_unauthorized' + '403': + $ref: '#/components/responses/scim_forbidden' + '404': + $ref: '#/components/responses/scim_not_found' + '500': + $ref: '#/components/responses/scim_error' post: summary: Create user description: | - Creates a user. If the user already exists by email, they are assigned - to the organization on the "company" team. - tags: [ scim ] + Creates a user. If the user already exists by email, they are assigned to the organization on the "company" team. + tags: + - scim security: - - bearerSCIMAuth: [ ] + - bearerSCIMAuth: [] requestBody: - $ref: "#/components/requestBodies/scim_create_user_request" + $ref: '#/components/requestBodies/scim_create_user_request' responses: - 201: - $ref: "#/components/responses/scim_create_user_resp" - 400: - $ref: "#/components/responses/scim_bad_request" - 401: - $ref: "#/components/responses/scim_unauthorized" - 403: - $ref: "#/components/responses/scim_forbidden" - 404: - $ref: "#/components/responses/scim_not_found" - 409: - $ref: "#/components/responses/scim_conflict" - 500: - $ref: "#/components/responses/scim_error" - + '201': + $ref: '#/components/responses/scim_create_user_resp' + '400': + $ref: '#/components/responses/scim_bad_request' + '401': + $ref: '#/components/responses/scim_unauthorized' + '403': + $ref: '#/components/responses/scim_forbidden' + '404': + $ref: '#/components/responses/scim_not_found' + '409': + $ref: '#/components/responses/scim_conflict' + '500': + $ref: '#/components/responses/scim_error' /v2/scim/2.0/Users/{id}: + x-audience: public parameters: - - $ref: "#/components/parameters/scim_user_id" + - $ref: '#/components/parameters/scim_user_id' get: summary: Get a user description: | Returns a user by ID. - tags: [ scim ] + tags: + - scim security: - - bearerSCIMAuth: [ ] + - bearerSCIMAuth: [] responses: - 200: - $ref: "#/components/responses/scim_get_user_resp" - 400: - $ref: "#/components/responses/scim_bad_request" - 401: - $ref: "#/components/responses/scim_unauthorized" - 403: - $ref: "#/components/responses/scim_forbidden" - 404: - $ref: "#/components/responses/scim_not_found" - 500: - $ref: "#/components/responses/scim_error" + '200': + $ref: '#/components/responses/scim_get_user_resp' + '400': + $ref: '#/components/responses/scim_bad_request' + '401': + $ref: '#/components/responses/scim_unauthorized' + '403': + $ref: '#/components/responses/scim_forbidden' + '404': + $ref: '#/components/responses/scim_not_found' + '500': + $ref: '#/components/responses/scim_error' put: summary: Update a user description: | - Updates a user. Use this route to change the user's name, activate, - and deactivate the user. - tags: [ scim ] + Updates a user. This route is used to change the user's name, activate, and deactivate the user. + tags: + - scim security: - - bearerSCIMAuth: [ ] + - bearerSCIMAuth: [] requestBody: - $ref: "#/components/requestBodies/scim_update_user_request" + $ref: '#/components/requestBodies/scim_update_user_request' responses: - 200: - $ref: "#/components/responses/scim_update_user_resp" - 400: - $ref: "#/components/responses/scim_bad_request" - 401: - $ref: "#/components/responses/scim_unauthorized" - 403: - $ref: "#/components/responses/scim_forbidden" - 404: - $ref: "#/components/responses/scim_not_found" - 409: - $ref: "#/components/responses/scim_conflict" - 500: - $ref: "#/components/responses/scim_error" - - -servers: - - url: https://hub.docker.com/ + '200': + $ref: '#/components/responses/scim_update_user_resp' + '400': + $ref: '#/components/responses/scim_bad_request' + '401': + $ref: '#/components/responses/scim_unauthorized' + '403': + $ref: '#/components/responses/scim_forbidden' + '404': + $ref: '#/components/responses/scim_not_found' + '409': + $ref: '#/components/responses/scim_conflict' + '500': + $ref: '#/components/responses/scim_error' components: responses: BadRequest: @@ -897,100 +1392,144 @@ components: content: application/json: schema: - $ref: "#/components/schemas/ValueError" + $ref: '#/components/schemas/ValueError' Unauthorized: description: Unauthorized content: application/json: schema: - $ref: "#/components/schemas/Error" + $ref: '#/components/schemas/Error' Forbidden: description: Forbidden content: application/json: schema: - $ref: "#/components/schemas/Error" + $ref: '#/components/schemas/Error' NotFound: description: Not Found content: application/json: schema: - $ref: "#/components/schemas/Error" - + $ref: '#/components/schemas/Error' + list_tags: + description: list repository tags + content: + application/json: + schema: + $ref: '#/components/schemas/paginated_tags' + get_tag: + description: repository tag + content: + application/json: + schema: + $ref: '#/components/schemas/tag' + bad_request: + description: Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/error' + unauthorized: + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/error' + forbidden: + description: Forbidden + content: + application/json: + schema: + $ref: '#/components/schemas/error' + not_found: + description: Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/error' + conflict: + description: Conflict + content: + application/json: + schema: + $ref: '#/components/schemas/error' + internal_error: + description: Internal + content: + application/json: + schema: + $ref: '#/components/schemas/error' scim_bad_request: description: Bad Request content: application/scim+json: schema: allOf: - - $ref: "#/components/schemas/scim_error" + - $ref: '#/components/schemas/scim_error' - properties: status: - example: "400" + example: '400' scimType: type: string - description: Some types of errors will return this per the - specification. + description: Some types of errors will return this per the specification. scim_unauthorized: description: Unauthorized content: application/scim+json: schema: allOf: - - $ref: "#/components/schemas/scim_error" + - $ref: '#/components/schemas/scim_error' - properties: status: - example: "401" + example: '401' scim_forbidden: description: Forbidden content: application/scim+json: schema: allOf: - - $ref: "#/components/schemas/scim_error" + - $ref: '#/components/schemas/scim_error' - properties: status: - example: "403" + example: '403' scim_not_found: description: Not Found content: application/scim+json: schema: allOf: - - $ref: "#/components/schemas/scim_error" + - $ref: '#/components/schemas/scim_error' - properties: status: - example: "404" + example: '404' scim_conflict: description: Conflict content: application/scim+json: schema: allOf: - - $ref: "#/components/schemas/scim_error" + - $ref: '#/components/schemas/scim_error' - properties: status: - example: "409" + example: '409' scim_error: description: Internal Error content: application/scim+json: schema: allOf: - - $ref: "#/components/schemas/scim_error" + - $ref: '#/components/schemas/scim_error' - properties: status: - example: "500" - + example: '500' scim_get_service_provider_config_resp: - description: "" + description: '' content: application/scim+json: schema: - $ref: "#/components/schemas/scim_service_provider_config" - + $ref: '#/components/schemas/scim_service_provider_config' scim_get_resource_types_resp: - description: "" + description: '' content: application/scim+json: schema: @@ -1000,24 +1539,22 @@ components: type: array items: type: string - example: [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ] + example: urn:ietf:params:scim:api:messages:2.0:ListResponse totalResults: type: integer example: 1 resources: type: array items: - $ref: "#/components/schemas/scim_resource_type" - + $ref: '#/components/schemas/scim_resource_type' scim_get_resource_type_resp: - description: "" + description: '' content: application/scim+json: schema: - $ref: "#/components/schemas/scim_resource_type" - + $ref: '#/components/schemas/scim_resource_type' scim_get_schemas_resp: - description: "" + description: '' content: application/scim+json: schema: @@ -1027,24 +1564,22 @@ components: type: array items: type: string - example: [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ] + example: urn:ietf:params:scim:api:messages:2.0:ListResponse totalResults: type: integer example: 1 resources: type: array items: - $ref: "#/components/schemas/scim_schema" - + $ref: '#/components/schemas/scim_schema' scim_get_schema_resp: - description: "" + description: '' content: application/scim+json: schema: - $ref: "#/components/schemas/scim_schema" - + $ref: '#/components/schemas/scim_schema' scim_get_users_resp: - description: "" + description: '' content: application/scim+json: schema: @@ -1054,7 +1589,8 @@ components: type: array items: type: string - example: [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ] + example: + - urn:ietf:params:scim:api:messages:2.0:ListResponse totalResults: type: integer example: 1 @@ -1067,43 +1603,25 @@ components: resources: type: array items: - $ref: "#/components/schemas/scim_user" - + $ref: '#/components/schemas/scim_user' scim_create_user_resp: - description: "" + description: '' content: application/scim+json: schema: - $ref: "#/components/schemas/scim_user" - + $ref: '#/components/schemas/scim_user' scim_get_user_resp: - description: "" + description: '' content: application/scim+json: schema: - $ref: "#/components/schemas/scim_user" - + $ref: '#/components/schemas/scim_user' scim_update_user_resp: - description: "" + description: '' content: application/scim+json: schema: - $ref: "#/components/schemas/scim_user" - - list_tags: - description: "list repository tags" - content: - application/json: - schema: - $ref: "#/components/schemas/paginated_tags" - - get_tag: - description: "repository tag" - content: - application/json: - schema: - $ref: "#/components/schemas/tag" - + $ref: '#/components/schemas/scim_user' schemas: UsersLoginRequest: description: User login details @@ -1117,11 +1635,10 @@ components: type: string example: myusername password: - description: - The password or personal access token (PAT) of the Docker Hub - account to authenticate with. + description: | + The password or personal access token (PAT) of the Docker Hub account to authenticate with. type: string - example: hunter2 + example: p@ssw0rd PostUsersLoginSuccessResponse: description: successful user login response type: object @@ -1129,7 +1646,6 @@ components: token: description: | Created authentication token. - This token can be used in the HTTP Authorization header as a JWT to authenticate with the Docker Hub APIs. type: string example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c @@ -1146,10 +1662,8 @@ components: example: Incorrect authentication credentials nullable: false login_2fa_token: - description: - Short time lived token to be used on `/v2/users/2fa-login` to - complete the authentication. This field is present only if 2FA is - enabled. + description: | + Short time lived token to be used on `/v2/users/2fa-login` to complete the authentication. This field is present only if 2FA is enabled. type: string example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c nullable: true @@ -1165,9 +1679,8 @@ components: type: string example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c code: - description: - The Time-based One-Time Password of the Docker Hub account to - authenticate with. + description: | + The Time-based One-Time Password of the Docker Hub account to authenticate with. type: string example: 123456 PostUsers2FALoginErrorResponse: @@ -1179,369 +1692,6 @@ components: type: string example: Incorrect authentication credentials nullable: false - ErrorInfo: - description: Context information for an error used for diagnostics. - type: object - properties: - api_call_docker_id: - description: ID of docker user. - type: string - api_call_name: - description: Name of the API operation called. - type: string - api_call_start: - description: Date/time of call start. - type: string - api_call_txnid: - description: Unique ID for this call. - type: string - ErrorResponse: - description: Represents an error. - type: object - properties: - txnid: - description: Unique ID for this call. - type: string - message: - description: The error message. - type: string - errinfo: - $ref: "#/components/schemas/ErrorInfo" - ErrorDetail: - description: Error with a detail field. - type: object - properties: - detail: - description: The error message. - type: string - GetNamespaceRepositoryImagesSummaryResponse: - description: Summary information for images in a repository. - type: object - properties: - active_from: - description: - Time from which an image must have been pushed or pulled to be - counted as active. - type: string - example: 2021-01-25T14:25:37.076343059Z - statistics: - type: object - properties: - total: - description: Number of images in this repository. - type: integer - example: 3 - active: - description: Number of images counted as active in this repository. - type: integer - example: 2 - inactive: - description: Number of images counted as inactive in this repository. - type: integer - example: 1 - GetNamespaceRepositoryImagesResponse: - description: Paginated list of images in a repository. - type: object - properties: - count: - description: Total count of images in the repository. - type: integer - example: 100 - next: - description: - Link to the next page with the same query parameters if there are - more images. - type: string - example: https://hub.docker.com/v2/namespaces/mynamespace/repositories/myrepo/images?&page=4&page_size=20 - nullable: true - previous: - description: - Link to the previous page with the same query parameters if not on - first page. - type: string - example: https://hub.docker.com/v2/namespaces/mynamespace/repositories/myrepo/images?&page=2&page_size=20 - nullable: true - results: - type: array - description: Image details. - items: - type: object - properties: - namespace: - description: The repository namespace. - type: string - example: mynamespace - repository: - description: The repository name. - type: string - example: myrepo - digest: - description: The image's digest. - type: string - example: sha256:1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr - tags: - description: The current and historical tags for this image. - type: array - items: - type: object - properties: - tag: - description: The tag. - type: string - example: latest - is_current: - description: | - `true` if the tag currently points to this image. - - `false` if it has been overwritten to point at a different image. - type: boolean - example: true - last_pushed: - description: Time when this image was last pushed. - type: string - example: 2021-02-24T22:05:27.526308Z - nullable: true - last_pulled: - description: - Time when this image was last pulled. Note this is updated at - most once per hour. - type: string - example: 2021-02-24T23:16:10.200008Z - nullable: true - status: - description: - The status of the image based on its last activity against the - `active_from` time. - type: string - enum: - - active - - inactive - example: active - GetNamespaceRepositoryImagesTagsResponse: - description: Paginated list of tags for this repository. - type: object - properties: - count: - description: Total count of tags for this image. - type: integer - example: 100 - next: - description: Link to the next page if there are more tags. - type: string - example: https://hub.docker.com/v2/namespaces/mynamespace/repositories/myrepo/images/sha256:mydigest/tags?&page=4&page_size=20 - nullable: true - previous: - description: Link to the previous page if not on first page. - type: string - example: https://hub.docker.com/v2/namespaces/mynamespace/repositories/myrepo/images/sha256:mydigest/tags?&page=2&page_size=20 - nullable: true - results: - description: The current and historical tags for this image. - type: array - items: - type: object - properties: - tag: - description: The tag. - type: string - example: latest - is_current: - description: | - `true` if the tag currently points to this image. - - `false` if it has been overwritten to point at a different image. - type: boolean - example: true - PostNamespacesDeleteImagesRequest: - description: Delete images request. - type: object - properties: - dry_run: - description: - If `true` then will check and return errors and unignored warnings - for the deletion request but will not delete any images. - type: boolean - example: false - active_from: - description: | - Sets the time from which an image must have been pushed or pulled to - be counted as active. - - Defaults to 1 month before the current time. - type: string - example: 2020-12-01T12:00:00Z - manifests: - description: Image manifests to delete. - type: array - items: - type: object - required: - - repository - - digest - properties: - repository: - description: Name of the repository to delete the image from. - type: string - example: myrepo - digest: - description: Digest of the image to delete. - type: string - example: sha256:1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr - ignore_warnings: - description: | - Warnings to ignore. If a warning is not ignored then no deletions will happen and the - warning is returned in the response. - - These warnings include: - - - is_active: warning when attempting to delete an image that is marked as active. - - current_tag: warning when attempting to delete an image that has one or more current - tags in the repository. - - Warnings can be copied from the response to the request. - type: array - items: - type: object - required: - - repository - - digest - - warning - properties: - repository: - description: Name of the repository of the image to ignore the warning for. - type: string - example: myrepo - digest: - description: Digest of the image to ignore the warning for. - type: string - example: sha256:1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr - warning: - description: Warning to ignore. - type: string - enum: - - is_active - - current_tag - example: current_tag - tags: - description: Current tags to ignore. - type: array - items: - type: string - example: latest - PostNamespacesDeleteImagesResponseSuccess: - description: Successful delete images response. - type: object - properties: - dry_run: - description: Whether the request was a dry run or not. - type: boolean - example: false - metrics: - type: object - properties: - manifest_deletes: - description: Number of manifests deleted. - type: integer - example: 3 - manifest_errors: - description: Number of manifests that failed to delete. - type: integer - example: 0 - tag_deletes: - description: Number of tags deleted. - type: integer - example: 1 - tag_errors: - description: Number of tags that failed to delete. - type: integer - example: 0 - PostNamespacesDeleteImagesResponseError: - description: Deletion not possible. - type: object - properties: - txnid: - description: Unique ID for this call. - type: string - message: - description: The error message. - type: string - errinfo: - allOf: - - $ref: "#/components/schemas/ErrorInfo" - - type: object - properties: - type: - description: Type of error. - type: string - example: validation - details: - type: object - properties: - errors: - description: - Errors from validating delete request. These cannot be - ignored. - type: array - items: - type: object - properties: - repository: - description: - Name of the repository of the image that caused - the error. - type: string - example: myrepo - digest: - description: Digest of the image that caused the error. - type: string - example: sha256:1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr - error: - description: Error type. - type: string - enum: - - not_found - - unauthorized - - child_manifest - example: not_found - warnings: - description: | - Warnings that can be ignored. - - These warnings include: - - - is_active: warning when attempting to delete an image that is marked as - active. - - current_tag: warning when attempting to delete an image that has one or - more current tags in the repository. - - Warnings can be copied from the response to the request. - type: array - items: - type: object - properties: - repository: - description: - Name of the repository of the image that caused - the warning. - type: string - example: myrepo - digest: - description: Digest of the image that caused the warning. - type: string - example: sha256:1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr - warning: - description: Warning type. - type: string - enum: - - is_active - - current_tag - example: current_tag - tags: - description: Current tags if warning is `current_tag`. - type: array - items: - type: string - example: latest protobufAny: type: object properties: @@ -1561,7 +1711,7 @@ components: details: type: array items: - $ref: "#/components/schemas/protobufAny" + $ref: '#/components/schemas/protobufAny' AuditLogAction: type: object properties: @@ -1581,7 +1731,7 @@ components: actions: type: array items: - $ref: "#/components/schemas/AuditLogAction" + $ref: '#/components/schemas/AuditLogAction' description: List of audit log actions. label: type: string @@ -1592,7 +1742,7 @@ components: actions: type: object additionalProperties: - $ref: "#/components/schemas/AuditLogActions" + $ref: '#/components/schemas/AuditLogActions' description: Map of audit log actions. description: GetAuditActions response. GetAuditLogsResponse: @@ -1601,7 +1751,7 @@ components: logs: type: array items: - $ref: "#/components/schemas/AuditLog" + $ref: '#/components/schemas/AuditLog' description: List of audit log events. description: GetAuditLogs response. AuditLog: @@ -1659,7 +1809,7 @@ components: example: some user agent created_at: type: string - example: 2021-07-20T12:00:00.000000Z + example: '2021-07-20T12:00:00.000000Z' last_used: type: string example: null @@ -1703,7 +1853,7 @@ components: items: type: string createAccessTokensResponse: - $ref: "#/components/schemas/accessToken" + $ref: '#/components/schemas/accessToken' getAccessTokensResponse: type: object properties: @@ -1723,12 +1873,12 @@ components: type: array items: allOf: - - $ref: "#/components/schemas/accessToken" + - $ref: '#/components/schemas/accessToken' - type: object properties: token: type: string - example: "" + example: '' patchAccessTokenRequest: type: object properties: @@ -1741,12 +1891,12 @@ components: type: boolean example: false patchAccessTokenResponse: - $ref: "#/components/schemas/accessToken" + $ref: '#/components/schemas/accessToken' orgSettings: type: object properties: restricted_images: - $ref: "#/components/schemas/restricted_images" + $ref: '#/components/schemas/restricted_images' restricted_images: type: object properties: @@ -1767,29 +1917,29 @@ components: properties: digest: type: string - description: "image layer digest" + description: image layer digest nullable: true size: type: integer - description: "size of the layer" + description: size of the layer instruction: type: string - description: "Dockerfile instruction" + description: Dockerfile instruction image: type: object properties: architecture: type: string - description: "CPU architecture" + description: CPU architecture features: type: string - description: "CPU features" + description: CPU features variant: type: string - description: "CPU variant" + description: CPU variant digest: type: string - description: "image digest" + description: image digest nullable: true layers: type: array @@ -1797,80 +1947,83 @@ components: $ref: '#/components/schemas/layer' os: type: string - description: "operating system" + description: operating system os_features: type: string - description: "OS features" + description: OS features os_version: type: string - description: "OS version" + description: OS version size: type: integer - description: "size of the image" + description: size of the image status: type: string - enum: ["active", "inactive"] - description: "Status of the image" + enum: + - active + - inactive + description: Status of the image last_pulled: type: string - example: "2021-01-05T21:06:53.506400Z" - description: "datetime of last pull" + example: '2021-01-05T21:06:53.506400Z' + description: datetime of last pull nullable: true last_pushed: type: string - example: "2021-01-05T21:06:53.506400Z" - description: "datetime of last push" + example: '2021-01-05T21:06:53.506400Z' + description: datetime of last push nullable: true tag: type: object properties: id: type: integer - description: "tag ID" + description: tag ID images: type: object $ref: '#/components/schemas/image' creator: type: integer - description: "ID of the user that pushed the tag" + description: ID of the user that pushed the tag last_updated: type: string - example: "2021-01-05T21:06:53.506400Z" - description: "datetime of last update" + example: '2021-01-05T21:06:53.506400Z' + description: datetime of last update nullable: true last_updater: type: integer - description: "ID of the last user that updated the tag" + description: ID of the last user that updated the tag last_updater_username: type: string - description: "Hub username of the user that updated the tag" + description: Hub username of the user that updated the tag name: type: string - description: "name of the tag" + description: name of the tag repository: type: integer - description: "repository ID" + description: repository ID full_size: type: integer - description: "compressed size (sum of all layers) of the tagged image" + description: compressed size (sum of all layers) of the tagged image v2: type: string - description: "repository API version" + description: repository API version status: type: string - enum: ["active", "inactive"] - description: "whether a tag has been pushed to or pulled in the past month" + enum: + - active + - inactive + description: whether a tag has been pushed to or pulled in the past month tag_last_pulled: type: string - example: "2021-01-05T21:06:53.506400Z" - description: "datetime of last pull" + example: '2021-01-05T21:06:53.506400Z' + description: datetime of last pull nullable: true tag_last_pushed: type: string - example: "2021-01-05T21:06:53.506400Z" - description: "datetime of last push" + example: '2021-01-05T21:06:53.506400Z' + description: datetime of last push nullable: true - paginated_tags: allOf: - $ref: '#/components/schemas/page' @@ -1894,7 +2047,118 @@ components: type: string description: link to previous page of results if any nullable: true - + scim_schema_attribute: + type: object + properties: + name: + type: string + example: userName + type: + enum: + - string + - boolean + - complex + type: string + example: string + multiValued: + type: boolean + example: false + description: + type: string + example: Unique identifier for the User, typically used by the user to directly authenticate to the service provider. Each User MUST include a non-empty userName value. This identifier MUST be unique across the service provider's entire set of Users. + required: + type: boolean + example: true + caseExact: + type: boolean + example: false + mutability: + type: string + example: readWrite + returned: + type: string + example: default + uniqueness: + type: string + example: server + scim_schema_parent_attribute: + allOf: + - $ref: '#/components/schemas/scim_schema_attribute' + - type: object + properties: + subAttributes: + type: array + items: + $ref: '#/components/schemas/scim_schema_attribute' + invite: + type: object + properties: + id: + type: string + description: uuid representing the invite id + example: e36eca69-4cc8-4f17-9845-ae8c2b832691 + inviter_username: + type: string + example: moby + invitee: + type: string + description: can either be a dockerID for registred users or an email for non-registred users + example: invitee@docker.com + org: + type: string + description: name of the org to join + example: docker + team: + type: string + description: name of the team (user group) to join + example: owners + created_at: + type: string + example: '2021-10-28T18:30:19.520861Z' + bulk_invite: + type: object + properties: + invitees: + type: array + description: A list of invitees + items: + type: object + properties: + invitee: + type: string + description: invitee email or Docker ID + status: + type: string + description: status of the invite or validation error + invite: + description: Invite data if successfully invited + $ref: '#/components/schemas/invite' + example: + invitees: + - invitee: invitee@docker.com + status: invited + invite: + id: e36eca69-4cc8-4f17-9845-ae8c2b832691 + inviter_username: moby + invitee: invitee@docker.com + org: docker + team: owners + created_at: '2021-10-28T18:30:19.520861Z' + - invitee: invitee2@docker.com + status: existing_org_member + - invitee: invitee3@docker.com + status: invalid_email_or_docker_id + error: + type: object + properties: + errinfo: + type: object + items: + type: string + detail: + type: string + message: + type: string scim_error: type: object properties: @@ -1909,7 +2173,180 @@ components: detail: type: string description: Details about why the request failed. - + user: + type: object + properties: + id: + type: string + example: 0ab70deb065a43fcacd55d48caa945d8 + description: The UUID trimmed + company: + type: string + example: Docker Inc + date_joined: + type: string + example: '2021-01-05T21:06:53.506400Z' + full_name: + type: string + example: Jon Snow + gravatar_email: + type: string + gravatar_url: + type: string + location: + type: string + profile_url: + type: string + type: + type: string + enum: + - User + - Org + example: User + username: + type: string + example: dockeruser + org_member: + allOf: + - $ref: '#/components/schemas/user' + properties: + email: + type: string + description: User's email address + example: example@docker.com + role: + type: string + description: User's role in the Organization + enum: + - Owner + - Member + - Invitee + example: Owner + groups: + type: array + description: Groups (Teams) that the user is member of + items: + type: string + example: + - developers + - owners + is_guest: + type: boolean + description: If the organization has verfied domains, members that have email addresses outside of those domains will be flagged as Guest member + example: false + primary_email: + type: string + description: User's email primary address + example: example@docker.com + deprecated: true + org_member_paginated: + type: object + properties: + count: + type: number + description: The total number of items that match with the search. + example: 120 + previous: + type: string + description: The URL or link for the previous page of items. + example: https://hub.docker.com/v2/some/resources/items?page=1&page_size=20 + next: + type: string + description: The URL or link for the next page of items. + example: https://hub.docker.com/v2/some/resources/items?page=3&page_size=20 + results: + type: array + description: List of accounts. + items: + $ref: '#/components/schemas/org_member' + org_group: + type: object + properties: + id: + type: number + example: 10 + description: Group ID + uuid: + type: string + description: UUID for the group + name: + type: string + example: mygroup + description: Name of the group + description: + type: string + example: Groups description + description: Description of the group + member_count: + type: number + example: 10 + description: Member count of the group + group_member: + type: object + properties: + id: + type: string + example: 0ab70deb065a43fcacd55d48caa945d8 + description: The UUID trimmed + company: + type: string + example: Docker Inc + date_joined: + type: string + example: '2021-01-05T21:06:53.506400Z' + full_name: + type: string + example: John Snow + gravatar_email: + type: string + gravatar_url: + type: string + location: + type: string + profile_url: + type: string + type: + type: string + enum: + - User + - Org + example: User + username: + type: string + example: dockeruser + email: + type: string + example: dockeruser@docker.com + email_address: + type: object + properties: + id: + type: number + user_id: + type: number + email: + type: string + example: dockeruser@docker.com + verified: + type: boolean + primary: + type: boolean + legacy_email_address: + allOf: + - $ref: '#/components/schemas/email_address' + - type: object + properties: + user: + type: string + example: dockeruser + email_with_username: + allOf: + - $ref: '#/components/schemas/email_address' + - type: object + properties: + username: + type: string + example: dockeruser scim_service_provider_config: type: object properties: @@ -1917,10 +2354,11 @@ components: type: array items: type: string - example: [ "urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig" ] + example: + - urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig documentationUri: type: string - example: "" + example: '' patch: properties: supported: @@ -1974,11 +2412,10 @@ components: example: The OAuth 2.0 Bearer Token Authentication scheme. OAuth enables clients to access protected resources by obtaining an access token, which is defined in RFC 6750 as "a string representing an access authorization issued to the client", rather than using the resource owner's credentials directly. specUri: type: string - example: "http://tools.ietf.org/html/rfc6750" + example: http://tools.ietf.org/html/rfc6750 type: type: string example: oauthbearertoken - scim_resource_type: type: object properties: @@ -1986,7 +2423,8 @@ components: type: array items: type: string - example: "urn:ietf:params:scim:schemas:core:2.0:ResourceType" + example: + - urn:ietf:params:scim:schemas:core:2.0:ResourceType id: type: string example: User @@ -1998,57 +2436,10 @@ components: example: User endpoint: type: string - example: "/Users" + example: /Users schema: type: string - example: "urn:ietf:params:scim:schemas:core:2.0:User" - - scim_schema_attribute: - type: object - properties: - name: - type: string - example: userName - type: - enum: - - string - - boolean - - complex - type: string - example: string - multiValued: - type: boolean - example: false - description: - type: string - example: Unique identifier for the User, typically used by the user to directly authenticate to the service provider. Each User MUST include a non-empty userName value. This identifier MUST be unique across the service provider's entire set of Users. - required: - type: boolean - example: true - caseExact: - type: boolean - example: false - mutability: - type: string - example: readWrite - returned: - type: string - example: default - uniqueness: - type: string - example: server - - - scim_schema_parent_attribute: - allOf: - - $ref: "#/components/schemas/scim_schema_attribute" - - type: object - properties: - subAttributes: - type: array - items: - $ref: "#/components/schemas/scim_schema_attribute" - + example: urn:ietf:params:scim:schemas:core:2.0:User scim_schema: type: object properties: @@ -2056,7 +2447,8 @@ components: type: array items: type: string - example: [ "urn:ietf:params:scim:schemas:core:2.0:Schema" ] + example: + - urn:ietf:params:scim:schemas:core:2.0:Schema id: type: string example: urn:ietf:params:scim:schemas:core:2.0:User @@ -2068,10 +2460,9 @@ components: example: User Account attributes: type: array - example: [ ] + example: [] items: - $ref: "#/components/schemas/scim_schema_parent_attribute" - + $ref: '#/components/schemas/scim_schema_parent_attribute' scim_email: type: object properties: @@ -2084,22 +2475,19 @@ components: primary: type: boolean example: true - scim_group: type: object properties: value: type: string - example: "nightswatch" + example: nightswatch display: type: string - example: "nightswatch" - + example: nightswatch scim_user_username: type: string description: The user's email address. This must be reachable via email. example: jon.snow@docker.com - scim_user_name: type: object properties: @@ -2109,48 +2497,44 @@ components: familyName: type: string example: Snow - scim_user_display_name: type: string description: The username in Docker. Also known as the "Docker ID". example: jonsnow - scim_user_schemas: type: array items: type: string - example: "urn:ietf:params:scim:schemas:core:2.0:User" + example: urn:ietf:params:scim:schemas:core:2.0:User minItems: 1 - scim_user_id: type: string example: d80f7c79-7730-49d8-9a41-7c42fb622d9c description: The unique identifier for the user. A v4 UUID. - scim_user: type: object properties: schemas: - $ref: "#/components/schemas/scim_user_schemas" + $ref: '#/components/schemas/scim_user_schemas' id: - $ref: "#/components/schemas/scim_user_id" + $ref: '#/components/schemas/scim_user_id' userName: - $ref: "#/components/schemas/scim_user_username" + $ref: '#/components/schemas/scim_user_username' name: - $ref: "#/components/schemas/scim_user_name" + $ref: '#/components/schemas/scim_user_name' displayName: - $ref: "#/components/schemas/scim_user_display_name" + $ref: '#/components/schemas/scim_user_display_name' active: type: boolean example: true emails: type: array items: - $ref: "#/components/schemas/scim_email" + $ref: '#/components/schemas/scim_email' groups: type: array items: - $ref: "#/components/schemas/scim_group" + $ref: '#/components/schemas/scim_group' meta: type: object properties: @@ -2162,31 +2546,13 @@ components: example: https://hub.docker.com/v2/scim/2.0/Users/d80f7c79-7730-49d8-9a41-7c42fb622d9c created: type: string - description: The creation date for the user as a RFC3339 formatted - string. - example: 2022-05-20T00:54:18Z + description: The creation date for the user as a RFC3339 formatted string. + example: '2022-05-20T00:54:18Z' lastModified: type: string - description: The date the user was last modified as a RFC3339 - formatted string. - example: 2022-05-20T00:54:18Z - + description: The date the user was last modified as a RFC3339 formatted string. + example: '2022-05-20T00:54:18Z' parameters: - scim_attributes: - in: query - name: attributes - schema: - type: string - description: Comma delimited list of attributes to limit to in the - response. - example: userName,displayName - scim_user_id: - name: id - in: path - schema: - type: string - description: The user ID. - example: "d80f7c79-7730-49d8-9a41-7c42fb622d9c" namespace: in: path name: namespace @@ -2205,22 +2571,132 @@ components: required: true schema: type: string + org_name: + in: path + name: org_name + description: Name of the organization (namespace). + schema: + type: string + example: myorganization + required: true + group_name: + in: path + name: group_name + description: Name of the group (team) in the organization. + schema: + type: string + example: developers + required: true + username: + in: path + name: username + description: Username, identifier for the user (namespace, DockerID). + schema: + type: string + example: jonsnow + required: true page: in: query name: page - required: false + description: Page number (starts on 1). schema: type: integer - description: "Page number to get. Defaults to 1." page_size: in: query name: page_size - required: false + description: Number of items (rows) per page. schema: type: integer - description: "Number of items to get per page. Defaults to 10. Max of 100." - + invites: + in: query + name: invites + description: Include invites in the response. + schema: + type: boolean + search: + in: query + name: search + schema: + type: integer + description: Search term. + scim_attributes: + in: query + name: attributes + schema: + type: string + description: Comma delimited list of attributes to limit to in the response. + example: userName,displayName + scim_user_id: + name: id + in: path + schema: + type: string + description: The user ID. + example: d80f7c79-7730-49d8-9a41-7c42fb622d9c + required: true + type: + in: query + name: type + schema: + type: string + enum: + - all + - invitee + - member + example: all + role: + in: query + name: role + schema: + type: string + enum: + - owner + - editor + - member + example: owner + bulk_invite: + in: header + name: X-Analytics-Client-Feature + description: Optional string that indicates the feature used to submit the bulk invites (e.g.'file', 'web') + schema: + type: string requestBodies: + bulk_invite_request: + required: true + content: + application/json: + schema: + type: object + required: + - org + - invitees + properties: + org: + type: string + description: organization name + example: docker + team: + type: string + description: team name + example: owners + role: + type: string + description: role for invitees + example: member + invitees: + type: array + description: list of invitees emails or Docker Ids + items: + type: string + description: invitee email or Docker ID + example: + - invitee1DockerId + - invitee2@docker.com + - invitee3@docker.com + dry_run: + type: boolean + description: Optional, run through validation but don't actually change data. + example: true scim_create_user_request: required: true content: @@ -2232,12 +2708,11 @@ components: - userName properties: schemas: - $ref: "#/components/schemas/scim_user_schemas" + $ref: '#/components/schemas/scim_user_schemas' userName: - $ref: "#/components/schemas/scim_user_username" + $ref: '#/components/schemas/scim_user_username' name: - $ref: "#/components/schemas/scim_user_name" - + $ref: '#/components/schemas/scim_user_name' scim_update_user_request: required: true content: @@ -2248,15 +2723,41 @@ components: - schemas properties: schemas: - $ref: "#/components/schemas/scim_user_schemas" + $ref: '#/components/schemas/scim_user_schemas' name: allOf: - - $ref: "#/components/schemas/scim_user_name" - - description: If this is omitted from the request, the - update will skip the update on it. We will only ever - change the name, but not clear it. + - $ref: '#/components/schemas/scim_user_name' + - description: If this is omitted from the request, the update will skip the update on it. We will only ever change the name, but not clear it. enabled: type: boolean default: false - description: If this is omitted from the request, it will - default to false resulting in a deactivated user. + description: If this is omitted from the request, it will default to false resulting in a deactivated user. + add_member_to_org_group: + required: true + content: + application/json: + schema: + type: object + required: + - member + properties: + member: + type: string + example: jonsnow +x-tagGroups: + - name: General + tags: + - resources + - rate-limiting + - name: API + tags: + - authentication + - access-tokens + - images + - audit-logs + - org-settings + - repositories + - scim + - orgs + - groups + - invites diff --git a/content/reference/cli/docker/desktop/_index.md b/content/reference/cli/docker/desktop/_index.md new file mode 100644 index 00000000000..be7ff711b12 --- /dev/null +++ b/content/reference/cli/docker/desktop/_index.md @@ -0,0 +1,10 @@ +--- +datafolder: desktop-cli +datafile: docker_desktop +title: docker desktop (Beta) +layout: cli +--- + +{{% experimental title="Beta" %}} +Docker Desktop CLI is currently in [Beta](/manuals/release-lifecycle.md#beta). +{{% /experimental %}} \ No newline at end of file diff --git a/content/reference/cli/docker/desktop/engine/_index.md b/content/reference/cli/docker/desktop/engine/_index.md new file mode 100644 index 00000000000..97950535974 --- /dev/null +++ b/content/reference/cli/docker/desktop/engine/_index.md @@ -0,0 +1,6 @@ +--- +datafolder: desktop-cli +datafile: docker_desktop_engine +title: docker desktop engine +layout: cli +--- \ No newline at end of file diff --git a/content/reference/cli/docker/desktop/engine/ls.md b/content/reference/cli/docker/desktop/engine/ls.md new file mode 100644 index 00000000000..a8499b1385e --- /dev/null +++ b/content/reference/cli/docker/desktop/engine/ls.md @@ -0,0 +1,6 @@ +--- +datafolder: desktop-cli +datafile: docker_desktop_engine_ls +title: docker desktop engine ls +layout: cli +--- \ No newline at end of file diff --git a/content/reference/cli/docker/desktop/engine/use.md b/content/reference/cli/docker/desktop/engine/use.md new file mode 100644 index 00000000000..56f58a96655 --- /dev/null +++ b/content/reference/cli/docker/desktop/engine/use.md @@ -0,0 +1,6 @@ +--- +datafolder: desktop-cli +datafile: docker_desktop_engine_use +title: docker desktop engine use +layout: cli +--- \ No newline at end of file diff --git a/content/reference/cli/docker/desktop/restart.md b/content/reference/cli/docker/desktop/restart.md new file mode 100644 index 00000000000..75ef78eeb49 --- /dev/null +++ b/content/reference/cli/docker/desktop/restart.md @@ -0,0 +1,6 @@ +--- +datafolder: desktop-cli +datafile: docker_desktop_restart +title: docker desktop restart +layout: cli +--- \ No newline at end of file diff --git a/content/reference/cli/docker/desktop/start.md b/content/reference/cli/docker/desktop/start.md new file mode 100644 index 00000000000..e9eccd116e2 --- /dev/null +++ b/content/reference/cli/docker/desktop/start.md @@ -0,0 +1,10 @@ +--- +datafolder: desktop-cli +datafile: docker_desktop_start +title: docker desktop start +layout: cli +--- + +> [!NOTE] +> +> `docker desktop start` doesn't work when executed via SSH on Windows due to a limitation in how WinCred stores credentials securely. diff --git a/content/reference/cli/docker/desktop/status.md b/content/reference/cli/docker/desktop/status.md new file mode 100644 index 00000000000..b0b868c579b --- /dev/null +++ b/content/reference/cli/docker/desktop/status.md @@ -0,0 +1,6 @@ +--- +datafolder: desktop-cli +datafile: docker_desktop_status +title: docker desktop status +layout: cli +--- \ No newline at end of file diff --git a/content/reference/cli/docker/desktop/stop.md b/content/reference/cli/docker/desktop/stop.md new file mode 100644 index 00000000000..203bdef5669 --- /dev/null +++ b/content/reference/cli/docker/desktop/stop.md @@ -0,0 +1,6 @@ +--- +datafolder: desktop-cli +datafile: docker_desktop_stop +title: docker desktop stop +layout: cli +--- \ No newline at end of file diff --git a/content/reference/compose-file/build.md b/content/reference/compose-file/build.md index b5640f080a7..636ab89ec23 100644 --- a/content/reference/compose-file/build.md +++ b/content/reference/compose-file/build.md @@ -51,7 +51,7 @@ When used to build service images from source, the Compose file creates three Do * `example/webapp`: A Docker image is built using `webapp` sub-directory, within the Compose file's parent folder, as the Docker build context. Lack of a `Dockerfile` within this folder throws an error. * `example/database`: A Docker image is built using `backend` sub-directory within the Compose file parent folder. `backend.Dockerfile` file is used to define build steps, this file is searched relative to the context path, which means `..` resolves to the Compose file's parent folder, so `backend.Dockerfile` is a sibling file. -* A Docker image is built using the `custom` directory with the user's HOME as the Docker context. Compose displays a warning about the non-portable path used to build image. +* A Docker image is built using the `custom` directory with the user's `$HOME` as the Docker context. Compose displays a warning about the non-portable path used to build image. On push, both `example/webapp` and `example/database` Docker images are pushed to the default registry. The `custom` service image is skipped as no `image` attribute is set and Compose displays a warning about this missing attribute. @@ -81,7 +81,7 @@ The second part represents a subdirectory inside the repository that is used as Alternatively `build` can be an object with fields defined as follows: -### additional_contexts +### `additional_contexts` {{< introduced compose 2.17.0 "/manuals/compose/releases/release-notes.md#2170" >}} @@ -118,9 +118,9 @@ the unused contexts. Illustrative examples of how this is used in Buildx can be found [here](https://github.com/docker/buildx/blob/master/docs/reference/buildx_build.md#-additional-build-contexts---build-context). -### args +### `args` -`args` define build arguments, i.e. Dockerfile `ARG` values. +`args` define build arguments, that is Dockerfile `ARG` values. Using the following Dockerfile as an example: @@ -146,16 +146,16 @@ build: ``` Values can be omitted when specifying a build argument, in which case its value at build time must be obtained by user interaction, -otherwise the build arg won't be set when building the Docker image. +otherwise the build argument won't be set when building the Docker image. ```yml args: - GIT_COMMIT ``` -### context +### `context` -`context` defines either a path to a directory containing a Dockerfile, or a URL to a git repository. +`context` defines either a path to a directory containing a Dockerfile, or a URL to a Git repository. When the value supplied is a relative path, it is interpreted as relative to the project directory. Compose warns you about the absolute path used to define the build context as those prevent the Compose file @@ -174,7 +174,7 @@ services: If not set explicitly, `context` defaults to project directory (`.`). -### cache_from +### `cache_from` `cache_from` defines a list of sources the image builder should use for cache resolution. @@ -196,7 +196,7 @@ build: Unsupported caches are ignored and don't prevent you from building images. -### cache_to +### `cache_to` `cache_to` defines a list of export locations to be used to share build cache with future builds. @@ -212,7 +212,7 @@ Cache target is defined using the same `type=TYPE[,KEY=VALUE]` syntax defined by Unsupported caches are ignored and don't prevent you from building images. -### dockerfile +### `dockerfile` `dockerfile` sets an alternate Dockerfile. A relative path is resolved from the build context. Compose warns you about the absolute path used to define the Dockerfile as it prevents Compose files @@ -227,7 +227,7 @@ build: dockerfile: webapp.Dockerfile ``` -### dockerfile_inline +### `dockerfile_inline` {{< introduced compose 2.17.0 "/manuals/compose/releases/release-notes.md#2170" >}} @@ -244,7 +244,7 @@ build: RUN some command ``` -### entitlements +### `entitlements` {{< introduced compose 2.27.1 "/manuals/compose/releases/release-notes.md#2271" >}} @@ -256,9 +256,9 @@ build: - security.insecure ``` -### extra_hosts +### `extra_hosts` -`extra_hosts` adds hostname mappings at build-time. Use the same syntax as [extra_hosts](services.md#extra_hosts). +`extra_hosts` adds hostname mappings at build-time. Use the same syntax as [`extra_hosts`](services.md#extra_hosts). ```yml extra_hosts: @@ -290,12 +290,12 @@ configuration, which means for Linux `/etc/hosts` will get extra lines: ::1 myhostv6 ``` -### isolation +### `isolation` `isolation` specifies a build’s container isolation technology. Like [isolation](services.md#isolation), supported values are platform specific. -### labels +### `labels` `labels` add metadata to the resulting image. `labels` can be set either as an array or a map. @@ -319,7 +319,7 @@ build: - "com.example.label-with-empty-value" ``` -### network +### `network` Set the network containers connect to for the `RUN` instructions during build. @@ -343,13 +343,13 @@ build: network: none ``` -### no_cache +### `no_cache` `no_cache` disables image builder cache and enforces a full rebuild from source for all image layers. This only applies to layers declared in the Dockerfile, referenced images can be retrieved from local image store whenever tag has been updated on registry (see [pull](#pull)). -### platforms +### `platforms` `platforms` defines a list of target [platforms](services.md#platform). @@ -368,8 +368,8 @@ When the `platforms` attribute is defined, Compose includes the service's platform, otherwise users won't be able to run images they built. Composes reports an error in the following cases: -* When the list contains multiple platforms but the implementation is incapable of storing multi-platform images. -* When the list contains an unsupported platform. +- When the list contains multiple platforms but the implementation is incapable of storing multi-platform images. +- When the list contains an unsupported platform. ```yml build: @@ -378,7 +378,7 @@ Composes reports an error in the following cases: - "linux/amd64" - "unsupported/unsupported" ``` -* When the list is non-empty and does not contain the service's platform +- When the list is non-empty and does not contain the service's platform. ```yml services: @@ -390,7 +390,7 @@ Composes reports an error in the following cases: - "linux/arm64" ``` -### privileged +### `privileged` {{< introduced compose 2.15.0 "/manuals/compose/releases/release-notes.md#2" >}} @@ -402,12 +402,12 @@ build: privileged: true ``` -### pull +### `pull` `pull` requires the image builder to pull referenced images (`FROM` Dockerfile directive), even if those are already available in the local image store. -### secrets +### `secrets` `secrets` grants access to sensitive data defined by [secrets](services.md#secrets) on a per-service build basis. Two different syntax variants are supported: the short syntax and the long syntax. @@ -446,8 +446,8 @@ the service's containers. - `source`: The name of the secret as it exists on the platform. - `target`: The name of the file to be mounted in `/run/secrets/` in the service's task containers. Defaults to `source` if not specified. -- `uid` and `gid`: The numeric UID or GID that owns the file within - `/run/secrets/` in the service's task containers. Default value is USER running container. +- `uid` and `gid`: The numeric uid or gid that owns the file within + `/run/secrets/` in the service's task containers. Default value is `USER`. - `mode`: The [permissions](https://wintelguy.com/permissions-calc.pl) for the file to be mounted in `/run/secrets/` in the service's task containers, in octal notation. Default value is world-readable permissions (mode `0444`). @@ -478,7 +478,7 @@ Service builds may be granted access to multiple secrets. Long and short syntax same Compose file. Defining a secret in the top-level `secrets` must not imply granting any service build access to it. Such grant must be explicit within service specification as [secrets](services.md#secrets) service element. -### ssh +### `ssh` `ssh` defines SSH authentications that the image builder should use during image build (e.g., cloning private repository). @@ -515,7 +515,7 @@ For illustration, [SSH mounts](https://github.com/moby/buildkit/blob/master/fron RUN --mount=type=ssh,id=myproject git clone ... ``` -### shm_size +### `shm_size` `shm_size` sets the size of the shared memory (`/dev/shm` partition on Linux) allocated for building Docker images. Specify as an integer value representing the number of bytes or as a string expressing a [byte value](extension.md#specifying-byte-values). @@ -532,7 +532,7 @@ build: shm_size: 10000000 ``` -### tags +### `tags` `tags` defines a list of tag mappings that must be associated to the build image. This list comes in addition to the `image` [property defined in the service section](services.md#image) @@ -543,7 +543,7 @@ tags: - "registry/username/myrepos:my-other-tag" ``` -### target +### `target` `target` defines the stage to build as defined inside a multi-stage `Dockerfile`. @@ -553,11 +553,11 @@ build: target: prod ``` -### ulimits +### `ulimits` {{< introduced compose 2.23.1 "/manuals/compose/releases/release-notes.md#2231" >}} -`ulimits` overrides the default ulimits for a container. It's specified either as an integer for a single limit +`ulimits` overrides the default `ulimits` for a container. It's specified either as an integer for a single limit or as mapping for soft/hard limits. ```yml @@ -571,5 +571,3 @@ services: soft: 20000 hard: 40000 ``` - - diff --git a/content/reference/compose-file/deploy.md b/content/reference/compose-file/deploy.md index d1bb19f57a2..c5a24f4d1b8 100644 --- a/content/reference/compose-file/deploy.md +++ b/content/reference/compose-file/deploy.md @@ -11,7 +11,7 @@ weight: 140 ## Attributes -### endpoint_mode +### `endpoint_mode` `endpoint_mode` specifies a service discovery method for external clients connecting to a service. The Compose Deploy Specification defines two canonical values: @@ -34,7 +34,7 @@ services: endpoint_mode: vip ``` -### labels +### `labels` `labels` specifies metadata for the service. These labels are only set on the service and not on any containers for the service. This assumes the platform has some native concept of "service" that can match the Compose application model. @@ -48,7 +48,7 @@ services: com.example.description: "This label will appear on the web service" ``` -### mode +### `mode` `mode` defines the replication model used to run a service or job. Options include: @@ -86,11 +86,11 @@ services: For more detailed information about job options and behavior, see the [Docker CLI documentation](/reference/cli/docker/service/create.md#running-as-a-job) -### placement +### `placement` `placement` specifies constraints and preferences for the platform to select a physical node to run service containers. -#### constraints +#### `constraints` `constraints` defines a required property the platform's node must fulfill to run the service container. For a further example, see the [CLI reference docs](/reference/cli/docker/service/create.md#constraint). @@ -101,7 +101,7 @@ deploy: - disktype=ssd ``` -#### preferences +#### `preferences` `preferences` defines a strategy (currently `spread` is the only supported strategy) to spread tasks evenly over the values of the datacenter node label. For a further example, see the [CLI reference docs](/reference/cli/docker/service/create.md#placement-pref) @@ -113,7 +113,7 @@ deploy: - spread: node.labels.zone ``` -### replicas +### `replicas` If the service is `replicated` (which is the default), `replicas` specifies the number of containers that should be running at any given time. @@ -127,7 +127,7 @@ services: replicas: 6 ``` -### resources +### `resources` `resources` configures physical resource constraints for container to run on platform. Those constraints can be configured as: @@ -150,25 +150,25 @@ services: memory: 20M ``` -#### cpus +#### `cpus` `cpus` configures a limit or reservation for how much of the available CPU resources, as number of cores, a container can use. -#### memory +#### `memory` `memory` configures a limit or reservation on the amount of memory a container can allocate, set as a string expressing a [byte value](extension.md#specifying-byte-values). -#### pids +#### `pids` `pids` tunes a container’s PIDs limit, set as an integer. -#### devices +#### `devices` `devices` configures reservations of the devices a container can use. It contains a list of reservations, each set as an object with the following parameters: `capabilities`, `driver`, `count`, `device_ids` and `options`. Devices are reserved using a list of capabilities, making `capabilities` the only required field. A device must satisfy all the requested capabilities for a successful reservation. -##### capabilities +##### `capabilities` `capabilities` are set as a list of strings, expressing both generic and driver specific capabilities. The following generic capabilities are recognized today: @@ -177,7 +177,7 @@ The following generic capabilities are recognized today: - `tpu`: AI accelerator To avoid name clashes, driver specific capabilities must be prefixed with the driver name. -For example, reserving an nVidia CUDA-enabled accelerator might look like this: +For example, reserving an NVIDIA CUDA-enabled accelerator might look like this: ```yml deploy: @@ -187,7 +187,7 @@ deploy: - capabilities: ["nvidia-compute"] ``` -##### driver +##### `driver` A different driver for the reserved device(s) can be requested using `driver` field. The value is specified as a string. @@ -200,7 +200,7 @@ deploy: driver: nvidia ``` -##### count +##### `count` If `count` is set to `all` or not specified, Compose reserves all devices that satisfy the requested capabilities. Otherwise, Compose reserves at least the number of devices specified. The value is specified as an integer. @@ -215,7 +215,7 @@ deploy: `count` and `device_ids` fields are exclusive. Compose returns an error if both are specified. -##### device_ids +##### `device_ids` If `device_ids` is set, Compose reserves devices with the specified IDs provided they satisfy the requested capabilities. The value is specified as a list of strings. @@ -230,7 +230,7 @@ deploy: `count` and `device_ids` fields are exclusive. Compose returns an error if both are specified. -##### options +##### `options` Driver specific options can be set with `options` as key-value pairs. @@ -245,7 +245,7 @@ deploy: virtualization: false ``` -### restart_policy +### `restart_policy` `restart_policy` configures if and how to restart containers when they exit. If `restart_policy` is not set, Compose considers the `restart` field set by the service configuration. @@ -269,7 +269,7 @@ deploy: window: 120s ``` -### rollback_config +### `rollback_config` `rollback_config` configures how the service should be rollbacked in case of a failing update. @@ -281,7 +281,7 @@ deploy: - `order`: Order of operations during rollbacks. One of `stop-first` (old task is stopped before starting new one), or `start-first` (new task is started first, and the running tasks briefly overlap) (default `stop-first`). -### update_config +### `update_config` `update_config` configures how the service should be updated. Useful for configuring rolling updates. diff --git a/content/reference/compose-file/develop.md b/content/reference/compose-file/develop.md index 1e48a00ff29..7bc771f103a 100644 --- a/content/reference/compose-file/develop.md +++ b/content/reference/compose-file/develop.md @@ -7,14 +7,13 @@ aliases: weight: 150 --- -> **Note:** +> [!NOTE] > > Develop is an optional part of the Compose Specification. It is available with Docker Compose version 2.22.0 and later. {{< include "compose/develop.md" >}} -This page defines how Compose behaves to efficiently assist you and defines the development constraints and workflows set by Compose. Only a subset of -Compose file services may require a `develop` subsection. +This page defines how Compose behaves to efficiently assist you and defines the development constraints and workflows set by Compose. Only a subset of Compose file services may require a `develop` subsection. ## Illustrative example @@ -44,43 +43,70 @@ services: ## Attributes + + The `develop` subsection defines configuration options that are applied by Compose to assist you during development of a service with optimized workflows. -### watch +### `watch` The `watch` attribute defines a list of rules that control automatic service updates based on local file changes. `watch` is a sequence, each individual item in the sequence defines a rule to be applied by Compose to monitor source code for changes. For more information, see [Use Compose Watch](/manuals/compose/how-tos/file-watch.md). -#### action +#### `action` `action` defines the action to take when changes are detected. If `action` is set to: -- `rebuild`, Compose rebuilds the service image based on the `build` section and recreates the service with the updated image. -- `sync`, Compose keeps the existing service container(s) running, but synchronizes source files with container content according to the `target` attribute. -- `sync+restart`, Compose synchronizes source files with container content according to the `target` attribute, and then restarts the container. +- `rebuild`: Compose rebuilds the service image based on the `build` section and recreates the service with the updated image. +- `restart`: Compose restarts the service container. Available with Docker Compose version 2.32.0 and later. +- `sync`: Compose keeps the existing service container(s) running, but synchronizes source files with container content according to the `target` attribute. +- `sync+restart`: Compose synchronizes source files with container content according to the `target` attribute, and then restarts the container. Available with Docker Compose version 2.23.0 and later. +- `sync+exec`: Compose synchronizes source files with container content according to the `target` attribute, and then executes a command inside the container. Available with Docker Compose version 2.32.0 and later. + +#### `exec` + +{{< introduced compose 2.23.2 "/manuals/compose/releases/release-notes.md#2232" >}} -> `sync+restart` attribute is available with Docker Compose version 2.23.0 and later. +`exec` is only relevant when `action` is set to `sync+exec`. Like [service hooks](services.md#post_start), `exec` is used to define the command to be run inside the container once it has started. + +- `command`: Specifies the command to run once the container starts. This attribute is required, and you can choose to use either the shell form or the exec form. +- `user`: The user to run the command. If not set, the command is run with the same user as the main service command. +- `privileged`: Lets the command run with privileged access. +- `working_dir`: The working directory in which to run the command. If not set, it is run in the same working directory as the main service command. +- `environment`: Sets the environment variables to run the command. While the command inherits the environment variables defined for the service’s main command, this section lets you add new variables or override existing ones. + +```yaml +services: + frontend: + image: ... + develop: + watch: + # sync content then run command to reload service without interruption + - path: ./etc/config + action: sync+exec + target: /etc/config/ + exec: + command: app reload +``` -#### ignore +#### `ignore` The `ignore` attribute can be used to define a list of patterns for paths to be ignored. Any updated file that matches a pattern, or belongs to a folder that matches a pattern, won't trigger services to be re-created. The syntax is the same as `.dockerignore` file: -- `*` matches 0 or more characters in a file name. -- `?` matches a single character in file name. +- `*` matches 0 or more characters in a filename. +- `?` matches a single character in filename. - `*/*` matches two nested folders with arbitrary names - `**` matches an arbitrary number of nested folders If the build context includes a `.dockerignore` file, the patterns in this file is loaded as implicit content for the `ignores` file, and values set in the Compose model are appended. -#### path +#### `path` `path` attribute defines the path to source code (relative to the project directory) to monitor for changes. Updates to any file inside the path, which doesn't match any `ignore` rule, triggers the configured action. -#### target +#### `target` -`target` attribute only applies when `action` is configured for `sync`. Files within `path` with changes are synchronized -with container filesystem, so that the latter is always running with up-to-date content. +`target` attribute only applies when `action` is configured for `sync`. Files within `path` that have changes are synchronized with the container's filesystem, so that the latter is always running with up-to-date content. diff --git a/content/reference/compose-file/include.md b/content/reference/compose-file/include.md index 4e763859709..84591669903 100644 --- a/content/reference/compose-file/include.md +++ b/content/reference/compose-file/include.md @@ -61,7 +61,7 @@ services: - included-service # defined by another_domain ``` -In the above example, both `../commons/compose.yaml` and +In the previous example, both `../commons/compose.yaml` and `../another_domain/compose.yaml` are loaded as individual Compose projects. Relative paths in Compose files being referred by `include` are resolved relative to their own Compose file path, not based on the local project's directory. Variables are interpolated using values set in the optional @@ -78,12 +78,15 @@ include: env_file: ../another/.env ``` -### path +### `path` `path` is required and defines the location of the Compose file(s) to be parsed and included into the -local Compose model. `path` can be set to either a string when a single Compose file is involved, -or to a list of strings when multiple Compose files need to be [merged together](merge.md) to -define the Compose model to be included in the local application. +local Compose model. + +`path` can be set as: + +- A string: When using a single Compose file. +- A list of strings: When multiple Compose files need to be [merged together](merge.md) to define the Compose model for the local application. ```yaml include: @@ -92,12 +95,12 @@ include: - ./commons-override.yaml ``` -### project_directory +### `project_directory` `project_directory` defines a base path to resolve relative paths set in the Compose file. It defaults to the directory of the included Compose file. -### env_file +### `env_file` `env_file` defines an environment file(s) to use to define default values when interpolating variables in the Compose file being parsed. It defaults to `.env` file in the `project_directory` for the Compose diff --git a/content/reference/compose-file/networks.md b/content/reference/compose-file/networks.md index 73c4dff4422..4812272295d 100644 --- a/content/reference/compose-file/networks.md +++ b/content/reference/compose-file/networks.md @@ -64,7 +64,7 @@ The advanced example shows a Compose file which defines two custom networks. The ## Attributes -### driver +### `driver` `driver` specifies which driver should be used for this network. Compose returns an error if the driver is not available on the platform. @@ -77,7 +77,7 @@ networks: For more information on drivers and available options, see [Network drivers](/manuals/engine/network/drivers/_index.md). -### driver_opts +### `driver_opts` `driver_opts` specifies a list of options as key-value pairs to pass to the driver. These options are driver-dependent. @@ -92,7 +92,7 @@ networks: Consult the [network drivers documentation](/manuals/engine/network/_index.md) for more information. -### attachable +### `attachable` If `attachable` is set to `true`, then standalone containers should be able to attach to this network, in addition to services. If a standalone container attaches to the network, it can communicate with services and other standalone containers @@ -105,18 +105,18 @@ networks: attachable: true ``` -### enable_ipv6 +### `enable_ipv6` `enable_ipv6` enables IPv6 networking. For an example, see step four of [Create an IPv6 network](/manuals/engine/daemon/ipv6.md). -### external +### `external` If set to `true`: - `external` specifies that this network’s lifecycle is maintained outside of that of the application. Compose doesn't attempt to create these networks, and returns an error if one doesn't exist. - All other attributes apart from name are irrelevant. If Compose detects any other attribute, it rejects the Compose file as invalid. -In the example below, `proxy` is the gateway to the outside world. Instead of attempting to create a network, Compose +In the following example, `proxy` is the gateway to the outside world. Instead of attempting to create a network, Compose queries the platform for an existing network simply called `outside` and connects the `proxy` service's containers to it. @@ -137,7 +137,7 @@ networks: external: true ``` -### ipam +### `ipam` `ipam` specifies a custom IPAM configuration. This is an object with several properties, each of which is optional: @@ -167,12 +167,12 @@ networks: baz: "0" ``` -### internal +### `internal` -By default, Compose provides external connectivity to networks. `internal`, when set to `true`, allows you to +By default, Compose provides external connectivity to networks. `internal`, when set to `true`, lets you create an externally isolated network. -### labels +### `labels` Add metadata to containers using `labels`. You can use either an array or a dictionary. @@ -198,7 +198,7 @@ networks: Compose sets `com.docker.compose.project` and `com.docker.compose.network` labels. -### name +### `name` `name` sets a custom name for the network. The name field can be used to reference networks which contain special characters. The name is used as is and is not scoped with the project name. diff --git a/content/reference/compose-file/secrets.md b/content/reference/compose-file/secrets.md index 80afcfff5e4..5fe118b77b2 100644 --- a/content/reference/compose-file/secrets.md +++ b/content/reference/compose-file/secrets.md @@ -15,7 +15,7 @@ The top-level `secrets` declaration defines or references sensitive data that is application. The source of the secret is either `file` or `environment`. - `file`: The secret is created with the contents of the file at the specified path. -- `environment`: The secret is created with the value of an environment variable. +- `environment`: The secret is created with the value of an environment variable on the host. ## Example 1 diff --git a/content/reference/compose-file/services.md b/content/reference/compose-file/services.md index 90999a93bf9..b3bac368fec 100644 --- a/content/reference/compose-file/services.md +++ b/content/reference/compose-file/services.md @@ -10,15 +10,15 @@ weight: 20 {{< include "compose/services.md" >}} A Compose file must declare a `services` top-level element as a map whose keys are string representations of service names, -and whose values are service definitions. A service definition contains the configuration that is applied to each +and whose values are service definitions. A service definition contains the configuration that is applied to each service container. Each service may also include a `build` section, which defines how to create the Docker image for the service. -Compose supports building docker images using this service definition. If not used, the `build` section is ignored and the Compose file is still considered valid. Build support is an optional aspect of the Compose Specification, and is +Compose supports building Docker images using this service definition. If not used, the `build` section is ignored and the Compose file is still considered valid. Build support is an optional aspect of the Compose Specification, and is described in detail in the [Compose Build Specification](build.md) documentation. Each service defines runtime constraints and requirements to run its containers. The `deploy` section groups -these constraints and allows the platform to adjust the deployment strategy to best match containers' needs with +these constraints and lets the platform adjust the deployment strategy to best match containers' needs with available resources. Deploy support is an optional aspect of the Compose Specification, and is described in detail in the [Compose Deploy Specification](deploy.md) documentation. If not implemented the `deploy` section is ignored and the Compose file is still considered valid. @@ -73,7 +73,9 @@ For more example Compose files, explore the [Awesome Compose samples](https://gi ## Attributes -### annotations + + +### `annotations` `annotations` defines annotations for the container. `annotations` can use either an array or a map. @@ -87,7 +89,7 @@ annotations: - com.example.foo=bar ``` -### attach +### `attach` {{< introduced compose 2.20.0 "/manuals/compose/releases/release-notes.md#2200" >}} @@ -96,13 +98,13 @@ until you explicitly request it to. The default service configuration is `attach: true`. -### build +### `build` `build` specifies the build configuration for creating a container image from source, as defined in the [Compose Build Specification](build.md). -### blkio_config +### `blkio_config` -`blkio_config` defines a set of configuration options to set block IO limits for a service. +`blkio_config` defines a set of configuration options to set block I/O limits for a service. ```yml services: @@ -127,7 +129,7 @@ services: rate: 30 ``` -#### device_read_bps, device_write_bps +#### `device_read_bps`, `device_write_bps` Set a limit in bytes per second for read / write operations on a given device. Each item in the list must have two keys: @@ -135,7 +137,7 @@ Each item in the list must have two keys: - `path`: Defines the symbolic path to the affected device. - `rate`: Either as an integer value representing the number of bytes or as a string expressing a byte value. -#### device_read_iops, device_write_iops +#### `device_read_iops`, `device_write_iops` Set a limit in operations per second for read / write operations on a given device. Each item in the list must have two keys: @@ -143,72 +145,72 @@ Each item in the list must have two keys: - `path`: Defines the symbolic path to the affected device. - `rate`: As an integer value representing the permitted number of operations per second. -#### weight +#### `weight` Modify the proportion of bandwidth allocated to a service relative to other services. Takes an integer value between 10 and 1000, with 500 being the default. -#### weight_device +#### `weight_device` Fine-tune bandwidth allocation by device. Each item in the list must have two keys: - `path`: Defines the symbolic path to the affected device. - `weight`: An integer value between 10 and 1000. -### cpu_count +### `cpu_count` `cpu_count` defines the number of usable CPUs for service container. -### cpu_percent +### `cpu_percent` `cpu_percent` defines the usable percentage of the available CPUs. -### cpu_shares +### `cpu_shares` `cpu_shares` defines, as integer value, a service container's relative CPU weight versus other containers. -### cpu_period +### `cpu_period` `cpu_period` configures CPU CFS (Completely Fair Scheduler) period when a platform is based on Linux kernel. -### cpu_quota +### `cpu_quota` `cpu_quota` configures CPU CFS (Completely Fair Scheduler) quota when a platform is based on Linux kernel. -### cpu_rt_runtime +### `cpu_rt_runtime` -`cpu_rt_runtime` configures CPU allocation parameters for platforms with support for realtime scheduler. It can be either +`cpu_rt_runtime` configures CPU allocation parameters for platforms with support for real-time scheduler. It can be either an integer value using microseconds as unit or a [duration](extension.md#specifying-durations). ```yml cpu_rt_runtime: '400ms' - cpu_rt_runtime: 95000` + cpu_rt_runtime: '95000' ``` -### cpu_rt_period +### `cpu_rt_period` -`cpu_rt_period` configures CPU allocation parameters for platforms with support for realtime scheduler. It can be either +`cpu_rt_period` configures CPU allocation parameters for platforms with support for real-time scheduler. It can be either an integer value using microseconds as unit or a [duration](extension.md#specifying-durations). ```yml cpu_rt_period: '1400us' - cpu_rt_period: 11000` + cpu_rt_period: '11000' ``` -### cpus +### `cpus` `cpus` define the number of (potentially virtual) CPUs to allocate to service containers. This is a fractional number. `0.000` means no limit. When set, `cpus` must be consistent with the `cpus` attribute in the [Deploy Specification](deploy.md#cpus). -### cpuset +### `cpuset` -`cpuset` defines the explicit CPUs in which to allow execution. Can be a range `0-3` or a list `0,1` +`cpuset` defines the explicit CPUs in which to permit execution. Can be a range `0-3` or a list `0,1` -### cap_add +### `cap_add` `cap_add` specifies additional container [capabilities](https://man7.org/linux/man-pages/man7/capabilities.7.html) as strings. @@ -218,7 +220,7 @@ cap_add: - ALL ``` -### cap_drop +### `cap_drop` `cap_drop` specifies container [capabilities](https://man7.org/linux/man-pages/man7/capabilities.7.html) to drop as strings. @@ -229,7 +231,7 @@ cap_drop: - SYS_ADMIN ``` -### cgroup +### `cgroup` {{< introduced compose 2.15.0 "/manuals/compose/releases/release-notes.md#2150" >}} @@ -239,7 +241,7 @@ select which cgroup namespace to use, if supported. - `host`: Runs the container in the Container runtime cgroup namespace. - `private`: Runs the container in its own private cgroup namespace. -### cgroup_parent +### `cgroup_parent` `cgroup_parent` specifies an optional parent [cgroup](https://man7.org/linux/man-pages/man7/cgroups.7.html) for the container. @@ -247,7 +249,7 @@ select which cgroup namespace to use, if supported. cgroup_parent: m-executor-abcd ``` -### command +### `command` `command` overrides the default command declared by the container image, for example by Dockerfile's `CMD`. @@ -263,12 +265,11 @@ command: [ "bundle", "exec", "thin", "-p", "3000" ] If the value is `null`, the default command from the image is used. -If the value is `[]` (empty list) or `''` (empty string), the default command declared by the image is ignored, -i.e. overridden to be empty. +If the value is `[]` (empty list) or `''` (empty string), the default command declared by the image is ignored, or in other words overridden to be empty. -### configs +### `configs` -Configs allow services to adapt their behaviour without the need to rebuild a Docker image. +`configs` let services adapt their behaviour without the need to rebuild a Docker image. Services can only access configs when explicitly granted by the `configs` attribute. Two different syntax variants are supported. Compose reports an error if `config` doesn't exist on the platform or isn't defined in the @@ -311,8 +312,8 @@ The long syntax provides more granularity in how the config is created within th - `source`: The name of the config as it exists in the platform. - `target`: The path and name of the file to be mounted in the service's task containers. Defaults to `/` if not specified. -- `uid` and `gid`: The numeric UID or GID that owns the mounted config file - within the service's task containers. Default value when not specified is USER running container. +- `uid` and `gid`: The numeric uid or gid that owns the mounted config file + within the service's task containers. Default value when not specified is `USER`. - `mode`: The [permissions](https://wintelguy.com/permissions-calc.pl) for the file that is mounted within the service's task containers, in octal notation. Default value is world-readable (`0444`). Writable bit must be ignored. The executable bit can be set. @@ -339,7 +340,7 @@ configs: external: true ``` -### container_name +### `container_name` `container_name` is a string that specifies a custom container name, rather than a name generated by default. @@ -352,7 +353,7 @@ Compose does not scale a service beyond one container if the Compose file specif `container_name` follows the regex format of `[a-zA-Z0-9][a-zA-Z0-9_.-]+` -### credential_spec +### `credential_spec` `credential_spec` configures the credential spec for a managed service account. @@ -397,7 +398,7 @@ configs: file: ./my-credential-spec.json| ``` -### depends_on +### `depends_on` {{< include "compose/services-depends-on.md" >}} @@ -442,9 +443,9 @@ expressed in the short form. after the container dies. Introduced in Docker Compose version [2.17.0](/manuals/compose/releases/release-notes.md#2170). - `condition`: Sets the condition under which dependency is considered satisfied - - `service_started`: An equivalent of the short syntax described above + - `service_started`: An equivalent of the short syntax described previously - `service_healthy`: Specifies that a dependency is expected to be "healthy" - (as indicated by [healthcheck](#healthcheck)) before starting a dependent + (as indicated by [`healthcheck`](#healthcheck)) before starting a dependent service. - `service_completed_successfully`: Specifies that a dependency is expected to run to successful completion before starting a dependent service. @@ -484,17 +485,17 @@ starting a dependent service. Compose guarantees dependency services marked with `service_healthy` are "healthy" before starting a dependent service. -### deploy +### `deploy` `deploy` specifies the configuration for the deployment and lifecycle of services, as defined [in the Compose Deploy Specification](deploy.md). -### develop +### `develop` {{< introduced compose 2.22.0 "/manuals/compose/releases/release-notes.md#2220" >}} `develop` specifies the development configuration for maintaining a container in sync with source, as defined in the [Development Section](develop.md). -### device_cgroup_rules +### `device_cgroup_rules` `device_cgroup_rules` defines a list of device cgroup rules for this container. The format is the same format the Linux kernel specifies in the [Control Groups @@ -506,7 +507,7 @@ device_cgroup_rules: - 'a 7:* rmw' ``` -### devices +### `devices` `devices` defines a list of device mappings for created containers in the form of `HOST_PATH:CONTAINER_PATH[:CGROUP_PERMISSIONS]`. @@ -517,7 +518,7 @@ devices: - "/dev/sda:/dev/xvda:rwm" ``` -### dns +### `dns` `dns` defines custom DNS servers to set on the container network interface configuration. It can be a single value or a list. @@ -531,7 +532,7 @@ dns: - 9.9.9.9 ``` -### dns_opt +### `dns_opt` `dns_opt` list custom DNS options to be passed to the container’s DNS resolver (`/etc/resolv.conf` file on Linux). @@ -541,7 +542,7 @@ dns_opt: - no-tld-query ``` -### dns_search +### `dns_search` `dns_search` defines custom DNS search domains to set on container network interface configuration. It can be a single value or a list. @@ -555,11 +556,11 @@ dns_search: - dc2.example.com ``` -### domainname +### `domainname` `domainname` declares a custom domain name to use for the service container. It must be a valid RFC 1123 hostname. -### driver_opts +### `driver_opts` {{< introduced compose 2.27.1 "/manuals/compose/releases/release-notes.md#2271" >}} @@ -577,7 +578,7 @@ services: Consult the [network drivers documentation](/manuals/engine/network/_index.md) for more information. -### entrypoint +### `entrypoint` `entrypoint` declares the default entrypoint for the service container. This overrides the `ENTRYPOINT` instruction from the service's Dockerfile. @@ -607,10 +608,9 @@ entrypoint: If the value is `null`, the default entrypoint from the image is used. -If the value is `[]` (empty list) or `''` (empty string), the default entrypoint declared by the image is ignored, -i.e. overridden to be empty. +If the value is `[]` (empty list) or `''` (empty string), the default entrypoint declared by the image is ignored, or in other words, overridden to be empty. -### env_file +### `env_file` {{< include "compose/services-env-file.md" >}} @@ -621,11 +621,11 @@ env_file: .env Relative paths are resolved from the Compose file's parent folder. As absolute paths prevent the Compose file from being portable, Compose warns you when such a path is used to set `env_file`. -Environment variables declared in the [environment](#environment) section override these values. This holds true even if those values are +Environment variables declared in the [`environment`](#environment) section override these values. This holds true even if those values are empty or undefined. `env_file` can also be a list. The files in the list are processed from the top down. For the same variable -specified in two env files, the value from the last file in the list stands. +specified in two environment files, the value from the last file in the list stands. ```yml env_file: @@ -636,7 +636,7 @@ env_file: List elements can also be declared as a mapping, which then lets you set additional attributes. -#### required +#### `required` {{< introduced compose 2.24.0 "/manuals/compose/releases/release-notes.md#2240" >}} @@ -650,11 +650,11 @@ env_file: required: false ``` -#### format +#### `format` {{< introduced compose 2.30.0 "/manuals/compose/releases/release-notes.md#2300" >}} -The `format` attribute lets you use an alternative file format for the `env_file`. When not set, `env_file` is parsed according to the Compose rules outlined in [Env_file format](#env_file-format). +The `format` attribute lets you use an alternative file format for the `env_file`. When not set, `env_file` is parsed according to the Compose rules outlined in [`Env_file` format](#env_file-format). `raw` format lets you use an `env_file` with key=value items, but without any attempt from Compose to parse the value for interpolation. This let you pass values as-is, including quotes and `$` signs. @@ -665,7 +665,7 @@ env_file: format: raw ``` -#### Env_file format +#### `Env_file` format Each line in an `.env` file must be in `VAR[=[VAL]]` format. The following syntax rules apply: @@ -702,7 +702,7 @@ RACK_ENV=development VAR="quoted" ``` -### environment +### `environment` {{< include "compose/services-environment.md" >}} @@ -730,7 +730,7 @@ environment: When both `env_file` and `environment` are set for a service, values set by `environment` have precedence. -### expose +### `expose` `expose` defines the (incoming) port or a range of ports that Compose exposes from the container. These ports must be accessible to linked services and should not be published to the host machine. Only the internal container @@ -750,7 +750,7 @@ expose: > > If the Dockerfile for the image already exposes ports, it is visible to other containers on the network even if `expose` is not set in your Compose file. -### extends +### `extends` `extends` lets you share common configurations among different files, or even different projects entirely. With `extends` you can define a common set of service options in one place and refer to it from anywhere. You can refer to another Compose file and select a service you want to also use in your own application, with the ability to override some attributes for your own needs. @@ -811,9 +811,8 @@ The following keys should be treated as mappings: `annotations`, `build.args`, ` `labels`, `logging.options`, `sysctls`, `storage_opt`, `extra_hosts`, `ulimits`. One exception that applies to `healthcheck` is that the main mapping cannot specify -`disable: true` unless the referenced mapping also specifies `disable: true`. Compose returns an error in this case. - -For example, the input below: +`disable: true` unless the referenced mapping also specifies `disable: true`. Compose returns an error in this case. +For example, the following input: ```yaml services: @@ -844,7 +843,7 @@ Items under `blkio_config.device_read_bps`, `blkio_config.device_read_iops`, `volumes` are also treated as mappings where key is the target path inside the container. -For example, the input below: +For example, the following input: ```yaml services: @@ -872,7 +871,7 @@ If the referenced service definition contains `extends` mapping, the items under are simply copied into the new merged definition. The merging process is then kicked off again until no `extends` keys are remaining. -For example, the input below: +For example, the following input: ```yaml services: @@ -906,19 +905,19 @@ The following keys should be treated as sequences: `cap_add`, `cap_drop`, `confi Any duplicates resulting from the merge are removed so that the sequence only contains unique elements. -For example, the input below: +For example, the following input: ```yaml services: common: image: busybox security_opt: - - label:role:ROLE + - label=role:ROLE cli: extends: service: common security_opt: - - label:user:USER + - label=user:USER ``` Produces the following configuration for the `cli` service. @@ -926,19 +925,19 @@ Produces the following configuration for the `cli` service. ```yaml image: busybox security_opt: -- label:role:ROLE -- label:user:USER +- label=role:ROLE +- label=user:USER ``` In case list syntax is used, the following keys should also be treated as sequences: -`dns`, `dns_search`, `env_file`, `tmpfs`. Unlike sequence fields mentioned above, +`dns`, `dns_search`, `env_file`, `tmpfs`. Unlike sequence fields mentioned previously, duplicates resulting from the merge are not removed. ##### Scalars Any other allowed keys in the service definition should be treated as scalars. -### external_links +### `external_links` `external_links` link service containers to services managed outside of your Compose application. `external_links` define the name of an existing service to retrieve using the platform lookup mechanism. @@ -951,7 +950,7 @@ external_links: - database:postgresql ``` -### extra_hosts +### `extra_hosts` `extra_hosts` adds hostname mappings to the container network interface configuration (`/etc/hosts` for Linux). @@ -1001,7 +1000,7 @@ configuration, which means for Linux `/etc/hosts` get extra lines: ::1 myhostv6 ``` -### group_add +### `group_add` `group_add` specifies additional groups, by name or number, which the user inside the container must be a member of. @@ -1020,7 +1019,7 @@ services: Running `id` inside the created container must show that the user belongs to the `mail` group, which would not have been the case if `group_add` were not declared. -### healthcheck +### `healthcheck` {{< include "compose/services-healthcheck.md" >}} @@ -1048,7 +1047,7 @@ test: ["CMD", "curl", "-f", "http://localhost"] ``` Using `CMD-SHELL` runs the command configured as a string using the container's default shell -(`/bin/sh` for Linux). Both forms below are equivalent: +(`/bin/sh` for Linux). Both of the following forms are equivalent: ```yml test: ["CMD-SHELL", "curl -f http://localhost || exit 1"] @@ -1066,11 +1065,11 @@ healthcheck: disable: true ``` -### hostname +### `hostname` `hostname` declares a custom host name to use for the service container. It must be a valid RFC 1123 hostname. -### image +### `image` `image` specifies the image to start the container from. `image` must follow the Open Container Specification [addressable image format](https://github.com/opencontainers/org/blob/master/docs/docs/introduction/digests.md), @@ -1091,7 +1090,7 @@ pull over building the image from source, however pulling the image is the defau `image` may be omitted from a Compose file as long as a `build` section is declared. If you are not using the Compose Build Specification, Compose won't work if `image` is missing from the Compose file. -### init +### `init` `init` runs an init process (PID 1) inside the container that forwards signals and reaps processes. Set this option to `true` to enable this feature for the service. @@ -1105,7 +1104,7 @@ services: The init binary that is used is platform specific. -### ipc +### `ipc` `ipc` configures the IPC isolation mode set by the service container. @@ -1119,11 +1118,11 @@ The init binary that is used is platform specific. ipc: "service:[service name]" ``` -### isolation +### `isolation` `isolation` specifies a container’s isolation technology. Supported values are platform specific. -### labels +### `labels` `labels` add metadata to containers. You can use either an array or a map. @@ -1152,7 +1151,28 @@ Compose creates containers with canonical labels: The `com.docker.compose` label prefix is reserved. Specifying labels with this prefix in the Compose file results in a runtime error. -### links +### `label_file` + +{{< introduced compose 2.23.2 "/manuals/compose/releases/release-notes.md#2232" >}} + +The `label_file` attribute lets you load labels for a service from an external file or a list of files. This provides a convenient way to manage multiple labels without cluttering the Compose file. + +The file uses a key-value format, similar to `env_file`. You can specify multiple files as a list. When using multiple files, they are processed in the order they appear in the list. If the same label is defined in multiple files, the value from the last file in the list overrides earlier ones. + +```yaml +services: + one: + label_file: ./app.labels + + two: + label_file: + - ./app.labels + - ./additional.labels +``` + +If a label is defined in both the `label_file` and the `labels` attribute, the value in [labels](#labels) takes precedence. + +### `links` `links` defines a network link to containers in another service. Either specify both the service name and a link alias (`SERVICE:ALIAS`), or just the service name. @@ -1169,14 +1189,13 @@ Containers for the linked service are reachable at a hostname identical to the a if no alias is specified. Links are not required to enable services to communicate. When no specific network configuration is set, -any service is able to reach any other service at that service’s name on the `default` network. If services -do declare networks they are attached to, `links` does not override the network configuration and services not -attached to a shared network are not be able to communicate. Compose doesn't warn you about a configuration mismatch. +any service is able to reach any other service at that service’s name on the `default` network. +If services specify the networks they are attached to, `links` does not override the network configuration. Services that are not connected to a shared network are not be able to communicate with each other. Compose doesn't warn you about a configuration mismatch. Links also express implicit dependency between services in the same way as -[depends_on](#depends_on), so they determine the order of service startup. +[`depends_on`](#depends_on), so they determine the order of service startup. -### logging +### `logging` `logging` defines the logging configuration for the service. @@ -1190,28 +1209,28 @@ logging: The `driver` name specifies a logging driver for the service's containers. The default and available values are platform specific. Driver specific options can be set with `options` as key-value pairs. -### mac_address +### `mac_address` > Available with Docker Compose version 2.24.0 and later. -`mac_address` sets a MAC address for the service container. +`mac_address` sets a Mac address for the service container. > [!NOTE] -> Container runtimes might reject this value (ie. Docker Engine >= v25.0). In that case, you should use [networks.mac_address](#mac_address) instead. +> Container runtimes might reject this value, for example Docker Engine >= v25.0. In that case, you should use [networks.mac_address](#mac_address) instead. -### mem_limit +### `mem_limit` `mem_limit` configures a limit on the amount of memory a container can allocate, set as a string expressing a [byte value](extension.md#specifying-byte-values). When set, `mem_limit` must be consistent with the `limits.memory` attribute in the [Deploy Specification](deploy.md#memory). -### mem_reservation +### `mem_reservation` `mem_reservation` configures a reservation on the amount of memory a container can allocate, set as a string expressing a [byte value](extension.md#specifying-byte-values). When set, `mem_reservation` must be consistent with the `reservations.memory` attribute in the [Deploy Specification](deploy.md#memory). -### mem_swappiness +### `mem_swappiness` `mem_swappiness` defines as a percentage, a value between 0 and 100, for the host kernel to swap out anonymous memory pages used by a container. @@ -1221,7 +1240,7 @@ anonymous memory pages used by a container. The default value is platform specific. -### memswap_limit +### `memswap_limit` `memswap_limit` defines the amount of memory the container is allowed to swap to disk. This is a modifier attribute that only has meaning if [`memory`](deploy.md#memory) is also set. Using swap lets the container write excess @@ -1234,7 +1253,7 @@ There is a performance penalty for applications that swap memory to disk often. - If `memswap_limit` is unset, and `memory` is set, the container can use as much swap as the `memory` setting, if the host container has swap memory configured. For instance, if `memory`="300m" and `memswap_limit` is not set, the container can use 600m in total of memory and swap. - If `memswap_limit` is explicitly set to -1, the container is allowed to use unlimited swap, up to the amount available on the host system. -### network_mode +### `network_mode` `network_mode` sets a service container's network mode. @@ -1254,7 +1273,7 @@ For more information container networks, see the [Docker Engine documentation](/ When set, the [`networks`](#networks) attribute is not allowed and Compose rejects any Compose file containing both attributes. -### networks +### `networks` {{< include "compose/services-networks.md" >}} @@ -1267,7 +1286,7 @@ services: ``` For more information about the `networks` top-level element, see [Networks](networks.md). -#### aliases +#### `aliases` `aliases` declares alternative hostnames for the service on the network. Other containers on the same network can use either the service name or an alias to connect to one of the service's containers. @@ -1324,7 +1343,7 @@ networks: admin: ``` -#### ipv4_address, ipv6_address +#### `ipv4_address`, `ipv6_address` Specify a static IP address for a service container when joining the network. @@ -1349,7 +1368,7 @@ networks: - subnet: "2001:3984:3989::/64" ``` -#### link_local_ips +#### `link_local_ips` `link_local_ips` specifies a list of link-local IPs. Link-local IPs are special IPs which belong to a well known subnet and are purely managed by the operator, usually dependent on the architecture where they are @@ -1372,13 +1391,13 @@ networks: driver: bridge ``` -#### mac_address +#### `mac_address` {{< introduced compose 2.23.2 "/manuals/compose/releases/release-notes.md#2232" >}} -`mac_address` sets the MAC address used by the service container when connecting to this particular network. +`mac_address` sets the Mac address used by the service container when connecting to this particular network. -#### priority +#### `priority` `priority` indicates in which order Compose connects the service’s containers to its networks. If unspecified, the default value is 0. @@ -1403,22 +1422,22 @@ networks: app_net_3: ``` -### oom_kill_disable +### `oom_kill_disable` If `oom_kill_disable` is set, Compose configures the platform so it won't kill the container in case of memory starvation. -### oom_score_adj +### `oom_score_adj` `oom_score_adj` tunes the preference for containers to be killed by platform in case of memory starvation. Value must be within -1000,1000 range. -### pid +### `pid` `pid` sets the PID mode for container created by Compose. Supported values are platform specific. -### pids_limit +### `pids_limit` `pids_limit` tunes a container’s PIDs limit. Set to -1 for unlimited PIDs. @@ -1428,7 +1447,7 @@ pids_limit: 10 When set, `pids_limit` must be consistent with the `pids` attribute in the [Deploy Specification](deploy.md#pids). -### platform +### `platform` `platform` defines the target platform the containers for the service run on. It uses the `os[/arch[/variant]]` syntax. @@ -1443,7 +1462,7 @@ platform: windows/amd64 platform: linux/arm64/v8 ``` -### ports +### `ports` {{< include "compose/services-ports.md" >}} @@ -1470,7 +1489,7 @@ Either specify both ports (`HOST:CONTAINER`), or just the container port. In the the container runtime automatically allocates any unassigned port of the host. `HOST:CONTAINER` should always be specified as a (quoted) string, to avoid conflicts -with [yaml base-60 float](https://yaml.org/type/float.html). +with [YAML base-60 float](https://yaml.org/type/float.html). Examples: @@ -1494,7 +1513,7 @@ ports: #### Long syntax -The long form syntax allows the configuration of additional fields that can't be +The long form syntax lets you configure additional fields that can't be expressed in the short form. - `target`: The container port @@ -1524,7 +1543,7 @@ ports: mode: host ``` -### post_start +### `post_start` {{< introduced compose 2.30.0 "../../manuals/compose/releases/release-notes.md#2300" >}} @@ -1549,19 +1568,19 @@ services: For more information, see [Use lifecycle hooks](/manuals/compose/how-tos/lifecycle.md). -### pre_stop +### `pre_stop` {{< introduced compose 2.30.0 "../../manuals/compose/releases/release-notes.md#2300" >}} `pre_stop` defines a sequence of lifecycle hooks to run before the container is stopped. These hooks won't run if the container stops by itself or is terminated suddenly. -Configuration is equivalent to [`post_start](#post_start). +Configuration is equivalent to [post_start](#post_start). -### privileged +### `privileged` `privileged` configures the service container to run with elevated privileges. Support and actual impacts are platform specific. -### profiles +### `profiles` `profiles` defines a list of named profiles for the service to be enabled under. If unassigned, the service is always started but if assigned, it is only started if the profile is activated. @@ -1581,7 +1600,7 @@ services: - debug ``` -### pull_policy +### `pull_policy` `pull_policy` defines the decisions Compose makes when it starts to pull images. Possible values are: @@ -1593,11 +1612,11 @@ services: `if_not_present` is considered an alias for this value for backward compatibility. * `build`: Compose builds the image. Compose rebuilds the image if it's already present. -### read_only +### `read_only` `read_only` configures the service container to be created with a read-only filesystem. -### restart +### `restart` `restart` defines the policy that the platform applies on container termination. @@ -1620,7 +1639,7 @@ You can find more detailed information on restart policies in the [Restart Policies (--restart)](/reference/cli/docker/container/run.md#restart) section of the Docker run reference page. -### runtime +### `runtime` `runtime` specifies which runtime to use for the service’s containers. @@ -1635,12 +1654,12 @@ web: The default is `runc`. To use a different runtime, see [Alternative runtimes](/manuals/engine/daemon/alternative-runtimes.md). -### scale +### `scale` `scale` specifies the default number of containers to deploy for this service. When both are set, `scale` must be consistent with the `replicas` attribute in the [Deploy Specification](deploy.md#replicas). -### secrets +### `secrets` {{< include "compose/services-secrets.md" >}} @@ -1682,8 +1701,8 @@ the service's containers. - `source`: The name of the secret as it exists on the platform. - `target`: The name of the file to be mounted in `/run/secrets/` in the service's task container, or absolute path of the file if an alternate location is required. Defaults to `source` if not specified. -- `uid` and `gid`: The numeric UID or GID that owns the file within - `/run/secrets/` in the service's task containers. Default value is USER running container. +- `uid` and `gid`: The numeric uid or gid that owns the file within + `/run/secrets/` in the service's task containers. Default value is `USER`. - `mode`: The [permissions](https://wintelguy.com/permissions-calc.pl) for the file to be mounted in `/run/secrets/` in the service's task containers, in octal notation. The default value is world-readable permissions (mode `0444`). @@ -1709,31 +1728,31 @@ secrets: file: ./server.cert ``` -### security_opt +### `security_opt` `security_opt` overrides the default labeling scheme for each container. ```yml security_opt: - - label:user:USER - - label:role:ROLE + - label=user:USER + - label=role:ROLE ``` For further default labeling schemes you can override, see [Security configuration](/reference/cli/docker/container/run.md#security-opt). -### shm_size +### `shm_size` `shm_size` configures the size of the shared memory (`/dev/shm` partition on Linux) allowed by the service container. It's specified as a [byte value](extension.md#specifying-byte-values). -### stdin_open +### `stdin_open` `stdin_open` configures a service's container to run with an allocated stdin. This is the same as running a container with the -`-i` flag. For more information, see [Keep STDIN open](/reference/cli/docker/container/run.md#interactive). +`-i` flag. For more information, see [Keep stdin open](/reference/cli/docker/container/run.md#interactive). Supported values are `true` or `false`. -### stop_grace_period +### `stop_grace_period` `stop_grace_period` specifies how long Compose must wait when attempting to stop a container if it doesn't handle SIGTERM (or whichever stop signal has been specified with @@ -1747,7 +1766,7 @@ as a [duration](extension.md#specifying-durations). Default value is 10 seconds for the container to exit before sending SIGKILL. -### stop_signal +### `stop_signal` `stop_signal` defines the signal that Compose uses to stop the service containers. If unset containers are stopped by Compose by sending `SIGTERM`. @@ -1756,7 +1775,7 @@ If unset containers are stopped by Compose by sending `SIGTERM`. stop_signal: SIGUSR1 ``` -### storage_opt +### `storage_opt` `storage_opt` defines storage driver options for a service. @@ -1765,7 +1784,7 @@ storage_opt: size: '1G' ``` -### sysctls +### `sysctls` `sysctls` defines kernel parameters to set in the container. `sysctls` can use either an array or a map. @@ -1786,7 +1805,7 @@ support changing sysctls inside a container that also modify the host system. For an overview of supported sysctls, refer to [configure namespaced kernel parameters (sysctls) at runtime](/reference/cli/docker/container/run.md#sysctl). -### tmpfs +### `tmpfs` `tmpfs` mounts a temporary file system inside the container. It can be a single value or a list. @@ -1796,8 +1815,8 @@ tmpfs: - : ``` -- : The path inside the container where the tmpfs will be mounted. -- : Comma-separated list of options for the tmpfs mount. +- `path`: The path inside the container where the tmpfs will be mounted. +- `options`: Comma-separated list of options for the tmpfs mount. Available options: @@ -1813,16 +1832,16 @@ services: - /run ``` -### tty +### `tty` `tty` configures a service's container to run with a TTY. This is the same as running a container with the `-t` or `--tty` flag. For more information, see [Allocate a pseudo-TTY](/reference/cli/docker/container/run.md#tty). Supported values are `true` or `false`. -### ulimits +### `ulimits` -`ulimits` overrides the default ulimits for a container. It's specified either as an integer for a single limit +`ulimits` overrides the default `ulimits` for a container. It's specified either as an integer for a single limit or as mapping for soft/hard limits. ```yml @@ -1833,11 +1852,11 @@ ulimits: hard: 40000 ``` -### user +### `user` -`user` overrides the user used to run the container process. The default is set by the image (i.e. Dockerfile `USER`). If it's not set, then `root`. +`user` overrides the user used to run the container process. The default is set by the image, for example Dockerfile `USER`. If it's not set, then `root`. -### userns_mode +### `userns_mode` `userns_mode` sets the user namespace for the service. Supported values are platform specific and may depend on platform configuration. @@ -1846,7 +1865,7 @@ on platform configuration. userns_mode: "host" ``` -### uts +### `uts` {{< introduced compose 2.15.1 "/manuals/compose/releases/release-notes.md#2151" >}} @@ -1859,7 +1878,7 @@ it is the runtime's decision to assign a UTS namespace, if supported. Available uts: "host" ``` -### volumes +### `volumes` {{< include "compose/services-volumes.md" >}} @@ -1913,7 +1932,7 @@ The short syntax uses a single string with colon-separated values to specify a v #### Long syntax -The long form syntax allows the configuration of additional fields that can't be +The long form syntax lets you configure additional fields that can't be expressed in the short form. - `type`: The mount type. Either `volume`, `bind`, `tmpfs`, `npipe`, or `cluster` @@ -1942,7 +1961,7 @@ expressed in the short form. > Compose now takes advantage of [Synchronized file shares](/manuals/desktop/features/synchronized-file-sharing.md) and automatically creates file shares for bind mounts. > Ensure you're signed in to Docker with a paid subscription and have enabled both **Access experimental features** and **Manage Synchronized file shares with Compose** in Docker Desktop's settings. -### volumes_from +### `volumes_from` `volumes_from` mounts all of the volumes from another service or container. You can optionally specify read-only access `ro` or read-write `rw`. If no access level is specified, then read-write access is used. @@ -1957,6 +1976,6 @@ volumes_from: - container:container_name:rw ``` -### working_dir +### `working_dir` `working_dir` overrides the container's working directory which is specified by the image, for example Dockerfile's `WORKDIR`. diff --git a/content/reference/compose-file/volumes.md b/content/reference/compose-file/volumes.md index fb026e2669a..333d8e666a7 100644 --- a/content/reference/compose-file/volumes.md +++ b/content/reference/compose-file/volumes.md @@ -47,7 +47,7 @@ Running `docker compose up` creates the volume if it doesn't already exist. Othe An entry under the top-level `volumes` section can be empty, in which case it uses the container engine's default configuration for creating a volume. Optionally, you can configure it with the following keys: -### driver +### `driver` Specifies which volume driver should be used. If the driver is not available, Compose returns an error and doesn't deploy the application. @@ -57,7 +57,7 @@ volumes: driver: foobar ``` -### driver_opts +### `driver_opts` `driver_opts` specifies a list of options as key-value pairs to pass to the driver for this volume. The options are driver-dependent. @@ -70,14 +70,14 @@ volumes: device: ":/docker/example" ``` -### external +### `external` If set to `true`: - `external` specifies that this volume already exists on the platform and its lifecycle is managed outside of that of the application. Compose then doesn't create the volume and returns an error if the volume doesn't exist. - All other attributes apart from `name` are irrelevant. If Compose detects any other attribute, it rejects the Compose file as invalid. -In the example below, instead of attempting to create a volume called +In the following example, instead of attempting to create a volume called `{project_name}_db-data`, Compose looks for an existing volume simply called `db-data` and mounts it into the `backend` service's containers. @@ -93,7 +93,7 @@ volumes: external: true ``` -### labels +### `labels` `labels` are used to add metadata to volumes. You can use either an array or a dictionary. @@ -119,7 +119,7 @@ volumes: Compose sets `com.docker.compose.project` and `com.docker.compose.volume` labels. -### name +### `name` `name` sets a custom name for a volume. The name field can be used to reference volumes that contain special characters. The name is used as is and is not scoped with the stack name. diff --git a/data/desktop-cli/docker_desktop.yaml b/data/desktop-cli/docker_desktop.yaml new file mode 100644 index 00000000000..a222a240064 --- /dev/null +++ b/data/desktop-cli/docker_desktop.yaml @@ -0,0 +1,24 @@ +command: docker desktop +short: Docker Desktop +long: Control Docker Desktop from the CLI +usage: docker desktop +pname: docker +plink: docker.yaml +cname: + - docker desktop start + - docker desktop stop + - docker desktop restart + - docker desktop status + - docker desktop engine +clink: + - docker_desktop_start.yaml + - docker_desktop_stop.yaml + - docker_desktop_restart.yaml + - docker_desktop_status.yaml + - docker_desktop_engine.yaml +deprecated: false +hidden: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false \ No newline at end of file diff --git a/data/desktop-cli/docker_desktop_engine.yaml b/data/desktop-cli/docker_desktop_engine.yaml new file mode 100644 index 00000000000..86295164a62 --- /dev/null +++ b/data/desktop-cli/docker_desktop_engine.yaml @@ -0,0 +1,17 @@ +command: docker desktop engine +short: Commands to list and switch containers (Windows only) +usage: docker desktop engine +pname: docker desktop +plink: docker_desktop.yaml +cname: + - docker desktop engine ls + - docker desktop engine use +clink: + - docker_desktop_engine_ls.yaml + - docker_desktop_engine_use.yaml +deprecated: false +hidden: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false \ No newline at end of file diff --git a/data/desktop-cli/docker_desktop_engine_ls.yaml b/data/desktop-cli/docker_desktop_engine_ls.yaml new file mode 100644 index 00000000000..52a1012d06d --- /dev/null +++ b/data/desktop-cli/docker_desktop_engine_ls.yaml @@ -0,0 +1,11 @@ +command: docker desktop engine ls +short: List available engines (Windows only) +usage: docker desktop engine ls +pname: docker desktop engine +plink: docker_desktop_engine.yaml +deprecated: false +hidden: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false \ No newline at end of file diff --git a/data/desktop-cli/docker_desktop_engine_use.yaml b/data/desktop-cli/docker_desktop_engine_use.yaml new file mode 100644 index 00000000000..e289519506c --- /dev/null +++ b/data/desktop-cli/docker_desktop_engine_use.yaml @@ -0,0 +1,11 @@ +command: docker desktop engine use +short: Switch to Windows or Linux containers (Windows only) +usage: docker desktop engine use NAME +pname: docker desktop engine +plink: docker_desktop_engine.yaml +deprecated: false +hidden: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false \ No newline at end of file diff --git a/data/desktop-cli/docker_desktop_restart.yaml b/data/desktop-cli/docker_desktop_restart.yaml new file mode 100644 index 00000000000..4809ede1544 --- /dev/null +++ b/data/desktop-cli/docker_desktop_restart.yaml @@ -0,0 +1,11 @@ +command: docker desktop restart +short: Restart Docker Desktop +usage: docker desktop restart +pname: docker desktop +plink: docker_desktop.yaml +deprecated: false +hidden: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false \ No newline at end of file diff --git a/data/desktop-cli/docker_desktop_start.yaml b/data/desktop-cli/docker_desktop_start.yaml new file mode 100644 index 00000000000..3422aa8873d --- /dev/null +++ b/data/desktop-cli/docker_desktop_start.yaml @@ -0,0 +1,32 @@ +command: docker desktop start +short: Start Docker Desktop +usage: docker desktop start [OPTIONS] +pname: docker desktop +plink: docker_desktop.yaml +options: + - option: detach + value_type: bool + default_value: false + description: Start Docker Desktop in the background + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: timeout + value_type: init + default_value: 0 + description: Specify in seconds how long to wait for Docker Desktop to start before timing out + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +deprecated: false +hidden: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false diff --git a/data/desktop-cli/docker_desktop_status.yaml b/data/desktop-cli/docker_desktop_status.yaml new file mode 100644 index 00000000000..e69a46a6e17 --- /dev/null +++ b/data/desktop-cli/docker_desktop_status.yaml @@ -0,0 +1,11 @@ +command: docker desktop status +short: Display Docker Desktop's status +usage: docker desktop status +pname: docker desktop +plink: docker_desktop.yaml +deprecated: false +hidden: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false \ No newline at end of file diff --git a/data/desktop-cli/docker_desktop_stop.yaml b/data/desktop-cli/docker_desktop_stop.yaml new file mode 100644 index 00000000000..e0b775a4e6f --- /dev/null +++ b/data/desktop-cli/docker_desktop_stop.yaml @@ -0,0 +1,41 @@ +command: docker desktop stop +short: Stop Docker Desktop +usage: docker desktop stop [OPTIONS] +pname: docker desktop +plink: docker_desktop.yaml +options: + - option: detach + value_type: bool + default_value: false + description: Stop Docker Desktop in the background + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: force + value_type: bool + default_value: false + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: timeout + value_type: init + default_value: 0 + description: Specify in seconds how long to wait for Docker Desktop to stop before timing out + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +deprecated: false +hidden: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false \ No newline at end of file diff --git a/go.mod b/go.mod index 9f2ade109a4..d7d7553640c 100644 --- a/go.mod +++ b/go.mod @@ -5,16 +5,16 @@ go 1.23.1 require ( github.com/docker/buildx v0.19.2 // indirect github.com/docker/cli v27.4.0+incompatible // indirect - github.com/docker/compose/v2 v2.31.0 // indirect + github.com/docker/compose/v2 v2.32.2 // indirect github.com/docker/scout-cli v1.15.0 // indirect - github.com/moby/buildkit v0.18.0 // indirect + github.com/moby/buildkit v0.18.1 // indirect github.com/moby/moby v27.4.0+incompatible // indirect ) replace ( github.com/docker/buildx => github.com/docker/buildx v0.19.2 github.com/docker/cli => github.com/docker/cli v27.4.0+incompatible - github.com/docker/compose/v2 => github.com/docker/compose/v2 v2.31.0 + github.com/docker/compose/v2 => github.com/docker/compose/v2 v2.32.2 github.com/docker/scout-cli => github.com/docker/scout-cli v1.15.0 github.com/moby/buildkit => github.com/moby/buildkit v0.18.0 github.com/moby/moby => github.com/moby/moby v27.4.0+incompatible diff --git a/go.sum b/go.sum index 628d1d59fce..48c1f1d0d7e 100644 --- a/go.sum +++ b/go.sum @@ -190,6 +190,7 @@ github.com/docker/compose/v2 v2.30.3 h1:e8H7xGLCZOeFo46GEtyDGHlkBbNgXqbXKIXPOSL8 github.com/docker/compose/v2 v2.30.3/go.mod h1:ayPsSsRSc5WpVFehPrTDFuljAydxaf8g0aM9UKbaMXk= github.com/docker/compose/v2 v2.31.0 h1:8Sm0c4MjIhksguxIA5koYMXoTJDAp/CaZ1cdZrMvMdw= github.com/docker/compose/v2 v2.31.0/go.mod h1:oQq3UDEdsnB3AUO72AxaoeLbkCgmUu1+8tLzvmphmXA= +github.com/docker/compose/v2 v2.32.2/go.mod h1:fcK4rrf1bm8pfDsYdZIR+l4RSk9j6HVtBvJKGYyXsZ4= github.com/docker/distribution v2.8.2+incompatible h1:T3de5rq0dB1j30rp0sA2rER+m322EBzniBPB6ZIzuh8= github.com/docker/distribution v2.8.2+incompatible/go.mod h1:J2gT2udsDAN96Uj4KfcMRqY0/ypR+oyYUYmja8H+y+w= github.com/docker/distribution v2.8.3+incompatible h1:AtKxIZ36LoNK51+Z6RpzLpddBirtxJnzDrHLEKxTAYk= diff --git a/hugo.yaml b/hugo.yaml index fb311ec1838..46d5a959c06 100644 --- a/hugo.yaml +++ b/hugo.yaml @@ -108,7 +108,8 @@ params: latest_engine_api_version: "1.47" docker_ce_version: "27.4.0" - compose_version: "v2.30.3" + docker_ce_version_prev: "27.3.1" + compose_version: "v2.32.2" compose_file_v3: "3.8" compose_file_v2: "2.4" buildkit_version: "0.16.0" diff --git a/hugo_stats.json b/hugo_stats.json index 0cc860b0665..4cb719a37c9 100644 --- a/hugo_stats.json +++ b/hugo_stats.json @@ -42,6 +42,7 @@ "Docker-Desktop", "Docker-Hub", "Docker-Scout-Dashboard", + "Docker-plan", "Download", "Entra-ID", "Entra-ID-SAML-2.0", @@ -68,6 +69,8 @@ "JavaScript", "Jenkins", "Latest", + "Legacy-Docker-plan", + "Legacy-Docker-plans", "Linux", "Local-or-Hub-storage", "MDM", @@ -138,7 +141,6 @@ "aspect-video", "bake-action", "bg-amber-light", - "bg-amber-light-200", "bg-background-light", "bg-black/50", "bg-black/70", @@ -191,7 +193,6 @@ "containerd-image-store", "cursor-pointer", "dark:bg-amber-dark", - "dark:bg-amber-dark-200", "dark:bg-background-dark", "dark:bg-blue-dark", "dark:bg-blue-dark-400", @@ -261,6 +262,7 @@ "flex-col", "flex-col-reverse", "flex-grow", + "flex-grow-0", "flex-none", "flex-shrink", "flex-wrap", @@ -342,6 +344,7 @@ "lg:gap-8", "lg:grid-cols-2", "lg:grid-cols-3", + "lg:grid-cols-4", "lg:hidden", "lg:no-underline", "lg:pb-2", diff --git a/layouts/index.html b/layouts/index.html index c7d3963d855..04ee028ae60 100644 --- a/layouts/index.html +++ b/layouts/index.html @@ -41,7 +41,29 @@

Get Docker

-
+
+ + +
- Get started and learn how Docker can optimize your development workflows. + Learn how Docker can optimize your development workflows.
@@ -112,16 +134,21 @@

Get Docker

-

Getting started

+

Gen AI catalog {{ partial + "components/badge.html" (dict "color" "blue" "content" "New") + }}

- Learn Docker basics and the benefits of containerizing your - applications + Integrate AI solutions into your apps with minimal effort

-
@@ -134,23 +161,26 @@

Getting started

-

Research

+

+ Ask Gordon + {{ partial "components/badge.html" (dict "color" "blue" "content" "Beta") }} +

- Docker State of Application Development survey + Your personal Docker expert, built right into Docker Desktop.

- Help us better understand and support the application development - community by answering our community survey. -

-

- The survey takes approximately 20-30 minutes to complete, and - you can save your progress and return at any time. As a thank - you, you can opt into a raffle for Docker swag and other - prizes! + Boost your productivity with Ask Gordon, an AI-powered + assistant designed to optimize your Docker workflows. From + improving Dockerfiles to troubleshooting containers, Gordon + is here to help.

- Take the survey +
+ Join the beta + Read the docs +
diff --git a/layouts/partials/sidebar/sections.html b/layouts/partials/sidebar/sections.html index 988c4557eee..d166b61e21a 100644 --- a/layouts/partials/sidebar/sections.html +++ b/layouts/partials/sidebar/sections.html @@ -8,11 +8,10 @@ {{ define "renderChildren" }} - {{- $pages := .Pages }} + {{- $pages := where .Pages "Params.sitemap" "ne" "false" }} {{- if .Params.sidebar.reverse }} {{ $pages = .Pages.Reverse }} {{- end }} - {{- $pages = where .Pages "Params.sitemap" "ne" "false" }} {{- $ungrouped := where $pages "Params.sidebar.group" "==" nil }} {{- range $ungrouped }} {{- if .IsSection }} diff --git a/layouts/shortcodes/admin-domain-audit.md b/layouts/shortcodes/admin-domain-audit.md index d43dd82c75e..983555f834f 100644 --- a/layouts/shortcodes/admin-domain-audit.md +++ b/layouts/shortcodes/admin-domain-audit.md @@ -5,7 +5,7 @@ {{ if eq (.Get "product") "admin" }} {{ $product_link = "the [Admin Console](https://admin.docker.com)" }} - {{ $domain_navigation = "Select your organization in the left navigation drop-down menu, and then select **Domain management**." }} + {{ $domain_navigation = "Select your organization on the **Choose profile** page, and then select **Domain management**." }} {{ $sso_link = "[SSO](/security/for-admins/single-sign-on/)" }} {{ $scim_link = "[SCIM](/security/for-admins/provisioning/scim/)" }} {{ end }} diff --git a/layouts/shortcodes/admin-sso-config.md b/layouts/shortcodes/admin-sso-config.md index 1c959eeadc4..3a4a0d38b6f 100644 --- a/layouts/shortcodes/admin-sso-config.md +++ b/layouts/shortcodes/admin-sso-config.md @@ -3,7 +3,7 @@ {{ if eq (.Get "product") "admin" }} {{ $product_link = "the [Admin Console](https://admin.docker.com)" }} - {{ $sso_navigation = "Select your organization or company in the left navigation drop-down menu, and then select **SSO and SCIM**. Note that when an organization is part of a company, you must select the company and configure SSO for that organization at the company level. Each organization can have its own SSO configuration and domain, but it must be configured at the company level." }} + {{ $sso_navigation = "Select your organization or company from the **Choose profile** page, and then select **SSO and SCIM**. Note that when an organization is part of a company, you must select the company and configure SSO for that organization at the company level. Each organization can have its own SSO configuration and domain, but it must be configured at the company level." }} {{ end }} > [!IMPORTANT] diff --git a/layouts/shortcodes/admin-sso-connect.md b/layouts/shortcodes/admin-sso-connect.md index e5663366a7f..4e045bd904f 100644 --- a/layouts/shortcodes/admin-sso-connect.md +++ b/layouts/shortcodes/admin-sso-connect.md @@ -3,7 +3,7 @@ {{ if eq (.Get "product") "admin" }} {{ $product_link = "the [Admin Console](https://admin.docker.com)" }} - {{ $sso_navigation = "Select your organization or company in the left navigation drop-down menu, and then select **SSO and SCIM**. Note that when an organization is part of a company, you must select the company and configure SSO for that organization at the company level. Each organization can have its own SSO configuration and domain, but it must be configured at the company level." }} + {{ $sso_navigation = "Select your organization or company from the **Choose profile** page, and then select **SSO and SCIM**. Note that when an organization is part of a company, you must select the company and configure SSO for that organization at the company level. Each organization can have its own SSO configuration and domain, but it must be configured at the company level." }} {{ end }} 1. In {{ $product_link }}, select the verified domains you want to apply the connection to. diff --git a/layouts/shortcodes/admin-sso-management-connections.md b/layouts/shortcodes/admin-sso-management-connections.md index fe185d85818..ab51525e994 100644 --- a/layouts/shortcodes/admin-sso-management-connections.md +++ b/layouts/shortcodes/admin-sso-management-connections.md @@ -3,7 +3,7 @@ {{ if eq (.Get "product") "admin" }} {{ $product_link = "the [Admin Console](https://app.docker.com/admin)" }} - {{ $sso_navigation = "Select your organization or company in the left navigation drop-down menu, and then select **SSO and SCIM**. Note that when an organization is part of a company, you must select the company and configure SSO for that organization at the company level. Each organization can have its own SSO configuration and domain, but it must be configured at the company level." }} + {{ $sso_navigation = "Select your organization or company from the Choose proifle page, and then select **SSO and SCIM**. Note that when an organization is part of a company, you must select the company and configure SSO for that organization at the company level. Each organization can have its own SSO configuration and domain, but it must be configured at the company level." }} {{ end }} ### Edit a connection diff --git a/layouts/shortcodes/admin-sso-management-orgs.md b/layouts/shortcodes/admin-sso-management-orgs.md index db97b8b12d4..300c3591108 100644 --- a/layouts/shortcodes/admin-sso-management-orgs.md +++ b/layouts/shortcodes/admin-sso-management-orgs.md @@ -2,7 +2,7 @@ {{ $sso_navigation := "Select **Organizations**, your company, and then **Settings**." }} {{ if eq (.Get "product") "admin" }} {{ $product_link = "the [Admin Console](https://app.docker.com/admin)" }} - {{ $sso_navigation = "Select your company in the left navigation drop-down menu, and then select **SSO and SCIM**." }} + {{ $sso_navigation = "Select your company from the **Choose profile** page, and then select **SSO and SCIM**." }} {{ end }} ### Connect an organization diff --git a/layouts/shortcodes/admin-sso-management.md b/layouts/shortcodes/admin-sso-management.md index a61db8256c4..054c8419a95 100644 --- a/layouts/shortcodes/admin-sso-management.md +++ b/layouts/shortcodes/admin-sso-management.md @@ -3,7 +3,7 @@ {{ if eq (.Get "product") "admin" }} {{ $product_link = "the [Admin Console](https://app.docker.com/admin)" }} - {{ $sso_navigation = "Select your organization or company in the left navigation drop-down menu, and then select **SSO and SCIM**." }} + {{ $sso_navigation = "Select your organization or company from the **Choose profile** page, and then select **SSO and SCIM**." }} {{ end }} ### Remove a domain from an SSO connection diff --git a/layouts/shortcodes/admin-users.html b/layouts/shortcodes/admin-users.html index 1594d9dfd0b..3643075d5e0 100644 --- a/layouts/shortcodes/admin-users.html +++ b/layouts/shortcodes/admin-users.html @@ -17,7 +17,7 @@ {{ if eq (.Get "product") "admin" }} {{ $invite_button = "**Invite**" }} {{ $export_button = "the **Action** icon and then select **Export users as CSV**" }} -{{ $member_navigation = "Select your organization in the left navigation drop-down menu, and then select **Members**." }} +{{ $member_navigation = "Select your organization from the **Choose profile** page, and then select **Members**." }} {{ $remove_button = "**Remove member**" }} {{ $product_link = "the [Admin Console](https://admin.docker.com)" }} {{ $role_mapping_link = "[SCIM for role mapping](/security/for-admins/provisioning/scim/)" }} @@ -29,7 +29,7 @@ * **Member of Organizations**: All organizations the user is a member of within a company. * **Invited to Organizations**: All organizations the user is an invitee of within a company. * **Account Created**: The time and date when the user account was created.` }} -{{ $member_navigation = "Select your company in the left navigation drop-down menu, and then select **Users**." }} +{{ $member_navigation = "Select your organization from the **Choose profile** page, and then select **Members**." }} {{ $remove_button = "**Remove user**" }} {{ $role_mapping_link = "[SCIM for role mapping](/security/for-admins/provisioning/scim/)"}} {{ end }}