diff --git a/content/manuals/_index.md b/content/manuals/_index.md index cef5f4a5bbe..29456e5efcf 100644 --- a/content/manuals/_index.md +++ b/content/manuals/_index.md @@ -53,6 +53,10 @@ params: description: Secure, minimal base images for trusted software delivery. icon: /icons/dhi.svg link: /dhi/ + - title: Docker Cloud + description: Build and run containers in the cloud. + icon: cloud + link: /cloud/ - title: Build Cloud description: Build your images faster in the cloud. icon: /icons/logo-build-cloud.svg diff --git a/content/manuals/admin/organization/manage-products.md b/content/manuals/admin/organization/manage-products.md index b20004ed23f..b6a9de0faa3 100644 --- a/content/manuals/admin/organization/manage-products.md +++ b/content/manuals/admin/organization/manage-products.md @@ -16,6 +16,7 @@ product, including how to set up and configure them, see the following manuals: - [Docker Hub](../../docker-hub/_index.md) - [Docker Scout](../../scout/_index.md) - [Testcontainers Cloud](https://testcontainers.com/cloud/docs/#getting-started) +- [Docker Cloud](../../cloud/_index.md) ## Manage access to Docker products @@ -26,11 +27,19 @@ for all users. The included products are: - Docker Build Cloud - Docker Desktop - Docker Scout +- Docker Cloud Testcontainers Cloud is not enabled by default. To enable Testcontainers Cloud, see the Testcontainers [Getting Started](https://testcontainers.com/cloud/docs/#getting-started) guide. The following sections describe how to enable or disable access for these products. +### Manage access to Docker Cloud + +To manage access to Docker Cloud, sign in to [Docker +Home](http://app.docker.com/) as an organization owner, select **Docker +Cloud**, select **Cloud settings**, and then manage access under **Lock Docker +Cloud**. + ### Manage access to Docker Build Cloud To learn how to initially set up and configure Docker Build Cloud, sign in to @@ -105,5 +114,8 @@ View usage for the products on the following pages: - Docker Desktop: View the **Insights** page in the [Docker Admin Console](https://app.docker.com/admin). For more details, see [Insights](./insights.md). +- Docker Cloud: View the **Cloud overview** page in the Docker Cloud + Dashboard. + If your usage exceeds your subscription amount, you can [scale your subscription](../../subscription/scale.md) to meet your needs. \ No newline at end of file diff --git a/content/manuals/cloud/_index.md b/content/manuals/cloud/_index.md new file mode 100644 index 00000000000..c42c109a5d1 --- /dev/null +++ b/content/manuals/cloud/_index.md @@ -0,0 +1,74 @@ +--- +title: Docker Cloud +weight: 15 +description: Find documentation on Docker Cloud to help you build and run your container images faster, both locally and in CI +keywords: build, cloud, cloud build, remote builder +params: + sidebar: + group: Products + badge: + color: blue + text: Beta + +grid: + +- title: Quickstart + description: Get up and running with Docker Cloud in just a few steps. + icon: rocket_launch + link: /cloud/quickstart/ + +- title: About + description: Learn about Docker Cloud and how it works. + icon: info + link: /cloud/about/ + +- title: Configure + description: Set up and customize your cloud build environments. + icon: tune + link: /cloud/configuration/ + +- title: Build + description: Use Docker Cloud to build container images from the CLI or Docker Desktop. + icon: build + link: /cloud/build/ + +- title: Build in CI + description: Use Docker Cloud to build container images in continuous integration workflows. + icon: build + link: /cloud/ci-build/ + + + +- title: Usage + description: Learn about Docker Cloud usage and how to monitor your cloud resources. + icon: monitor_heart + link: /cloud/usage/ + +- title: Optimize + description: Improve performance, caching, and cost efficiency in Docker Cloud. + icon: speed + link: /cloud/optimize/ + +- title: Troubleshoot + description: Learn how to troubleshoot issues with Docker Cloud. + icon: bug_report + link: /cloud/troubleshoot/ + +--- + +{{< summary-bar feature_name="Docker Cloud" >}} + +Docker Cloud is a fully managed service that lets you build and run containers +in the cloud using the Docker tools you already know. Whether you're working +locally on Docker Desktop or in CI, Docker Cloud provides scalable +infrastructure for fast, consistent builds and compute-intensive workloads like +running LLMs or machine learning pipelines. + +You can use Docker Cloud in Cloud mode to offload builds and container runs from +Docker Desktop, or use it for builds only without running containers in the +cloud. + +In the following topics, learn about Docker Cloud, how to set it up, use it for your workflows, and +troubleshoot common issues. + +{{< grid >}} \ No newline at end of file diff --git a/content/manuals/cloud/about.md b/content/manuals/cloud/about.md new file mode 100644 index 00000000000..526fb65bb1b --- /dev/null +++ b/content/manuals/cloud/about.md @@ -0,0 +1,152 @@ +--- +title: About Docker Cloud +linktitle: About +weight: 15 +description: Learn about Docker Cloud, its features, and how it works. +keywords: cloud, build, remote builder +--- + +Docker Cloud is a fully managed service for building and running containers in +the cloud using the Docker tools you already know, including Docker Desktop, the +Docker CLI, and Docker Compose. It extends your local development workflow into a +scalable, cloud-powered environment, so you can offload compute-heavy tasks, +accelerate builds, and securely manage container workloads across the software +lifecycle. + +Docker Cloud also supports GPU-accelerated instances, allowing you to +containerize and run compute-intensive workloads such as Docker Model Runner and +other machine learning or data processing tasks that benefit from GPU. + +You can use Docker Cloud in following ways: + +- In Cloud mode, where you use Docker Desktop with cloud-based resources. This + is ideal for virtual desktop environments (VDIs) where nested virtualization + isn't supported, or when you need more CPU, memory, or GPU than your local + machine can provide. In this mode, both builds and container runs happen in + the cloud, but Docker Desktop maintains a local-like experience. To get + started, see [Docker Cloud quickstart](/cloud/quickstart/). + +- For only builds, without running containers in the cloud. This lets you offload image + builds to Docker Cloud while continuing to run containers locally. It's useful + when you want faster, consistent builds but don’t need to run containers in + the cloud. To get started, see [Build with Docker Cloud](/cloud/build/). + +- In CI environments where builds are performed entirely in the cloud. This lets + you have fast, consistent, and scalable builds without the need to manage your + own runners or infrastructure. To get started, see [Use Docker Cloud in + CI](/cloud/ci-build/). + +## Key features + +Docker Cloud includes the following capabilities to support modern container +workflows: + +- Cloud-based builds: Execute builds on remote, fully managed BuildKit instances + with native support for multi-platform output. +- GPU acceleration: Use NVIDIA L4 GPU-backed environments for machine learning, + media processing, and other compute-intensive workloads. +- Ephemeral cloud runners: Automatically provision and tear down cloud + environments for each container session. +- Shared build cache: Speed up build times across machines and teammates with a + smart, shared cache layer. +- Hybrid workflows: Seamlessly transition between local and remote execution + using Docker Desktop, CLI, or CI tools. +- Secure communication: Use encrypted tunnels between Docker Desktop and cloud + environments with support for secure secrets and image pulling. +- CI/CD integration: Trigger builds in CI pipelines using Buildx, GitHub + Actions, or prebuilt integrations. +- Port forwarding and bind mounts: Retain a local development experience even + when running containers in the cloud. +- VDI-friendly: Use Docker Cloud in virtual desktop environments or systems that + don't support nested virtualization. + +## Why use Docker Cloud? + +Docker Cloud is designed to support modern development teams working across +local and cloud environments. It helps you: + +- Use the same Docker workflows locally and in the cloud +- Offload builds to fast, high-performance infrastructure +- Run containers that require more CPU, memory, or GPU than your local setup can + provide +- Run Docker Desktop in environments that don't support nested virtualization +- Speed up feedback loops by reducing wait times for builds and testing + environments +- Avoid managing custom infrastructure while retaining full control over how + containers are built and executed +- Ensure consistent, clean environments for every build or test +- Integrate easily with any CI system using simple scripts or prebuilt actions + +Docker Cloud is ideal for hybrid teams that want to iterate quickly, test +reliably, and scale efficiently without compromising on developer experience. + +## How Docker Cloud works + +Docker Cloud replaces the need to build or run containers locally by connecting +Docker Desktop and your CI pipelines to secure, dedicated cloud resources. + +### Building with Docker Cloud + +When you use Docker Cloud for builds, the `docker buildx build` command sends +the build request to a remote BuildKit instance in the cloud, instead of +executing it locally. Your workflow stays the same, only the execution +environment changes. + +The build runs on infrastructure provisioned and managed by Docker: + +- Each cloud builder is an isolated Amazon EC2 instance with its own EBS volume +- Remote builders use a shared cache to speed up builds across machines and + teammates +- Builds support native multi-platform output (for example, `linux/amd64`, + `linux/arm64`) +- Build results are encrypted in transit and sent to your specified destination + (such as a registry or local image store) + +Docker Cloud manages the lifecycle of builders automatically. There's no need to +provision or maintain infrastructure. + +> [!NOTE] +> +> Docker Cloud builders are currently hosted in the US East region. Users in +> other regions may experience increased latency. + +### Running containers with Docker Cloud + +When you use Docker Cloud to run containers, a Docker Desktop creates a secure +SSH tunnel to a Docker daemon running in the cloud. Your containers are started +and managed entirely in that remote environment. + +Here's what happens: + +1. Docker Desktop connects to the cloud and triggers container creation. +2. Docker Cloud pulls the required images and starts containers in the cloud. +3. The connection stays open while the containers run. +4. When the containers stop running, the environment shuts down and is cleaned + up automatically. + +This setup avoids the overhead of running containers locally and enables fast, +reliable containers even on low-powered machines, including machines that do not +support nested virtualization. This makes Docker Cloud ideal for developers +using environments such as virtual desktops, cloud-hosted development machines, +or older hardware. + +Docker Cloud also supports GPU-accelerated workloads. Containers that require +GPU access can run on cloud instances provisioned with NVIDIA L4 GPUs for +efficient AI inferencing, media processing, and general-purpose GPU +acceleration. This enables compute-heavy workflows such as model evaluation, +image processing, and hardware-accelerated CI tests to run seamlessly in the +cloud. + +Despite running remotely, features like bind mounts and port forwarding continue +to work seamlessly, providing a local-like experience from within Docker Desktop +and the CLI. + +Docker Cloud provisions an ephemeral cloud environment for each session. The +environment remains active while you are interacting with Docker Desktop or +actively using containers. If no activity is detected for about 30 minutes, the +session shuts down automatically. This includes any containers, images, or +volumes in that environment, which are deleted when the session ends. + +## What's next + +Get hands-on with Docker Cloud by following the [Docker Cloud quickstart](/cloud/quickstart/). \ No newline at end of file diff --git a/content/manuals/cloud/build.md b/content/manuals/cloud/build.md new file mode 100644 index 00000000000..a73895e8775 --- /dev/null +++ b/content/manuals/cloud/build.md @@ -0,0 +1,259 @@ +--- +title: Build with Docker Cloud +linktitle: Build +weight: 25 +description: Build container images using Docker Cloud from the CLI or Docker Desktop. +keywords: build, cloud build, buildx, builder, usage +--- + +> [!IMPORTANT] +> +> This section applies only if you want to use Docker Cloud for builds, +> without running containers in the cloud. +> +> If you want to use Docker Cloud for both builds and container runs, refer to +> [Docker Cloud quickstart](/cloud/quickstart/). + +Before you can start using Docker Cloud for builds, you must set it up by adding the +builder to your local environment. + + +## Set up + +To use Docker Cloud without Docker Desktop, you must download and install +a version of Buildx with support for Docker Cloud (the `cloud` driver). +You can find compatible Buildx binaries on the releases page of +[this repository](https://github.com/docker/buildx-desktop). + +If you plan on building with Docker Cloud using the `docker compose build` +command, you also need a version of Docker Compose that supports Docker Cloud. +You can find compatible Docker Compose binaries on the releases page of [this +repository](https://github.com/docker/compose-desktop). + +You can add a cloud builder using the CLI, with the `docker buildx create` +command, or using the Docker Desktop settings GUI. + +{{< tabs >}} +{{< tab name="CLI" >}} + +1. Sign in to your Docker account. + + ```console + $ docker login + ``` + +2. Add the cloud builder endpoint. + + ```console + $ docker buildx create --driver cloud / + ``` + + Replace `ORG` with the Docker Hub namespace of your Docker organization. + +This creates a builder named `cloud-ORG-BUILDER_NAME`. + +{{< /tab >}} +{{< tab name="Docker Desktop" >}} + +1. Sign in to your Docker account using the **Sign in** button in Docker Desktop. + +2. Open the Docker Desktop settings and navigate to the **Builders** tab. + +3. Under **Available builders**, select **Connect to builder**. + +{{< /tab >}} +{{< /tabs >}} + +The builder has native support for the `linux/amd64` and `linux/arm64` +architectures. This gives you a high-performance build cluster for building +multi-platform images natively. + +### Firewall configuration + +To use Docker Cloud behind a firewall, ensure that your firewall allows +traffic to the following addresses: + +- `3.211.38.21` +- `https://auth.docker.io` +- `https://build-cloud.docker.com` +- `https://hub.docker.com` + + +## Use Docker Cloud for builds + +To build using Docker Cloud, invoke a build command and specify the name of the +builder using the `--builder` flag. + +```console +$ docker buildx build --builder cloud-- --tag . +``` + +## Use by default + +If you want to use Docker Cloud without having to specify the `--builder` flag +each time, you can set it as the default builder. + +{{< tabs group="ui" >}} +{{< tab name="CLI" >}} + +Run the following command: + +```console +$ docker buildx use cloud-- --global +``` + +{{< /tab >}} +{{< tab name="Docker Desktop" >}} + +1. Open the Docker Desktop settings and navigate to the **Builders** tab. +2. Find the cloud builder under **Available builders**. +3. Open the drop-down menu and select **Use**. + + ![Selecting the cloud builder as default using the Docker Desktop GUI](/build/images/set-default-builder-gui.webp) + +{{< /tab >}} +{{< /tabs >}} + +Changing your default builder with `docker buildx use` only changes the default +builder for the `docker buildx build` command. The `docker build` command still +uses the `default` builder, unless you specify the `--builder` flag explicitly. + +If you use build scripts, such as `make`, we recommend that you update your +build commands from `docker build` to `docker buildx build`, to avoid any +confusion with regards to builder selection. Alternatively, you can run `docker +buildx install` to make the default `docker build` command behave like `docker +buildx build`, without discrepancies. + +## Use with Docker Compose + +To build with Docker Cloud using `docker compose build`, first set the +cloud builder as your selected builder, then run your build. + +> [!NOTE] +> +> Make sure you're using a supported version of Docker Compose, see +> [Set up](#set-up). + +```console +$ docker buildx use cloud-- +$ docker compose build +``` + +In addition to `docker buildx use`, you can also use the `docker compose build +--builder` flag or the [`BUILDX_BUILDER` environment +variable](/manuals/build/building/variables.md#buildx_builder) to select the cloud builder. + +## Loading build results + +Building with `--tag` loads the build result to the local image store +automatically when the build finishes. To build without a tag and load the +result, you must pass the `--load` flag. + +Loading the build result for multi-platform images is not supported. Use the +`docker buildx build --push` flag when building multi-platform images to push +the output to a registry. + +```console +$ docker buildx build --builder cloud-- \ + --platform linux/amd64,linux/arm64 \ + --tag \ + --push . +``` + +If you want to build with a tag, but you don't want to load the results to your +local image store, you can export the build results to the build cache only: + +```console +$ docker buildx build --builder cloud-- \ + --platform linux/amd64,linux/arm64 \ + --tag \ + --output type=cacheonly . +``` + +## Multi-platform builds + +To run multi-platform builds, you must specify all of the platforms that you +want to build for using the `--platform` flag. + +```console +$ docker buildx build --builder cloud-- \ + --platform linux/amd64,linux/arm64 \ + --tag \ + --push . +``` + +If you don't specify the platform, the cloud builder automatically builds for the +architecture matching your local environment. + +To learn more about building for multiple platforms, refer to [Multi-platform +builds](/build/building/multi-platform/). + +## Cloud builds in Docker Desktop + +The Docker Desktop [Builds view](/desktop/use-desktop/builds/) works with +Docker Cloud out of the box. This view can show information about not only your +own builds, but also builds initiated by your team members using the same +builder. + +Teams using a shared builder get access to information such as: + +- Ongoing and completed builds +- Build configuration, statistics, dependencies, and results +- Build source (Dockerfile) +- Build logs and errors + +This lets you and your team work collaboratively on troubleshooting and +improving build speeds, without having to send build logs and benchmarks back +and forth between each other. + +## Use secrets with Docker Cloud + +To use build secrets with Docker Cloud, +such as authentication credentials or tokens, +use the `--secret` and `--ssh` CLI flags for the `docker buildx` command. +The traffic is encrypted and secrets are never stored in the build cache. + +> [!WARNING] +> +> If you're misusing build arguments to pass credentials, authentication +> tokens, or other secrets, you should refactor your build to pass the secrets using +> [secret mounts](/reference/cli/docker/buildx/build.md#secret) instead. +> Build arguments are stored in the cache and their values are exposed through attestations. +> Secret mounts don't leak outside of the build and are never included in attestations. + +For more information, refer to: + +- [`docker buildx build --secret`](/reference/cli/docker/buildx/build/#secret) +- [`docker buildx build --ssh`](/reference/cli/docker/buildx/build/#ssh) + +## Managing build cache + +You don't need to manage Docker Cloud cache manually. +The system manages it for you through [garbage collection](/build/cache/garbage-collection/). + +Old cache is automatically removed if you hit your storage limit. +You can check your current cache state using the +[`docker buildx du` command](/reference/cli/docker/buildx/du/). + +To clear the builder's cache manually, +use the [`docker buildx prune` command](/reference/cli/docker/buildx/prune/). +This works like pruning the cache for any other builder. + +> [!WARNING] +> +> Pruning a cloud builder's cache also removes the cache for other team members +> using the same builder. + +## Unset Docker Cloud as the default builder + +If you've set a cloud builder as the default builder +and want to revert to the default `docker` builder, +run the following command: + +```console +$ docker context use default +``` + +This doesn't remove the builder from your system. +It only changes the builder that's automatically selected to run your builds. + diff --git a/content/manuals/cloud/ci-build.md b/content/manuals/cloud/ci-build.md new file mode 100644 index 00000000000..27b5015702f --- /dev/null +++ b/content/manuals/cloud/ci-build.md @@ -0,0 +1,465 @@ +--- +title: Use Docker Cloud to build images in CI +linktitle: Build in CI +weight: 30 +description: Learn how to integrate Docker Cloud into your CI pipeline. +keywords: cloud, ci, build, buildx, builder, usage +--- + +Using Docker Cloud in CI for builds can speed up your build pipelines, which +means less time spent waiting and context switching. You control your CI +workflows as usual, and delegate the build execution to Docker Cloud. + +Building with Docker Cloud in CI involves the following steps: + +1. Sign in to a Docker account. +2. Set up Buildx and connect to the builder. +3. Run the build. + +When using Docker Cloud in CI, it's recommended that you push the result to a +registry directly, rather than loading the image and then pushing it. Pushing +directly speeds up your builds and avoids unnecessary file transfers. + +If you just want to build and discard the output, export the results to the +build cache or build without tagging the image. When you use Docker Cloud, +Buildx automatically loads the build result if you build a tagged image. + +> [!NOTE] +> +> Builds on Docker Cloud have a timeout limit of 90 minutes. Builds that +> run for longer than 90 minutes are automatically cancelled. + +## Setting up credentials for CI/CD + +To enable your CI/CD system to build and push images using Docker 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.md) + and set `DOCKER_USER` 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. + +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 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) +> +> This ensures your builds authenticate correctly with Docker Cloud. + +### GitHub Actions + +```yaml +name: ci + +on: + push: + branches: + - "main" + +jobs: + docker: + runs-on: ubuntu-latest + steps: + - name: Login to Docker Hub + uses: docker/login-action@v3 + with: + username: ${{ vars.DOCKER_USER }} + password: ${{ secrets.DOCKER_PAT }} + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + with: + driver: cloud + endpoint: "/default" + install: true + + - name: Build and push + uses: docker/build-push-action@v6 + with: + tags: "" + # For pull requests, export results to the build cache. + # Otherwise, push to a registry. + outputs: ${{ github.event_name == 'pull_request' && 'type=cacheonly' || 'type=registry' }} +``` + +### GitLab + +```yaml +default: + image: docker:24-dind + services: + - docker:24-dind + before_script: + - docker info + - echo "$DOCKER_PAT" | docker login --username "$DOCKER_USER" --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 + +variables: + IMAGE_NAME: + DOCKER_ORG: + +# Build multi-platform image and push to a registry +build_push: + stage: build + script: + - | + docker buildx build \ + --platform linux/amd64,linux/arm64 \ + --tag "${IMAGE_NAME}:${CI_COMMIT_SHORT_SHA}" \ + --push . + +# Build an image and discard the result +build_cache: + stage: build + script: + - | + docker buildx build \ + --platform linux/amd64,linux/arm64 \ + --tag "${IMAGE_NAME}:${CI_COMMIT_SHORT_SHA}" \ + --output type=cacheonly \ + . +``` + +### Circle CI + +```yaml +version: 2.1 + +jobs: + # Build multi-platform image and push to a registry + build_push: + machine: + image: ubuntu-2204:current + steps: + - checkout + + - run: | + mkdir -vp ~/.docker/cli-plugins/ + ARCH=amd64 + 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 + + - run: echo "$DOCKER_PAT" | docker login --username $DOCKER_USER --password-stdin + - run: docker buildx create --use --driver cloud "/default" + + - run: | + docker buildx build \ + --platform linux/amd64,linux/arm64 \ + --push \ + --tag "" . + + # Build an image and discard the result + build_cache: + machine: + image: ubuntu-2204:current + steps: + - checkout + + - run: | + mkdir -vp ~/.docker/cli-plugins/ + ARCH=amd64 + 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 + + - run: echo "$DOCKER_PAT" | docker login --username $DOCKER_USER --password-stdin + - run: docker buildx create --use --driver cloud "/default" + + - run: | + docker buildx build \ + --tag temp \ + --output type=cacheonly \ + . + +workflows: + pull_request: + jobs: + - build_cache + release: + jobs: + - build_push +``` + +### Buildkite + +The following example sets up a Buildkite pipeline using Docker Cloud. The +example assumes that the pipeline name is `build-push-docker` and that you +manage the Docker access token using environment hooks, but feel free to adapt +this to your needs. + +Add the following `environment` hook agent's hook directory: + +```bash +#!/bin/bash +set -euo pipefail + +if [[ "$BUILDKITE_PIPELINE_NAME" == "build-push-docker" ]]; then + export DOCKER_PAT="" +fi +``` + +Create a `pipeline.yml` that uses the `docker-login` plugin: + +```yaml +env: + DOCKER_ORG: + IMAGE_NAME: + +steps: + - command: ./build.sh + key: build-push + plugins: + - docker-login#v2.1.0: + username: + password-env: DOCKER_PAT # the variable name in the environment hook +``` + +Create the `build.sh` script: + +```bash +DOCKER_DIR=/usr/libexec/docker + +# Get download link for latest buildx binary. +# Set $ARCH to the CPU architecture (e.g. amd64, arm64) +UNAME_ARCH=`uname -m` +case $UNAME_ARCH in + aarch64) + ARCH="arm64"; + ;; + amd64) + ARCH="amd64"; + ;; + *) + ARCH="amd64"; + ;; +esac +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\"))") + +# Download docker buildx with Docker Cloud support +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" + +# Cache-only image build +docker buildx build \ + --platform linux/amd64,linux/arm64 \ + --tag "$IMAGE_NAME:$BUILDKITE_COMMIT" \ + --output type=cacheonly \ + . + +# Build, tag, and push a multi-arch docker image +docker buildx build \ + --platform linux/amd64,linux/arm64 \ + --push \ + --tag "$IMAGE_NAME:$BUILDKITE_COMMIT" \ + . +``` + +### Jenkins + +```groovy +pipeline { + agent any + + environment { + ARCH = 'amd64' + DOCKER_PAT = credentials('docker-personal-access-token') + DOCKER_USER = credentials('docker-username') + DOCKER_ORG = '' + IMAGE_NAME = '' + } + + stages { + stage('Build') { + environment { + BUILDX_URL = sh (returnStdout: true, script: 'curl -s https://raw.githubusercontent.com/docker/actions-toolkit/main/.github/buildx-lab-releases.json | jq -r ".latest.assets[] | select(endswith(\\"linux-$ARCH\\"))"').trim() + } + steps { + 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"' + // 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 + sh 'docker buildx build --platform linux/amd64,linux/arm64 --push --tag "$IMAGE_NAME" .' + } + } + } +} +``` + +### Travis CI + +```yaml +language: minimal +dist: jammy + +services: + - docker + +env: + global: + - IMAGE_NAME=username/repo + +before_install: | + echo "$DOCKER_PAT" | docker login --username "$DOCKER_USER" --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 "/default" + +script: | + docker buildx build \ + --platform linux/amd64,linux/arm64 \ + --push \ + --tag "$IMAGE_NAME" . +``` + +### BitBucket Pipelines + +```yaml +# Prerequisites: $DOCKER_USER, $DOCKER_PAT setup as deployment variables +# This pipeline assumes $BITBUCKET_REPO_SLUG as the image name +# Replace in the `docker buildx create` command with your Docker org + +image: atlassian/default-image:3 + +pipelines: + default: + - step: + name: Build multi-platform image + script: + - mkdir -vp ~/.docker/cli-plugins/ + - ARCH=amd64 + - 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 "/default" + - IMAGE_NAME=$BITBUCKET_REPO_SLUG + - docker buildx build + --platform linux/amd64,linux/arm64 + --push + --tag "$IMAGE_NAME" . + services: + - docker +``` + +### Shell script + +```bash +#!/bin/bash + +# Get download link for latest buildx binary. Set $ARCH to the CPU architecture (e.g. amd64, arm64) +ARCH=amd64 +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\"))") + +# Download docker buildx with Docker Cloud support +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 + +# Connect to your builder and set it as the default builder +docker buildx create --use --driver cloud "/default" + +# Cache-only image build +docker buildx build \ + --tag temp \ + --output type=cacheonly \ + . + +# Build, tag, and push a multi-arch docker image +docker buildx build \ + --platform linux/amd64,linux/arm64 \ + --push \ + --tag "" \ + . +``` + +### Docker Compose + +Use this implementation if you want to use `docker compose build` with +Docker Cloud in CI. + +```bash +#!/bin/bash + +# Get download link for latest buildx binary. Set $ARCH to the CPU architecture (e.g. amd64, arm64) +ARCH=amd64 +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\"))") +COMPOSE_URL=$(curl -sL \ + -H "Accept: application/vnd.github+json" \ + -H "Authorization: Bearer " \ + -H "X-GitHub-Api-Version: 2022-11-28" \ + https://api.github.com/repos/docker/compose-desktop/releases \ + | jq "[ .[] | select(.prerelease==false and .draft==false) ] | .[0].assets.[] | select(.name | endswith(\"linux-${ARCH}\")) | .browser_download_url") + +# Download docker buildx with Docker Cloud support +mkdir -vp ~/.docker/cli-plugins/ +curl --silent -L --output ~/.docker/cli-plugins/docker-buildx $BUILDX_URL +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 + +# Connect to your builder and set it as the default builder +docker buildx create --use --driver cloud "/default" + +# Build the image build +docker compose build +``` diff --git a/content/manuals/cloud/configuration.md b/content/manuals/cloud/configuration.md new file mode 100644 index 00000000000..8c5255149b4 --- /dev/null +++ b/content/manuals/cloud/configuration.md @@ -0,0 +1,124 @@ +--- +title: Configure Docker Cloud +linktitle: Configure +weight: 20 +description: Learn how to configure build settings for Docker Cloud. +keywords: cloud, configuration, settings, cloud builder, GPU, disk allocation, private resources, firewall +--- + +To use Docker Cloud, you must configure your environment based on how you're using it: + +- If you're using Cloud mode to build and run containers through Docker Desktop, + follow the [Docker Cloud quickstart](/cloud/quickstart/). +- If you're not using Cloud mode and only building with Docker Cloud, follow the + steps in [Build with Docker Cloud](/cloud/build/) or [Use Docker Cloud to build images in CI](/cloud/ci-build/). + +Both ways of using Docker Cloud can be further customized through **Cloud +settings** in the Docker Cloud dashboard. + +## Cloud settings + +The **Cloud settings** page in Docker Cloud dashboard lets you configure Docker Cloud and +GPU access, disk allocation, private resource access, and firewall settings for +your cloud builders in your organization. + +To view the **Cloud settings** page: + +1. Go to [Docker Home](https://app.docker.com/). +2. Select the account for which you want to manage Docker Cloud. +3. Select **Go to Docker Cloud** +4. Select **Cloud settings**. + +The following sections describe the available settings. + +### Cloud feature availability + +The **Allow Docker Cloud usage** option lets you control whether your +organization can use Docker Cloud features through Docker Desktop for hybrid +development. + +The **Allow GPU access** option lets you control whether your organization can +utilize GPU-accelerated containers when using Docker Cloud in Docker Desktop. + +### Lock Docker Cloud + +The **Lock access to Docker Cloud** setting removes the ability for anybody in +your organization to utilize any cloud resources or consume build or run +minutes. + +### Disk allocation + +The **Disk allocation** setting lets you control how much of the available +storage is dedicated to the build cache. A lower allocation increases storage +available for active builds. + +To make disk allocation changes, navigate to **Cloud settings** in Docker +Cloud and then adjust the **Disk allocation** slider to specify the +percentage of storage used for build caching. + +Any changes take effect immediately. + +> [!TIP] +> +> If you build very large images, consider allocating less storage for caching. + +### Build cache space + +Your subscription includes the following Build cache space: + +| Subscription | Build cache space | +|--------------|-------------------| +| Personal | N/A | +| Pro | 50GB | +| Team | 100GB | +| Business | 200GB | + +To get more Build cache space, [upgrade your subscription](/manuals/subscription/change.md). + +> [!TIP] +> +> If you build large images, consider allocating less storage for caching. + +### Private resource access + +Private resource access lets cloud builders pull images and packages from +private resources. This feature is useful when builds rely on self-hosted +artifact repositories or private OCI registries. + +For example, if your organization hosts a private [PyPI](https://pypi.org/) +repository on a private network, Docker Build Cloud would not be able to access +it by default, since the cloud builder is not connected to your private network. + +To enable your cloud builders to access your private resources, enter the host +name and port of your private resource and then select **Add**. + +#### Authentication + +If your internal artifacts require authentication, make sure that you +authenticate with the repository either before or during the build. For internal +package repositories for npm or PyPI, use [build +secrets](/manuals/build/building/secrets.md) to authenticate during the build. +For internal OCI registries, use `docker login` to authenticate before building. + +Note that if you use a private registry that requires authentication, you will +need to authenticate with `docker login` twice before building. This is because +the cloud builder needs to authenticate with Docker to use the cloud builder, +and then again to authenticate with the private registry. + +```console +$ echo $DOCKER_PAT | docker login docker.io -u --password-stdin +$ echo $REGISTRY_PASSWORD | docker login registry.example.com -u --password-stdin +$ docker build --builder --tag registry.example.com/ --push . +``` + +### Firewall + +Firewall settings let you restrict cloud builder egress traffic to specific IP +addresses. This helps enhance security by limiting external network egress from +the builder. + +1. Select **Enable firewall: Restrict cloud builder egress to specific public IP address**. + +2. Enter the IP address you want to allow. + +3. Select **Add** to apply the restriction. diff --git a/content/manuals/cloud/images/cloud-mode-stopped.png b/content/manuals/cloud/images/cloud-mode-stopped.png new file mode 100644 index 00000000000..dda35c7ecc5 Binary files /dev/null and b/content/manuals/cloud/images/cloud-mode-stopped.png differ diff --git a/content/manuals/cloud/images/cloud-mode.png b/content/manuals/cloud/images/cloud-mode.png new file mode 100644 index 00000000000..f8b1ceb60d2 Binary files /dev/null and b/content/manuals/cloud/images/cloud-mode.png differ diff --git a/content/manuals/cloud/optimize.md b/content/manuals/cloud/optimize.md new file mode 100644 index 00000000000..76b984b61ae --- /dev/null +++ b/content/manuals/cloud/optimize.md @@ -0,0 +1,83 @@ +--- +title: Optimize Docker Cloud usage +linktitle: Optimize usage +weight: 40 +description: Learn how to optimize your Docker Cloud usage. +keywords: cloud, optimize, performance, caching, cost efficiency +--- + +Docker Cloud runs your builds remotely, not on the machine where you invoke the +build. This means that files must be transferred from your local system to the +cloud over the network. + +Transferring files over the network introduces higher latency and lower +bandwidth compared to local transfers. To reduce these effects, Docker Cloud +includes several performance optimizations: + +- It uses attached storage volumes for build cache, which makes reading and writing cache fast. +- When pulling build results back to your local machine, it only transfers layers that changed since the previous build. + +Even with these optimizations, large projects or slower network connections can +lead to longer transfer times. Here are several ways to optimize your build +setup for Docker Cloud: + +- [Use `.dockerignore` files](#dockerignore-files) +- [Choose slim base images](#slim-base-images) +- [Use multi-stage builds](#multi-stage-builds) +- [Fetch remote files during the build](#fetch-remote-files-in-build) +- [Leverage multi-threaded tools](#multi-threaded-tools) + +For general Dockerfile tips, see [Building best practices](/manuals/build/building/best-practices.md). + +### Dockerignore files + +A [`.dockerignore` file](/manuals/build/concepts/context.md#dockerignore-files) +lets you specify which local files should *not* be included in the build +context. Files excluded by these patterns won’t be uploaded to Docker Cloud +during a build. + +Typical items to ignore: + +- `.git` – avoids transferring your version history. (Note: you won’t be able to run `git` commands in the build.) +- Build artifacts or locally generated binaries. +- Dependency folders such as `node_modules`, if those are restored in the build + process. + +As a rule of thumb, your `.dockerignore` should be similar to your `.gitignore`. + +### Slim base images + +Smaller base images in your `FROM` instructions can reduce final image size and +improve build performance. The [`alpine`](https://hub.docker.com/_/alpine) image +is a good example of a minimal base. + +For fully static binaries, you can use [`scratch`](https://hub.docker.com/_/scratch), which is an empty base image. + +### Multi-stage builds + +[Multi-stage builds](/build/building/multi-stage/) let you separate build-time +and runtime environments in your Dockerfile. This not only reduces the size of +the final image but also allows for parallel stage execution during the build. + +Use `COPY --from` to copy files from earlier stages or external images. This +approach helps minimize unnecessary layers and reduce final image size. + +### Fetch remote files in build + +When possible, download large files from the internet during the build itself +instead of bundling them in your local context. This avoids network transfer +from your client to Docker Cloud. + +You can do this using: + +- The Dockerfile [`ADD` instruction](/reference/dockerfile/#add) +- `RUN` commands like `wget`, `curl`, or `rsync` + +### Multi-threaded tools + +Some build tools, such as `make`, are single-threaded by default. If the tool +supports it, configure it to run in parallel. For example, use `make --jobs=4` +to run four jobs simultaneously. + +Taking advantage of available CPU resources in the cloud can significantly +improve build time. \ No newline at end of file diff --git a/content/manuals/cloud/quickstart.md b/content/manuals/cloud/quickstart.md new file mode 100644 index 00000000000..7412aa35aa5 --- /dev/null +++ b/content/manuals/cloud/quickstart.md @@ -0,0 +1,116 @@ +--- +title: Docker Cloud quickstart +linktitle: Quickstart +weight: 10 +description: Learn how to use Docker Cloud to build and run your container images faster, both locally and in CI. +keywords: cloud, quickstart, cloud mode, Docker Desktop, GPU support, cloud builder, usage +--- + +{{< summary-bar feature_name="Docker Cloud" >}} + +This quickstart helps you get started with Cloud mode for Docker Cloud. + +## Cloud mode + +Cloud mode uses cloud-based resources while maintaining your familiar +local Docker experience. When started, Docker Desktop offloads builds and +container runs to high-performance cloud infrastructure. + +This mode is especially useful in virtual desktop environments (VDIs) where +nested virtualization isn't supported, or when your local machine doesn't have +enough CPU, memory, or GPU to handle container workloads. Docker Cloud runs +everything in the cloud while preserving a local-like experience through Docker +Desktop. + +Despite running remotely, features like bind mounts and port forwarding continue +to work seamlessly, providing a local-like experience from within Docker Desktop +and the CLI. + +### Step 1: Start Docker Cloud + +1. Open the Docker Desktop Dashboard and sign in. +2. Toggle the **Start Cloud mode** switch ({{< inline-image + src="./images/cloud-mode-stopped.png" alt="Cloud mode icon" + >}}) in the header bar. + + When Docker Cloud is started, you'll see a cloud icon ({{< inline-image + src="./images/cloud-mode.png" alt="Cloud mode icon" + >}}), the Docker Desktop Dashboard appears purple, and **Cloud running** + appears in the left side of the footer. + + > [!NOTE] + > If you don't see the Cloud mode switch, ensure you have the latest version of + > Docker Desktop installed and that Docker Cloud is enabled in **Settings** > + > **Beta features**. + +3. In the Docker Desktop Dashboard, select the dropdown at the top of the left + navigation to choose an account. Docker Cloud will consume Cloud credits from + the selected account. + +After enabling Docker Cloud, Docker Desktop connects to a secure cloud environment +that mirrors your local experience. When you run builds or containers, they +execute remotely, but behave just like local ones. + +To verify that Docker Cloud is active, run a container: + +```console +$ docker run hello-world +``` + +If Docker Cloud is working, you'll see `Hello from Docker!` in the terminal output. + +### Step 2: Optional. Enable GPU support + +GPU support is useful for machine learning or compute-intensive workloads. Once +enabled, your cloud containers run in an instance with an NVIDIA L4 GPU. + +1. In the Docker Desktop Dashboard, navigate to **Settings**. +2. Select **Beta features**. +3. Ensure that the **Enable Docker Cloud** option is enabled. +4. Check the **Enable GPU support** option. +5. Select **Apply & restart** to enable GPU support. +6. Ensure that the Cloud mode switch is enabled in the Docker Desktop Dashboard + header. + +To verify that GPU support is active, run an NVIDIA CUDA container and the +nvidia-smi tool that lets you check GPU status. Use the following command in a +terminal: + +```console +$ docker run --rm --gpus all nvidia/cuda:12.9.0-base-ubuntu24.04 nvidia-smi +``` + +If GPU support is working, you'll see output from nvidia-smi listing available +NVIDIA GPUs, including device names and driver versions. + +For example, the output might look like this: + +```text ++---------------------------------------------------------------------------------------+ +| NVIDIA-SMI 535.247.01 Driver Version: 535.247.01 CUDA Version: 12.9 | +|-----------------------------------------+----------------------+----------------------+ +| GPU Name Persistence-M | Bus-Id Disp.A | Volatile Uncorr. ECC | +| Fan Temp Perf Pwr:Usage/Cap | Memory-Usage | GPU-Util Compute M. | +| | | MIG M. | +|=========================================+======================+======================| +| 0 NVIDIA L4 Off | 00000000:31:00.0 Off | 0 | +| N/A 47C P0 30W / 72W | 0MiB / 23034MiB | 5% Default | +| | | N/A | ++-----------------------------------------+----------------------+----------------------+ + ++---------------------------------------------------------------------------------------+ +| Processes: | +| GPU GI CI PID Type Process name GPU Memory | +| ID ID Usage | +|=======================================================================================| +| No running processes found | ++---------------------------------------------------------------------------------------+ +``` + +If GPU support is not enabled or available in your environment, you'll see an +error indicating that the GPU runtime could not be initialized. + +## What's next + +- [Configure Docker Cloud](configuration.md). +- [Use Docker Cloud to build images in CI environments](ci-build.md). \ No newline at end of file diff --git a/content/manuals/cloud/troubleshoot.md b/content/manuals/cloud/troubleshoot.md new file mode 100644 index 00000000000..794f27402e2 --- /dev/null +++ b/content/manuals/cloud/troubleshoot.md @@ -0,0 +1,158 @@ +--- +title: Troubleshoot Docker Cloud +linktitle: Troubleshoot +weight: 999 +description: Learn how to troubleshoot issues with Docker Cloud. +keywords: cloud, troubleshooting, cloud mode, Docker Desktop, cloud builder, usage +tags: [Troubleshooting] +--- + + +If you're having trouble using Docker Cloud, this guide can help you troubleshoot: + +- Issues with cloud sessions and remote container runs using Docker Desktop (Cloud mode) +- Problems running cloud builds without enabling Cloud mode + +## Troubleshoot Cloud mode + +Docker Desktop uses Cloud mode to run both builds and containers in the cloud. +If builds or containers are failing to run, falling back to local, or reporting +session errors, use the following commands. + +### 1. Check your Docker Cloud session + +Docker Cloud requires an active session between Docker Desktop and the cloud. +Use the following command to check if the connection is active: + +```console +$ docker cloud status +``` + +If you're not connected, start a new session: + +```console +$ docker cloud start +``` + +To stop a session manually: + +```console +$ docker cloud stop +``` + +If you're not sure what's wrong, try running diagnose to get more information +about your environment: + +```console +$ docker cloud diagnose +``` + +This will print helpful information about your environment. + +### 2. Validate cloud builder readiness + +Cloud mode automatically provisions and uses a remote builder. You can confirm +the builder is initialized and ready using: + + +```console +$ docker cloud diagnose +``` + +In the output, look for a healthy session and builder status. If the builder +isn't available, try restarting the session: + +```console +$ docker cloud stop +$ docker cloud start +``` + + +### 3. Check for authentication or networking issues + +Cloud mode requires: + +- A valid Docker login +- An active internet connection +- No restrictive proxy or firewall blocking traffic to Docker Cloud + +Use the following to verify login status: + +```console +$ docker login +``` + +If needed, you can log out and then log in again: + +```console +$ docker logout +$ docker login +``` + +## Troubleshoot builds only + +If you're using Docker Cloud for builds only (without enabling Cloud mode in +Docker Desktop), issues may include builds running locally instead of in the +cloud, builder errors, or authentication failures. + +### 1. Check your active Docker context + +Cloud builds run using a remote builder, but your Docker context may still affect behavior. + +List all contexts: + +```console +$ docker context ls +``` + +You can inspect a specific context: + +```console +$ docker context inspect +``` + +Switch to the appropriate context if needed: + +```console +$ docker context use +``` + +### 2. Verify your builder configuration + +Check available builders: + +```console +$ docker buildx ls +``` + +Look for a builder with the `cloud` driver, for example `cloud-myorg-myteam`. The `*` marks the current one. + +If you're not using the cloud builder, select it: + +```console +$ docker buildx use cloud-myorg-myteam +``` + +### 3. Confirm builder readiness + +Ensure the builder is initialized and ready: + +```console +$ docker buildx inspect --bootstrap +``` +Look for `Status: running` and a cloud driver in the output. + +### 4. Check Docker login + +Make sure you're authenticated with Docker: + +```console +$ docker login +``` + +Re-authenticate if needed: + +```console +$ docker logout +$ docker login +``` \ No newline at end of file diff --git a/content/manuals/cloud/usage.md b/content/manuals/cloud/usage.md new file mode 100644 index 00000000000..31401ad3f01 --- /dev/null +++ b/content/manuals/cloud/usage.md @@ -0,0 +1,54 @@ +--- +title: Docker Cloud usage +linktitle: Usage +weight: 30 +description: Learn about Docker Cloud usage and how to monitor your cloud resources. +keywords: cloud, usage, cloud minutes, shared cache, top repositories, cloud builder, Docker Cloud +--- + +Docker Cloud provides visibility into how your team is using cloud resources to +build and run containers. You can monitor your organization's activity from the +**Cloud overview** page in Docker Cloud. + +## Credits and consumption + +TBD + +## Cloud minutes + +This widget shows the total number of cloud minutes used over time. Cloud +minutes represent the time spent running builds and containers in the cloud. You +can use this chart to: + +- Track your cloud usage trends over time. +- Spot spikes in usage, which may indicate CI changes or build issues. +- Estimate usage against your subscription limits. + +## Shared cache usage + +This widget displays data about cache re-use across all builds, helping you +understand how effectively Docker Cloud is using the shared build cache. It +provides insight into: + +- The percentage of cache hits vs. misses. +- How much estimated build time is saved by reusing cache layers. +- Opportunities to improve cache efficiency by tuning your Dockerfiles or build + strategy. + +## Top repositories built + +This widget highlights the repositories with the highest build activity in +Docker Cloud. This widget helps you understand which projects consume the most +cloud resources and how efficiently they’re being built. + +It includes both aggregated metrics and per-repository details to give you a +comprehensive view. + +Use this widget to: + +- Identify build hotspots: See which repositories are consuming the most build + time and resources. +- Spot trends: Monitor how build activity evolves across your projects. +- Evaluate efficiency: Check which repositories benefit most from cache re-use. +- Target improvements: Flag repositories with low cache hits or high failure + rates for optimization. diff --git a/content/manuals/desktop/setup/images/cloud-mode.png b/content/manuals/desktop/setup/images/cloud-mode.png deleted file mode 100644 index b4d3deb039b..00000000000 Binary files a/content/manuals/desktop/setup/images/cloud-mode.png and /dev/null differ diff --git a/content/manuals/desktop/setup/vm-vdi.md b/content/manuals/desktop/setup/vm-vdi.md index cc4ecb1d205..37d0ed5b012 100644 --- a/content/manuals/desktop/setup/vm-vdi.md +++ b/content/manuals/desktop/setup/vm-vdi.md @@ -16,22 +16,20 @@ depending on whether nested virtualization is supported: - If your environment supports nested virtualization, you can run Docker Desktop with its default local Linux VM. -- If nested virtualization is not supported, Docker recommends using Docker - Cloud. To join the beta, contact Docker at `docker-cloud@docker.com`. +- If nested virtualization is not supported, Docker recommends using [Docker + Cloud](/cloud/). -## Use Docker Cloud +## Use Docker Cloud -{{< summary-bar feature_name="Docker Cloud" >}} - -Docker Cloud lets you offload container workloads to a high-performance, -fully hosted cloud environment, enabling a seamless hybrid experience. It -includes an insights dashboard that offers performance metrics and environment -management to help optimize your development workflow. +Docker Cloud lets you offload container workloads to a high-performance, fully +hosted cloud environment, enabling a seamless hybrid experience. It includes an +insights dashboard that offers performance metrics and environment management to +help optimize your development workflow. This mode is useful in virtual desktop environments where nested virtualization -isn't supported. In these environments, Docker Desktop defaults to using -cloud mode to ensure you can still build and run containers without relying on -local virtualization. +isn't supported. In these environments, Docker Desktop defaults to using cloud +mode to ensure you can still build and run containers without relying on local +virtualization. Docker Cloud decouples the Docker Desktop client from the Docker Engine, allowing the Docker CLI and Docker Desktop Dashboard to interact with @@ -41,57 +39,8 @@ Docker Desktop via an SSH tunnel. Despite running remotely, features like bind mounts and port forwarding continue to work seamlessly, providing a local-like experience. To use Docker Cloud: -1. Contact Docker at `docker-cloud@docker.com` to activate the feature for your - account. -2. [Install Docker Desktop](/manuals/desktop/setup/install/windows-install.md#install-docker-desktop-on-windows) - version 4.42 or later on your Windows virtual desktop. -3. [Start Docker Desktop](/manuals/desktop/setup/install/windows-install.md#start-docker-desktop). -4. Sign in to Docker Desktop. - -After you sign in, Docker Cloud is enabled by default and cannot be -disabled. When enabled, Docker Desktop's Dashboard header appears purple and the -cloud-mode toggle is a cloud icon ({{< inline-image -src="./images/cloud-mode.png" alt="Cloud mode icon" >}}). - -In this mode, Docker Desktop mirrors your cloud environment, providing -a seamless view of your containers and resources running on Docker Cloud. You -can verify that Docker Cloud is working by running a simple container. In a -terminal on your virtual desktop, run the following command: - -```console -$ docker run hello-world -``` - -In the terminal, you will see `Hello from Docker!` if everything is working -correctly. - -### View insights and manage Docker Cloud - -For insights and management, use the [Docker Cloud -Dashboard](https://app.docker.com/cloud). It provides visibility into your -builds, runs, and cloud resource usage. Key features include: - -- Overview: Monitor cloud usage, build cache, and top repositories built. -- Build history: Review past builds with filtering and sorting options. -- Run history: Track container runs and sort by various options. -- Integrations: Learn how to set up cloud builders and runners for your CI - pipeline. -- Settings: Manage cloud builders, usage, and account settings. - -Access the Docker Cloud Dashboard at https://app.docker.com/cloud. - -### Limitations - -The following limitations apply when using Docker Cloud: - -- Persistence: Containers are launched in a cloud engine that remains available - as long as you interact with and consume the containers' output. After closing - Docker Desktop, or about 30 minutes of inactivity, the engine is shut down and - becomes inaccessible, along with any data stored in it, including images, - containers, and volumes. A new engine is provisioned for any new workloads. -- Usage and billing: During beta, no charges are incurred for using Docker Cloud - resources. Docker enforces a usage cap and reserves the right to disable - Docker Cloud access at any time. +To get started using Docker Cloud, see [Docker Cloud +quickstart](/cloud/quickstart/). ## Virtual desktop support when using nested virtualization diff --git a/content/manuals/subscription/details.md b/content/manuals/subscription/details.md index 0a53cc4722c..9fb4f28c917 100644 --- a/content/manuals/subscription/details.md +++ b/content/manuals/subscription/details.md @@ -21,6 +21,8 @@ Docker subscriptions empower development teams by providing the tools they need - [Testcontainers Cloud](https://testcontainers.com/cloud/docs): Container-based testing automation that provides faster tests, a unified developer experience, and more. +- [Docker Cloud](../cloud/_index.md): A cloud-based development environment that + integrates with Docker Desktop to provide a seamless hybrid development experience. The following sections describe some of the key features included with your Docker subscription or Legacy Docker subscription. @@ -45,6 +47,7 @@ Docker Personal includes: - 200 pulls per 6 hours Docker Hub image pull rate limit for authenticated users - 7-day Docker Build Cloud trial - 7-day Testcontainers Cloud trial +- TBD Docker Cloud credits for trial Docker Personal users who want to continue using Docker Build Cloud or Docker Testcontainers Cloud after their trial can upgrade to a Docker Pro subscription at any @@ -72,6 +75,7 @@ rollover month to month. - 2 included repositories with continuous vulnerability analysis in Docker Scout. - 100 Testcontainers Cloud runtime minutes per month for use either in Docker Desktop or for CI. Testcontainers Cloud runtime minutes do not rollover month to month. - No Docker Hub image pull rate limits. +- TBD Docker Cloud credits per month. Credits do not rollover month to month. For a list of features available in each tier, see [Docker Pricing](https://www.docker.com/pricing/). @@ -92,6 +96,7 @@ rollover month to month. - Unlimited Docker Scout repositories with continuous vulnerability analysis. - 500 Testcontainers Cloud runtime minutes per month for use either in Docker Desktop or for CI. Testcontainers Cloud runtime minutes do not rollover month to month. - No Docker Hub image pull rate limits. +- TBD Docker Cloud credits per month. Credits do not rollover month to month. There are also advanced collaboration and management tools, including organization and team management with [Role Based Access Control @@ -116,6 +121,7 @@ rollover month to month. - Unlimited Docker Scout repositories with continuous vulnerability analysis. - 1500 Testcontainers Cloud runtime minutes per month for use either in Docker Desktop or for CI. Testcontainers Cloud runtime minutes do not rollover month to month. - No Docker Hub image pull rate limits. +- TBD Docker Cloud credits per month. Credits do not rollover month to month. In addition, you gain access to enterprise-grade features, such as: - [Hardened Docker Desktop](../security/for-admins/hardened-desktop/_index.md) diff --git a/content/reference/cli/docker/cloud/_index.md b/content/reference/cli/docker/cloud/_index.md new file mode 100644 index 00000000000..4547062021f --- /dev/null +++ b/content/reference/cli/docker/cloud/_index.md @@ -0,0 +1,13 @@ +--- +datafolder: cloud-cli +datafile: docker_cloud +title: docker cloud +layout: cli +params: + sidebar: + badge: + color: blue + text: Beta +--- + +{{< summary-bar feature_name="Docker Cloud" >}} \ No newline at end of file diff --git a/content/reference/cli/docker/cloud/accounts.md b/content/reference/cli/docker/cloud/accounts.md new file mode 100644 index 00000000000..ca18cde0a8e --- /dev/null +++ b/content/reference/cli/docker/cloud/accounts.md @@ -0,0 +1,8 @@ +--- +datafolder: cloud-cli +datafile: docker_cloud_accounts +title: docker cloud accounts +layout: cli +--- + +{{< summary-bar feature_name="Docker Cloud" >}} diff --git a/content/reference/cli/docker/cloud/diagnose.md b/content/reference/cli/docker/cloud/diagnose.md new file mode 100644 index 00000000000..51320134e39 --- /dev/null +++ b/content/reference/cli/docker/cloud/diagnose.md @@ -0,0 +1,8 @@ +--- +datafolder: cloud-cli +datafile: docker_cloud_diagnose +title: docker cloud diagnose +layout: cli +--- + +{{< summary-bar feature_name="Docker Cloud" >}} diff --git a/content/reference/cli/docker/cloud/start.md b/content/reference/cli/docker/cloud/start.md new file mode 100644 index 00000000000..ca44119a96f --- /dev/null +++ b/content/reference/cli/docker/cloud/start.md @@ -0,0 +1,8 @@ +--- +datafolder: cloud-cli +datafile: docker_cloud_start +title: docker cloud start +layout: cli +--- + +{{< summary-bar feature_name="Docker Cloud" >}} diff --git a/content/reference/cli/docker/cloud/status.md b/content/reference/cli/docker/cloud/status.md new file mode 100644 index 00000000000..7edf7e6f6bb --- /dev/null +++ b/content/reference/cli/docker/cloud/status.md @@ -0,0 +1,8 @@ +--- +datafolder: cloud-cli +datafile: docker_cloud_status +title: docker cloud status +layout: cli +--- + +{{< summary-bar feature_name="Docker Cloud" >}} diff --git a/content/reference/cli/docker/cloud/stop.md b/content/reference/cli/docker/cloud/stop.md new file mode 100644 index 00000000000..910213e8769 --- /dev/null +++ b/content/reference/cli/docker/cloud/stop.md @@ -0,0 +1,8 @@ +--- +datafolder: cloud-cli +datafile: docker_cloud_stop +title: docker cloud stop +layout: cli +--- + +{{< summary-bar feature_name="Docker Cloud" >}} diff --git a/content/reference/cli/docker/cloud/version.md b/content/reference/cli/docker/cloud/version.md new file mode 100644 index 00000000000..33071bdb8a3 --- /dev/null +++ b/content/reference/cli/docker/cloud/version.md @@ -0,0 +1,8 @@ +--- +datafolder: cloud-cli +datafile: docker_cloud_version +title: docker cloud version +layout: cli +--- + +{{< summary-bar feature_name="Docker Cloud" >}} diff --git a/data/cloud-cli/docker_cloud.yaml b/data/cloud-cli/docker_cloud.yaml new file mode 100644 index 00000000000..87db3adfca0 --- /dev/null +++ b/data/cloud-cli/docker_cloud.yaml @@ -0,0 +1,25 @@ +command: docker cloud +short: Control Docker Cloud from the CLI +usage: docker cloud +pname: docker +plink: docker.yaml +cname: + - docker cloud accounts + - docker cloud diagnose + - docker cloud start + - docker cloud status + - docker cloud stop + - docker cloud version +clink: + - docker_cloud_accounts.yaml + - docker_cloud_diagnose.yaml + - docker_cloud_start.yaml + - docker_cloud_status.yaml + - docker_cloud_stop.yaml + - docker_cloud_version.yaml +deprecated: false +hidden: true +experimental: false +experimentalcli: false +kubernetes: false +swarm: false diff --git a/data/cloud-cli/docker_cloud_accounts.yaml b/data/cloud-cli/docker_cloud_accounts.yaml new file mode 100644 index 00000000000..b4ad21da2ad --- /dev/null +++ b/data/cloud-cli/docker_cloud_accounts.yaml @@ -0,0 +1,12 @@ +command: docker cloud accounts +short: Prints available Docker Cloud accounts +usage: docker cloud accounts +pname: docker cloud +plink: docker_cloud.yaml +options: [] +deprecated: false +hidden: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false diff --git a/data/cloud-cli/docker_cloud_diagnose.yaml b/data/cloud-cli/docker_cloud_diagnose.yaml new file mode 100644 index 00000000000..d39b9c3e1ae --- /dev/null +++ b/data/cloud-cli/docker_cloud_diagnose.yaml @@ -0,0 +1,12 @@ +command: docker cloud diagnose +short: Print diagnostic information for Docker Cloud +usage: docker cloud diagnose +pname: docker cloud +plink: docker_cloud.yaml +options: [] +deprecated: false +hidden: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false diff --git a/data/cloud-cli/docker_cloud_start.yaml b/data/cloud-cli/docker_cloud_start.yaml new file mode 100644 index 00000000000..3c0ead1b0b0 --- /dev/null +++ b/data/cloud-cli/docker_cloud_start.yaml @@ -0,0 +1,12 @@ +command: docker cloud start +short: Start a Docker Cloud session +usage: docker cloud start +pname: docker cloud +plink: docker_cloud.yaml +options: [] +deprecated: false +hidden: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false diff --git a/data/cloud-cli/docker_cloud_status.yaml b/data/cloud-cli/docker_cloud_status.yaml new file mode 100644 index 00000000000..8d0e5daec64 --- /dev/null +++ b/data/cloud-cli/docker_cloud_status.yaml @@ -0,0 +1,23 @@ +command: docker cloud status +short: Show the status of the Docker Cloud connection +usage: docker cloud status [OPTIONS] +pname: docker cloud +plink: docker_cloud.yaml +options: + - option: watch + shorthand: w + value_type: bool + default_value: "false" + description: Watch for status updates + 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/cloud-cli/docker_cloud_stop.yaml b/data/cloud-cli/docker_cloud_stop.yaml new file mode 100644 index 00000000000..ee46e00855e --- /dev/null +++ b/data/cloud-cli/docker_cloud_stop.yaml @@ -0,0 +1,23 @@ +command: docker cloud stop +short: Stop a Docker Cloud session +usage: docker cloud stop [OPTIONS] +pname: docker cloud +plink: docker_cloud.yaml +options: + - option: force + shorthand: f + value_type: bool + default_value: "false" + description: Don't prompt for confirmation + 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/cloud-cli/docker_cloud_version.yaml b/data/cloud-cli/docker_cloud_version.yaml new file mode 100644 index 00000000000..88b3f50ba9e --- /dev/null +++ b/data/cloud-cli/docker_cloud_version.yaml @@ -0,0 +1,32 @@ +command: docker cloud version +short: Prints the Docker Cloud CLI version +usage: docker cloud version [OPTIONS] +pname: docker cloud +plink: docker_cloud.yaml +options: + - option: json + value_type: bool + default_value: "false" + description: Prints the version as JSON + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: short + value_type: bool + default_value: "false" + description: Prints the short version + 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/redirects.yml b/data/redirects.yml index b525e2c7608..82b2996771e 100644 --- a/data/redirects.yml +++ b/data/redirects.yml @@ -223,10 +223,11 @@ - /go/docker-build-cloud/ # Run Cloud links & Docker Cloud -"/": +"/": - /go/run-cloud-eap/ -"/desktop/setup/vm-vdi/": +"/cloud/": - /go/docker-cloud/ +"/cloud/about/": - /go/docker-cloud-gpu/ # CLI backlinks diff --git a/data/summary.yaml b/data/summary.yaml index c3fa29f2866..020911bf94d 100644 --- a/data/summary.yaml +++ b/data/summary.yaml @@ -137,7 +137,8 @@ Docker CLI OpenTelemetry: requires: Docker Engine [26.1.0](/manuals/engine/release-notes/26.1.md#2610) and later Docker Cloud: availability: Beta - requires: Docker Desktop 4.42 and later + requires: Docker Desktop 4.43 and later + subscription: [Pro, Team, Business] docker compose alpha: availability: Experimental Docker Debug: