publish updates from main

_vale/Docker/Acronyms.yml

@@ -17,6 +17,7 @@ exceptions:
   - ASP
   - AUFS
   - AWS
+  - BGP     # Border Gateway Protocol
   - BIOS
   - BPF
   - BSD

content/manuals/admin/organization/insights.md

@@ -68,9 +68,9 @@ The chart contains the following data:
 
 | Data | Description |
 |:-----------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| 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. <br><br>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. <br><br>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 user | The number of users who 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. <br><br>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 who have used Docker Desktop, regardless of their Insights activity. |
+| Users opted out of analytics | The number of users who are members of your organization that have opted out of sending analytics. <br><br>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. |
 
 
@@ -142,7 +142,7 @@ The chart contains the following data:
 ### Extensions
 
 Monitor extension installation activity with this chart. It provides visibility
-into the Docker Desktop extensions your team are using, letting you track
+into the Docker Desktop extensions your teams are using, letting you track
 adoption and identify popular tools that enhance productivity.
 
 The chart contains the following data:
@@ -180,7 +180,7 @@ A Docker Desktop user export file contains the following data points:
 member of
 - Date Joined: The date the user joined your organization
 - Last Logged-In Date: The last date the user logged into Docker using
-their web browser (this include Docker Hub and Docker Home)
+their web browser (this includes Docker Hub and Docker Home)
 - Docker Desktop Version: The version of Docker Desktop the user has
 installed
 - Last Seen Date: The last date the user used the Docker Desktop application
@@ -206,11 +206,11 @@ solutions to resolve common problems.
    Management](/desktop/hardened-desktop/settings-management/) and enable the
    `analyticsEnabled` setting.
 
-- Ensure that users are using Docker Desktop and aren't using the standalone
+- Ensure users use Docker Desktop and aren't using the standalone
   version of Docker Engine.
 
-   Only Docker Desktop can provide data for Insights. If a user installs and
-   uses Docker Engine outside of Docker Desktop, Docker Engine won't provide
+   Only Docker Desktop can provide data for Insights. If a user installs Docker
+   Engine outside of Docker Desktop, Docker Engine won't provide
    data for that user.
 
 - Ensure that users are signing in to an account associated with your

content/manuals/build-cloud/ci.md

@@ -36,42 +36,42 @@ See [Loading build results](./usage/#loading-build-results) for details.
 
 To enable your CI/CD system to build and push images using Docker Build Cloud, provide both an access token and a username. The type of token and the username you use depend on your account type and permissions.
 
-- If you are an organization administrator or have permission to create [organization access tokens (OAT)](../security/for-admins/access-tokens.md), use an OAT and set `DOCKER_USER` to your Docker Hub organization name.
-- If you do not have permission to create OATs or are using a personal account, use a [personal access token (PAT)](/security/for-developers/access-tokens/) and set `DOCKER_USER` to your Docker Hub username.
+- If you are an organization administrator or have permission to create [organization access tokens (OAT)](../security/for-admins/access-tokens.md), use an OAT and set `DOCKER_ACCOUNT` to your Docker Hub organization name.
+- If you do not have permission to create OATs or are using a personal account, use a [personal access token (PAT)](/security/for-developers/access-tokens/) and set `DOCKER_ACCOUNT` to your Docker Hub username.
 
 ### Creating access tokens
 
 #### For organization accounts
 
 If you are an organization administrator:
 
-1. Create an [organization access token (OAT)](../security/for-admins/access-tokens.md):
-   - The token must have these permissions:
-     - **cloud-connect** scope
-     - **Read public repositories** permission
-     - **Repository access** with **Image push** permission for the target repository:
-       - Expand the **Repository** drop-down.
-       - Select **Add repository** and choose your target repository.
-       - Set the **Image push** permission for the repository.
+- Create an [organization access token (OAT)](../security/for-admins/access-tokens.md). The token must have these permissions:
+    1. **cloud-connect** scope
+    2. **Read public repositories** permission
+    3. **Repository access** with **Image push** permission for the target repository:
+        - Expand the **Repository** drop-down.
+        - Select **Add repository** and choose your target repository.
+        - Set the **Image push** permission for the repository.
 
 If you are not an organization administrator:
 
 - Ask your organization administrator for an access token with the permissions listed above, or use a personal access token.
 
 #### For personal accounts
 
-1. Create a [personal access token (PAT)](/security/for-developers/access-tokens/):
-   - Create a new token with **Read & write** access.
-     - Note: Building with Docker Build Cloud only requires read access, but you need write access to push images to a Docker Hub repository.
+- Create a [personal access token (PAT)](/security/for-developers/access-tokens/) with the following permissions:
+   1. **Read & write** access.
+        - Note: Building with Docker Build Cloud only requires read access, but you need write access to push images to a Docker Hub repository.
 
 
 ## CI platform examples
 
 > [!NOTE]
 >
-> In your CI/CD configuration, set the following variables:
-> - `DOCKER_PAT` — your access token (PAT or OAT)
-> - `DOCKER_USER` — your Docker Hub username (for PAT) or organization name (for OAT)
+> In your CI/CD configuration, set the following variables/secrets:
+> - `DOCKER_ACCESS_TOKEN` — your access token (PAT or OAT). Use a secret to store the token.
+> - `DOCKER_ACCOUNT` — your Docker Hub organization name (for OAT) or username (for PAT)
+> - `CLOUD_BUILDER_NAME` — the name of the cloud builder you created in the [Docker Build Cloud Dashboard](https://app.docker.com/build/)
 >
 > This ensures your builds authenticate correctly with Docker Build Cloud.
 
@@ -92,20 +92,20 @@ jobs:
       - name: Login to Docker Hub
         uses: docker/login-action@v3
         with:
-          username: ${{ vars.DOCKER_USER }}
-          password: ${{ secrets.DOCKER_PAT }}
+          username: ${{ vars.DOCKER_ACCOUNT }}
+          password: ${{ secrets.DOCKER_ACCESS_TOKEN }}
 
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
         with:
           driver: cloud
-          endpoint: "<ORG>/default"
+          endpoint: "${{ vars.DOCKER_ACCOUNT }}/${{ vars.CLOUD_BUILDER_NAME }}" # for example, "acme/default"
           install: true
 
       - name: Build and push
         uses: docker/build-push-action@v6
         with:
-          tags: "<IMAGE>"
+          tags: "<IMAGE>" # for example, "acme/my-image:latest"
           # For pull requests, export results to the build cache.
           # Otherwise, push to a registry.
           outputs: ${{ github.event_name == 'pull_request' && 'type=cacheonly' || 'type=registry' }}
@@ -120,19 +120,20 @@ default:
     - docker:24-dind
   before_script:
     - docker info
-    - echo "$DOCKER_PAT" | docker login --username "$DOCKER_USER" --password-stdin
+    - echo "$DOCKER_ACCESS_TOKEN" | docker login --username "$DOCKER_ACCOUNT" --password-stdin
     - |
       apk add curl jq
       ARCH=${CI_RUNNER_EXECUTABLE_ARCH#*/}
       BUILDX_URL=$(curl -s https://raw.githubusercontent.com/docker/actions-toolkit/main/.github/buildx-lab-releases.json | jq -r ".latest.assets[] | select(endswith(\"linux-$ARCH\"))")
       mkdir -vp ~/.docker/cli-plugins/
       curl --silent -L --output ~/.docker/cli-plugins/docker-buildx $BUILDX_URL
       chmod a+x ~/.docker/cli-plugins/docker-buildx
-    - docker buildx create --use --driver cloud ${DOCKER_ORG}/default
+    - docker buildx create --use --driver cloud ${DOCKER_ACCOUNT}/${CLOUD_BUILDER_NAME}
 
 variables:
   IMAGE_NAME: <IMAGE>
-  DOCKER_ORG: <ORG>
+  DOCKER_ACCOUNT: <DOCKER_ACCOUNT> # your Docker Hub organization name (or username when using a personal account)
+  CLOUD_BUILDER_NAME: <CLOUD_BUILDER_NAME> # the name of the cloud builder you created in the [Docker Build Cloud Dashboard](https://app.docker.com/build/)
 
 # Build multi-platform image and push to a registry
 build_push:
@@ -176,8 +177,8 @@ jobs:
           curl --silent -L --output ~/.docker/cli-plugins/docker-buildx $BUILDX_URL
           chmod a+x ~/.docker/cli-plugins/docker-buildx
 
-      - run: echo "$DOCKER_PAT" | docker login --username $DOCKER_USER --password-stdin
-      - run: docker buildx create --use --driver cloud "<ORG>/default"
+      - run: echo "$DOCKER_ACCESS_TOKEN" | docker login --username $DOCKER_ --password-stdin
+      - run: docker buildx create --use --driver cloud "${DOCKER_ACCOUNT}/${CLOUD_BUILDER_NAME}"
 
       - run: |
           docker buildx build \
@@ -199,8 +200,8 @@ jobs:
           curl --silent -L --output ~/.docker/cli-plugins/docker-buildx $BUILDX_URL
           chmod a+x ~/.docker/cli-plugins/docker-buildx
 
-      - run: echo "$DOCKER_PAT" | docker login --username $DOCKER_USER --password-stdin
-      - run: docker buildx create --use --driver cloud "<ORG>/default"
+      - run: echo "$DOCKER_ACCESS_TOKEN" | docker login --username $DOCKER_ --password-stdin
+      - run: docker buildx create --use --driver cloud "${DOCKER_ACCOUNT}/${CLOUD_BUILDER_NAME}"
 
       - run: |
           docker buildx build \
@@ -231,24 +232,25 @@ Add the following `environment` hook agent's hook directory:
 set -euo pipefail
 
 if [[ "$BUILDKITE_PIPELINE_NAME" == "build-push-docker" ]]; then
- export DOCKER_PAT="<DOCKER_PERSONAL_ACCESS_TOKEN>"
+ export DOCKER_ACCESS_TOKEN="<DOCKER_ACCESS_TOKEN>"
 fi
 ```
 
 Create a `pipeline.yml` that uses the `docker-login` plugin:
 
 ```yaml
 env:
-  DOCKER_ORG: <ORG>
+  DOCKER_ACCOUNT: <DOCKER_ACCOUNT> # your Docker Hub organization name (or username when using a personal account)
+  CLOUD_BUILDER_NAME: <CLOUD_BUILDER_NAME> # the name of the cloud builder you created in the [Docker Build Cloud Dashboard](https://app.docker.com/build/)
   IMAGE_NAME: <IMAGE>
 
 steps:
   - command: ./build.sh
     key: build-push
     plugins:
       - docker-login#v2.1.0:
-          username: <DOCKER_USER>
-          password-env: DOCKER_PAT # the variable name in the environment hook
+          username: DOCKER_ACCOUNT
+          password-env: DOCKER_ACCESS_TOKEN # the variable name in the environment hook
 ```
 
 Create the `build.sh` script:
@@ -277,7 +279,7 @@ curl --silent -L --output $DOCKER_DIR/cli-plugins/docker-buildx $BUILDX_URL
 chmod a+x ~/.docker/cli-plugins/docker-buildx
 
 # Connect to your builder and set it as the default builder
-docker buildx create --use --driver cloud "$DOCKER_ORG/default"
+docker buildx create --use --driver cloud "${DOCKER_ACCOUNT}/${CLOUD_BUILDER_NAME}"
 
 # Cache-only image build
 docker buildx build \
@@ -302,9 +304,9 @@ pipeline {
 
   environment {
     ARCH = 'amd64'
-    DOCKER_PAT = credentials('docker-personal-access-token')
-    DOCKER_USER = credentials('docker-username')
-    DOCKER_ORG = '<ORG>'
+    DOCKER_ACCESS_TOKEN = credentials('docker-access-token')
+    DOCKER_ACCOUNT = credentials('docker-account')
+    CLOUD_BUILDER_NAME = '<CLOUD_BUILDER_NAME>'
     IMAGE_NAME = '<IMAGE>'
   }
 
@@ -317,8 +319,8 @@ pipeline {
         sh 'mkdir -vp ~/.docker/cli-plugins/'
         sh 'curl --silent -L --output ~/.docker/cli-plugins/docker-buildx $BUILDX_URL'
         sh 'chmod a+x ~/.docker/cli-plugins/docker-buildx'
-        sh 'echo "$DOCKER_PAT" | docker login --username $DOCKER_USER --password-stdin'
-        sh 'docker buildx create --use --driver cloud "$DOCKER_ORG/default"'
+        sh 'echo "$DOCKER_ACCESS_TOKEN" | docker login --username $DOCKER_ACCOUNT --password-stdin'
+        sh 'docker buildx create --use --driver cloud "${DOCKER_ACCOUNT}/${CLOUD_BUILDER_NAME}"'
         // Cache-only build
         sh 'docker buildx build --platform linux/amd64,linux/arm64 --tag "$IMAGE_NAME" --output type=cacheonly .'
         // Build and push a multi-platform image
@@ -340,18 +342,18 @@ services:
 
 env:
   global:
-    - IMAGE_NAME=username/repo
+    - IMAGE_NAME=<IMAGE> # for example, "acme/my-image:latest"
 
 before_install: |
-  echo "$DOCKER_PAT" | docker login --username "$DOCKER_USER" --password-stdin
+  echo "$DOCKER_ACCESS_TOKEN" | docker login --username "$DOCKER_ACCOUNT" --password-stdin
 
 install: |
   set -e 
   BUILDX_URL=$(curl -s https://raw.githubusercontent.com/docker/actions-toolkit/main/.github/buildx-lab-releases.json | jq -r ".latest.assets[] | select(endswith(\"linux-$TRAVIS_CPU_ARCH\"))")
   mkdir -vp ~/.docker/cli-plugins/
   curl --silent -L --output ~/.docker/cli-plugins/docker-buildx $BUILDX_URL
   chmod a+x ~/.docker/cli-plugins/docker-buildx
-  docker buildx create --use --driver cloud "<ORG>/default"
+  docker buildx create --use --driver cloud "${DOCKER_ACCOUNT}/${CLOUD_BUILDER_NAME}"
 
 script: |
   docker buildx build \
@@ -363,9 +365,8 @@ script: |
 ### BitBucket Pipelines 
 
 ```yaml
-# Prerequisites: $DOCKER_USER, $DOCKER_PAT setup as deployment variables
+# Prerequisites: $DOCKER_ACCOUNT, $CLOUD_BUILDER_NAME, $DOCKER_ACCESS_TOKEN setup as deployment variables
 # This pipeline assumes $BITBUCKET_REPO_SLUG as the image name
-# Replace <ORG> in the `docker buildx create` command with your Docker org
 
 image: atlassian/default-image:3
 
@@ -379,8 +380,8 @@ pipelines:
           - BUILDX_URL=$(curl -s https://raw.githubusercontent.com/docker/actions-toolkit/main/.github/buildx-lab-releases.json | jq -r ".latest.assets[] | select(endswith(\"linux-$ARCH\"))")
           - curl --silent -L --output ~/.docker/cli-plugins/docker-buildx $BUILDX_URL
           - chmod a+x ~/.docker/cli-plugins/docker-buildx
-          - echo "$DOCKER_PAT" | docker login --username $DOCKER_USER --password-stdin
-          - docker buildx create --use --driver cloud "<ORG>/default"
+          - echo "$DOCKER_ACCESS_TOKEN" | docker login --username $DOCKER_ACCOUNT --password-stdin
+          - docker buildx create --use --driver cloud "${DOCKER_ACCOUNT}/${CLOUD_BUILDER_NAME}"
           - IMAGE_NAME=$BITBUCKET_REPO_SLUG
           - docker buildx build
             --platform linux/amd64,linux/arm64
@@ -404,11 +405,11 @@ mkdir -vp ~/.docker/cli-plugins/
 curl --silent -L --output ~/.docker/cli-plugins/docker-buildx $BUILDX_URL
 chmod a+x ~/.docker/cli-plugins/docker-buildx
 
-# Login to Docker Hub. For security reasons $DOCKER_PAT should be a Personal Access Token. See https://docs.docker.com/build-cloud/ci/#creating-access-tokens
-echo "$DOCKER_PAT" | docker login --username $DOCKER_USER --password-stdin
+# Login to Docker Hub with an access token. See https://docs.docker.com/build-cloud/ci/#creating-access-tokens
+echo "$DOCKER_ACCESS_TOKEN" | docker login --username $DOCKER_ACCOUNT --password-stdin
 
 # Connect to your builder and set it as the default builder
-docker buildx create --use --driver cloud "<ORG>/default"
+docker buildx create --use --driver cloud "${DOCKER_ACCOUNT}/${CLOUD_BUILDER_NAME}"
 
 # Cache-only image build
 docker buildx build \
@@ -449,11 +450,11 @@ curl --silent -L --output ~/.docker/cli-plugins/docker-compose $COMPOSE_URL
 chmod a+x ~/.docker/cli-plugins/docker-buildx
 chmod a+x ~/.docker/cli-plugins/docker-compose
 
-# Login to Docker Hub. For security reasons $DOCKER_PAT should be a Personal Access Token. See https://docs.docker.com/build-cloud/ci/#creating-access-tokens
-echo "$DOCKER_PAT" | docker login --username $DOCKER_USER --password-stdin
+# Login to Docker Hub with an access token. See https://docs.docker.com/build-cloud/ci/#creating-access-tokens
+echo "$DOCKER_ACCESS_TOKEN" | docker login --username $DOCKER_ACCOUNT --password-stdin
 
 # Connect to your builder and set it as the default builder
-docker buildx create --use --driver cloud "<ORG>/default"
+docker buildx create --use --driver cloud "${DOCKER_ACCOUNT}/${CLOUD_BUILDER_NAME}"
 
 # Build the image build
 docker compose build

content/manuals/build-cloud/setup.md

@@ -16,7 +16,8 @@ environment.
 To get started with Docker Build Cloud, you need to:
 
 - Download and install Docker Desktop version 4.26.0 or later.
-- Sign up for a Docker Build Cloud subscription in the [Docker Build Cloud Dashboard](https://app.docker.com/build/).
+- Create a cloud builder on the [Docker Build Cloud Dashboard](https://app.docker.com/build/).
+  - When you create the builder, choose a name for it (for example, `default`). You will use this name as `BUILDER_NAME` in the CLI steps below.
 
 ### Use Docker Build Cloud without Docker Desktop
 
@@ -50,9 +51,17 @@ command, or using the Docker Desktop settings GUI.
    $ docker buildx create --driver cloud <ORG>/<BUILDER_NAME>
    ```
 
-   Replace `ORG` with the Docker Hub namespace of your Docker organization.
+   Replace `<ORG>` with the Docker Hub namespace of your Docker organization (or your username if you are using a personal account), and `<BUILDER_NAME>` with the name you chose when creating the builder in the dashboard.
+
+   This creates a local instance of the cloud builder named `cloud-ORG-BUILDER_NAME`.
+
+   > [!NOTE]
+   >
+   > If your organization is `acme` and you named your builder `default`, use:
+   > ```console
+   > $ docker buildx create --driver cloud acme/default
+   > ```
 
-This creates a builder named `cloud-ORG-BUILDER_NAME`.
 
 {{< /tab >}}
 {{< tab name="Docker Desktop" >}}