diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 7c8329fc10f..9194fe697ea 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -5,7 +5,7 @@ /content/manuals/build/ @crazy-max @aevesdocker -/content/manuals/build-cloud/ @crazy-max @aevesdocker +/content/manuals/build-cloud/ @crazy-max @aevesdocker /content/manuals/compose/ @aevesdocker @@ -19,11 +19,11 @@ /content/manuals/docker-hub/ @craig-osterhout -/content/manuals/engine/ @thaJeztah @aevesdocker +/content/manuals/engine/ @thaJeztah @aevesdocker -/content/reference/api/engine/ @thaJeztah @aevesdocker +/content/reference/api/engine/ @thaJeztah @aevesdocker -/content/reference/cli/ @thaJeztah @aevesdocker +/content/reference/cli/ @thaJeztah @aevesdocker /content/manuals/subscription/ @sarahsanders-docker @@ -41,4 +41,6 @@ /content/manuals/accounts/ @sarahsanders-docker +/content/manuals/ai/ @ArthurFlag + /_vendor @sarahsanders-docker diff --git a/.github/labeler.yml b/.github/labeler.yml index 11cef0e77f6..c610f1df620 100644 --- a/.github/labeler.yml +++ b/.github/labeler.yml @@ -1,3 +1,9 @@ +area/ai: + - changed-files: + - any-glob-to-any-file: + - content/manuals/ai/** + - content/reference/cli/model/** + area/release: - changed-files: - any-glob-to-any-file: diff --git a/_vendor/modules.txt b/_vendor/modules.txt index 1a4ad2197df..5b934fd1d8d 100644 --- a/_vendor/modules.txt +++ b/_vendor/modules.txt @@ -1,5 +1,5 @@ # github.com/moby/moby v28.1.0-rc.2+incompatible -# github.com/moby/buildkit v0.21.1 +# github.com/moby/buildkit v0.22.0-rc1 # github.com/docker/buildx v0.23.0 # github.com/docker/cli v28.1.1+incompatible # github.com/docker/compose/v2 v2.36.0 diff --git a/content/manuals/ai/model-runner.md b/content/manuals/ai/model-runner.md index 84898f989dd..65fe8562285 100644 --- a/content/manuals/ai/model-runner.md +++ b/content/manuals/ai/model-runner.md @@ -7,9 +7,9 @@ params: text: Beta group: AI weight: 20 -description: Learn how to use Docker Model Runner to manage and run AI models. +description: Learn how to use Docker Model Runner to manage and run AI models. keywords: Docker, ai, model runner, docker deskotp, llm -aliases: +aliases: - /desktop/features/model-runner/ - /ai/model-runner/ --- @@ -34,8 +34,8 @@ Models are pulled from Docker Hub the first time they're used and stored locally 1. Navigate to the **Features in development** tab in settings. 2. Under the **Experimental features** tab, select **Access experimental features**. -3. Select **Apply and restart**. -4. Quit and reopen Docker Desktop to ensure the changes take effect. +3. Select **Apply and restart**. +4. Quit and reopen Docker Desktop to ensure the changes take effect. 5. Open the **Settings** view in Docker Desktop. 6. Navigate to **Features in development**. 7. From the **Beta** tab, check the **Enable Docker Model Runner** setting. @@ -46,7 +46,7 @@ You can now use the `docker model` command in the CLI and view and interact with ### Model runner status -Check whether the Docker Model Runner is active: +Check whether the Docker Model Runner is active and displays the current inference engine: ```console $ docker model status @@ -55,7 +55,7 @@ $ docker model status ### View all commands Displays help information and a list of available subcommands. - + ```console $ docker model help ``` @@ -74,7 +74,7 @@ Commands: version Show the current version ``` -### Pull a model +### Pull a model Pulls a model from Docker Hub to your local environment. @@ -82,7 +82,7 @@ Pulls a model from Docker Hub to your local environment. $ docker model pull ``` -Example: +Example: ```console $ docker model pull ai/smollm2 @@ -114,7 +114,13 @@ You will see something similar to: ### Run a model -Run a model and interact with it using a submitted prompt or in chat mode. +Run a model and interact with it using a submitted prompt or in chat mode. When you run a model, Docker +calls an Inference Server API endpoint hosted by the Model Runner through Docker Desktop. The model +stays in memory until another model is requested, or until a pre-defined inactivity timeout is reached (currently 5 minutes). + +You do not have to use `Docker model run` before interacting with a specific model from a +host process or from within a container. Model Runner transparently loads the requested model on-demand, assuming it has been +pulled beforehand and is locally available. #### One-time prompt @@ -150,7 +156,7 @@ Chat session ended. ### Push a model to Docker Hub -Use the following command to push your model to Docker Hub: +To push your model to Docker Hub: ```console $ docker model push / @@ -158,10 +164,10 @@ $ docker model push / ### Tag a model -You can specify a particular version or variant of the model: +To specify a particular version or variant of the model: ```console -$ docker model tag +$ docker model tag ``` If no tag is provided, Docker defaults to `latest`. @@ -171,7 +177,7 @@ If no tag is provided, Docker defaults to `latest`. Fetch logs from Docker Model Runner to monitor activity or debug issues. ```console -$ docker model logs +$ docker model logs ``` The following flags are accepted: @@ -211,7 +217,7 @@ If you want to try an existing GenAI application, follow these instructions. 4. Open you app in the browser at the addresses specified in the repository [README](https://github.com/docker/hello-genai). -You'll see the GenAI app's interface where you can start typing your prompts. +You'll see the GenAI app's interface where you can start typing your prompts. You can now interact with your own GenAI app, powered by a local model. Try a few prompts and notice how fast the responses are — all running on your machine with Docker. @@ -219,45 +225,46 @@ You can now interact with your own GenAI app, powered by a local model. Try a fe ### What models are available? -All the available models are hosted in the [public Docker Hub namespace of `ai`](https://hub.docker.com/u/ai). +All the available models are hosted in the [public Docker Hub namespace of `ai`](https://hub.docker.com/u/ai). ### What API endpoints are available? -Once the feature is enabled, the following new APIs are available: +Once the feature is enabled, new API endpoints are available under the following base URLs: -```text -#### Inside containers #### +- From containers: `http://model-runner.docker.internal/` +- From host processes: `http://localhost:12434/`, assuming you have enabled TCP host access on default port 12434. -http://model-runner.docker.internal/ +Docker Model management endpoints: - # Docker Model management - POST /models/create - GET /models - GET /models/{namespace}/{name} - DELETE /models/{namespace}/{name} +```text +POST /models/create +GET /models +GET /models/{namespace}/{name} +DELETE /models/{namespace}/{name} +``` - # OpenAI endpoints - GET /engines/llama.cpp/v1/models - GET /engines/llama.cpp/v1/models/{namespace}/{name} - POST /engines/llama.cpp/v1/chat/completions - POST /engines/llama.cpp/v1/completions - POST /engines/llama.cpp/v1/embeddings - Note: You can also omit llama.cpp. - E.g., POST /engines/v1/chat/completions. +OpenAI endpoints: -#### Inside or outside containers (host) #### +```text +GET /engines/llama.cpp/v1/models +GET /engines/llama.cpp/v1/models/{namespace}/{name} +POST /engines/llama.cpp/v1/chat/completions +POST /engines/llama.cpp/v1/completions +POST /engines/llama.cpp/v1/embeddings +``` -Same endpoints on /var/run/docker.sock +To call these endpoints via a Unix socket (`/var/run/docker.sock`), prefix their path with +with `/exp/vDD4.40`. + +> [!NOTE] +> You can omit `llama.cpp` from the path. For example: `POST /engines/v1/chat/completions`. - # While still in Beta - Prefixed with /exp/vDD4.40 -``` ### How do I interact through the OpenAI API? #### From within a container -Examples of calling an OpenAI endpoint (`chat/completions`) from within another container using `curl`: +To call the `chat/completions` OpenAI endpoint from within another container using `curl`: ```bash #!/bin/sh @@ -280,15 +287,18 @@ curl http://model-runner.docker.internal/engines/llama.cpp/v1/chat/completions \ ``` -#### From the host using a Unix socket +#### From the host using TCP -Examples of calling an OpenAI endpoint (`chat/completions`) through the Docker socket from the host using `curl`: +To call the `chat/completions` OpenAI endpoint from the host via TCP: + +1. Enable the host-side TCP support from the Docker Desktop GUI, or via the [Docker Desktop CLI](/manuals/desktop/features/desktop-cli.md). + For example: `docker desktop enable model-runner --tcp `. +2. Interact with it as documented in the previous section using `localhost` and the correct port. ```bash #!/bin/sh -curl --unix-socket $HOME/.docker/run/docker.sock \ - localhost/exp/vDD4.40/engines/llama.cpp/v1/chat/completions \ + curl http://localhost:12434/engines/llama.cpp/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "ai/smollm2", @@ -303,19 +313,17 @@ curl --unix-socket $HOME/.docker/run/docker.sock \ } ] }' - ``` -#### From the host using TCP - -In case you want to interact with the API from the host, but use TCP instead of a Docker socket, you can enable the host-side TCP support from the Docker Desktop GUI, or via the [Docker Desktop CLI](/manuals/desktop/features/desktop-cli.md). For example, using `docker desktop enable model-runner --tcp `. +#### From the host using a Unix socket -Afterwards, interact with it as previously documented using `localhost` and the chosen, or the default port. +To call the `chat/completions` OpenAI endpoint through the Docker socket from the host using `curl`: ```bash #!/bin/sh - curl http://localhost:12434/engines/llama.cpp/v1/chat/completions \ +curl --unix-socket $HOME/.docker/run/docker.sock \ + localhost/exp/vDD4.40/engines/llama.cpp/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "ai/smollm2", @@ -354,7 +362,7 @@ Once linked, re-run the command. ### No safeguard for running oversized models -Currently, Docker Model Runner doesn't include safeguards to prevent you from launching models that exceed their system’s available resources. Attempting to run a model that is too large for the host machine may result in severe slowdowns or render the system temporarily unusable. This issue is particularly common when running LLMs models without sufficient GPU memory or system RAM. +Currently, Docker Model Runner doesn't include safeguards to prevent you from launching models that exceed their system's available resources. Attempting to run a model that is too large for the host machine may result in severe slowdowns or render the system temporarily unusable. This issue is particularly common when running LLMs models without sufficient GPU memory or system RAM. ### No consistent digest support in Model CLI @@ -362,7 +370,7 @@ The Docker Model CLI currently lacks consistent support for specifying models by ## Share feedback -Thanks for trying out Docker Model Runner. Give feedback or report any bugs you may find through the **Give feedback** link next to the **Enable Docker Model Runner** setting. +Thanks for trying out Docker Model Runner. Give feedback or report any bugs you may find through the **Give feedback** link next to the **Enable Docker Model Runner** setting. ## Disable the feature @@ -371,4 +379,4 @@ To disable Docker Model Runner: 1. Open the **Settings** view in Docker Desktop. 2. Navigate to the **Beta** tab in **Features in development**. 3. Clear the **Enable Docker Model Runner** checkbox. -4. Select **Apply & restart**. \ No newline at end of file +4. Select **Apply & restart**. diff --git a/content/manuals/compose/support-and-feedback/feedback.md b/content/manuals/compose/support-and-feedback/feedback.md index 04466f8a4e5..494e821488b 100644 --- a/content/manuals/compose/support-and-feedback/feedback.md +++ b/content/manuals/compose/support-and-feedback/feedback.md @@ -9,12 +9,6 @@ aliases: There are many ways you can provide feedback on Docker Compose. -### In-product feedback - -If you have obtained Docker Compose through Docker Desktop, you can use the `docker feedback` command to submit feedback directly from the command line. - - - ### Report bugs or problems on GitHub To report bugs or problems, visit [Docker Compose on GitHub](https://github.com/docker/compose/issues) diff --git a/content/manuals/desktop/troubleshoot-and-support/feedback.md b/content/manuals/desktop/troubleshoot-and-support/feedback.md index 6ab0af9cf89..edba3f2d070 100644 --- a/content/manuals/desktop/troubleshoot-and-support/feedback.md +++ b/content/manuals/desktop/troubleshoot-and-support/feedback.md @@ -14,10 +14,6 @@ There are many ways you can provide feedback on Docker Desktop or Docker Desktop On each Docker Desktop Dashboard view, there is a **Give feedback** link. This opens a feedback form where you can share ideas directly with the Docker team. -You can also use the `docker feedback` command to submit feedback directly from the command line. - - - ### Feedback via Docker Community forums To get help from the community, review current user topics, join or start a diff --git a/content/manuals/desktop/troubleshoot-and-support/troubleshoot/topics.md b/content/manuals/desktop/troubleshoot-and-support/troubleshoot/topics.md index ba3ff6953ae..a234191093c 100644 --- a/content/manuals/desktop/troubleshoot-and-support/troubleshoot/topics.md +++ b/content/manuals/desktop/troubleshoot-and-support/troubleshoot/topics.md @@ -343,13 +343,21 @@ Also, the `\` character has a special meaning in Git Bash. Portability of the scripts is not affected as Linux treats multiple `/` as a single entry. -### Docker Desktop fails due to Virtualization settings +### Docker Desktop fails due to Virtualization not working + +#### Error message + +A typical error message is "Docker Desktop - Unexpected WSL error" mentioning the error code +`Wsl/Service/RegisterDistro/CreateVm/HCS/HCS_E_HYPERV_NOT_INSTALLED`. Manually executing `wsl` commands +also fails with the same error code. #### Cause - Virtualization settings are disabled in the BIOS. - Windows Hyper-V or WSL 2 components are missing. +Note some third-party software such as Android emulators will disable Hyper-V on install. + #### Solutions Your machine must have the following features for Docker Desktop to function correctly: @@ -364,6 +372,21 @@ Your machine must have the following features for Docker Desktop to function cor ![WSL 2 enabled](../../images/wsl2-enabled.png) +It must be possible to run WSL 2 commands without error, for example: + +```console +PS C:\users\> wsl -l -v + NAME STATE VERSION +* Ubuntu Running 2 + docker-desktop Stopped 2 +PS C:\users\> wsl -d docker-desktop echo WSL 2 is working +WSL 2 is working +``` + +If the features are enabled but the commands are not working, first check [Virtualization is turned on](#virtualization-must-be-turned-on) +then [enable the Hypervisor at Windows startup](#hypervisor-enabled-at-windows-startup) if required. If running Docker +Desktop in a Virtual Machine, ensure [the hypervisor has nested virtualization enabled](#turn-on-nested-virtualization). + ##### Hyper-V On Windows 10 Pro or Enterprise, you can also use Hyper-V with the following features enabled: diff --git a/data/buildx/docker_buildx_build.yaml b/data/buildx/docker_buildx_build.yaml index 57a0d8cbfea..91aca49cfc8 100644 --- a/data/buildx/docker_buildx_build.yaml +++ b/data/buildx/docker_buildx_build.yaml @@ -187,16 +187,6 @@ options: experimentalcli: false kubernetes: false swarm: false - - option: detach - value_type: bool - default_value: "false" - description: Detach buildx server (supported only on linux) - deprecated: false - hidden: false - experimental: false - experimentalcli: true - kubernetes: false - swarm: false - option: file shorthand: f value_type: string @@ -415,15 +405,6 @@ options: experimentalcli: false kubernetes: false swarm: false - - option: root - value_type: string - description: Specify root directory of server to connect - deprecated: false - hidden: false - experimental: false - experimentalcli: true - kubernetes: false - swarm: false - option: sbom value_type: string description: Shorthand for `--attest=type=sbom` @@ -456,16 +437,6 @@ options: experimentalcli: false kubernetes: false swarm: false - - option: server-config - value_type: string - description: | - Specify buildx server config file (used only when launching new server) - deprecated: false - hidden: false - experimental: false - experimentalcli: true - kubernetes: false - swarm: false - option: shm-size value_type: bytes default_value: "0" diff --git a/data/buildx/docker_buildx_debug.yaml b/data/buildx/docker_buildx_debug.yaml index 90e6d0e8756..f9b45c6ad3a 100644 --- a/data/buildx/docker_buildx_debug.yaml +++ b/data/buildx/docker_buildx_debug.yaml @@ -9,16 +9,6 @@ cname: clink: - docker_buildx_debug_build.yaml options: - - option: detach - value_type: bool - default_value: "true" - description: Detach buildx server for the monitor (supported only on linux) - deprecated: false - hidden: false - experimental: false - experimentalcli: true - kubernetes: false - swarm: false - option: invoke value_type: string description: Launch a monitor with executing specified command @@ -49,25 +39,6 @@ options: experimentalcli: false kubernetes: false swarm: false - - option: root - value_type: string - description: Specify root directory of server to connect for the monitor - deprecated: false - hidden: false - experimental: false - experimentalcli: true - kubernetes: false - swarm: false - - option: server-config - value_type: string - description: | - Specify buildx server config file for the monitor (used only when launching new server) - deprecated: false - hidden: false - experimental: false - experimentalcli: true - kubernetes: false - swarm: false inherited_options: - option: builder value_type: string diff --git a/data/buildx/docker_buildx_debug_build.yaml b/data/buildx/docker_buildx_debug_build.yaml index e5e1b934a0b..547ae9e122a 100644 --- a/data/buildx/docker_buildx_debug_build.yaml +++ b/data/buildx/docker_buildx_debug_build.yaml @@ -176,16 +176,6 @@ options: experimentalcli: false kubernetes: false swarm: false - - option: detach - value_type: bool - default_value: "false" - description: Detach buildx server (supported only on linux) - deprecated: false - hidden: false - experimental: false - experimentalcli: true - kubernetes: false - swarm: false - option: file shorthand: f value_type: string @@ -394,15 +384,6 @@ options: experimentalcli: false kubernetes: false swarm: false - - option: root - value_type: string - description: Specify root directory of server to connect - deprecated: false - hidden: false - experimental: false - experimentalcli: true - kubernetes: false - swarm: false - option: sbom value_type: string description: Shorthand for `--attest=type=sbom` @@ -433,16 +414,6 @@ options: experimentalcli: false kubernetes: false swarm: false - - option: server-config - value_type: string - description: | - Specify buildx server config file (used only when launching new server) - deprecated: false - hidden: false - experimental: false - experimentalcli: true - kubernetes: false - swarm: false - option: shm-size value_type: bytes default_value: "0" diff --git a/data/buildx/docker_buildx_dial-stdio.yaml b/data/buildx/docker_buildx_dial-stdio.yaml index ca47c5afd74..4ba6f40e9af 100644 --- a/data/buildx/docker_buildx_dial-stdio.yaml +++ b/data/buildx/docker_buildx_dial-stdio.yaml @@ -1,8 +1,10 @@ command: docker buildx dial-stdio short: Proxy current stdio streams to builder instance long: |- - dial-stdio uses the stdin and stdout streams of the command to proxy to the configured builder instance. - It is not intended to be used by humans, but rather by other tools that want to interact with the builder instance via BuildKit API. + dial-stdio uses the stdin and stdout streams of the command to proxy to the + configured builder instance. It is not intended to be used by humans, but + rather by other tools that want to interact with the builder instance via + BuildKit API. usage: docker buildx dial-stdio pname: docker buildx plink: docker_buildx.yaml @@ -50,7 +52,7 @@ inherited_options: swarm: false examples: |- Example go program that uses the dial-stdio command wire up a buildkit client. - This is for example use only and may not be suitable for production use. + This is, for example, use only and may not be suitable for production use. ```go client.New(ctx, "", client.WithContextDialer(func(context.Context, string) (net.Conn, error) { diff --git a/data/buildx/docker_buildx_history_export.yaml b/data/buildx/docker_buildx_history_export.yaml index e70b8f8fba9..214ebd004d2 100644 --- a/data/buildx/docker_buildx_history_export.yaml +++ b/data/buildx/docker_buildx_history_export.yaml @@ -1,14 +1,29 @@ command: docker buildx history export -short: Export a build into Docker Desktop bundle -long: Export a build into Docker Desktop bundle -usage: docker buildx history export [OPTIONS] [REF] +short: Export build records into Docker Desktop bundle +long: |- + Export one or more build records to `.dockerbuild` archive files. These archives + contain metadata, logs, and build outputs, and can be imported into Docker + Desktop or shared across environments. +usage: docker buildx history export [OPTIONS] [REF...] pname: docker buildx history plink: docker_buildx_history.yaml options: - option: all value_type: bool default_value: "false" - description: Export all records for the builder + description: Export all build records for the builder + details_url: '#all' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: finalize + value_type: bool + default_value: "false" + description: Ensure build records are finalized before exporting + details_url: '#finalize' deprecated: false hidden: false experimental: false @@ -19,6 +34,7 @@ options: shorthand: o value_type: string description: Output file path + details_url: '#output' deprecated: false hidden: false experimental: false @@ -29,6 +45,7 @@ inherited_options: - option: builder value_type: string description: Override the configured builder instance + details_url: '#builder' deprecated: false hidden: false experimental: false @@ -40,12 +57,78 @@ inherited_options: value_type: bool default_value: "false" description: Enable debug logging + details_url: '#debug' deprecated: false hidden: false experimental: false experimentalcli: false kubernetes: false swarm: false +examples: |- + ### Export all build records to a file (--all) {#all} + + Use the `--all` flag and redirect the output: + + ```console + docker buildx history export --all > all-builds.dockerbuild + ``` + + Or use the `--output` flag: + + ```console + docker buildx history export --all -o all-builds.dockerbuild + ``` + + ### Use a specific builder instance (--builder) {#builder} + + ```console + docker buildx history export --builder builder0 ^1 -o builder0-build.dockerbuild + ``` + + ### Enable debug logging (--debug) {#debug} + + ```console + docker buildx history export --debug qu2gsuo8ejqrwdfii23xkkckt -o debug-build.dockerbuild + ``` + + ### Ensure build records are finalized before exporting (--finalize) {#finalize} + + Clients can report their own traces concurrently, and not all traces may be + saved yet by the time of the export. Use the `--finalize` flag to ensure all + traces are finalized before exporting. + + ```console + docker buildx history export --finalize qu2gsuo8ejqrwdfii23xkkckt -o finalized-build.dockerbuild + ``` + + ### Export a single build to a custom file (--output) {#output} + + ```console + docker buildx history export qu2gsuo8ejqrwdfii23xkkckt --output mybuild.dockerbuild + ``` + + You can find build IDs by running: + + ```console + docker buildx history ls + ``` + + To export two builds to separate files: + + ```console + # Using build IDs + docker buildx history export qu2gsuo8ejqrwdfii23xkkckt qsiifiuf1ad9pa9qvppc0z1l3 -o multi.dockerbuild + + # Or using relative offsets + docker buildx history export ^1 ^2 -o multi.dockerbuild + ``` + + Or use shell redirection: + + ```console + docker buildx history export ^1 > mybuild.dockerbuild + docker buildx history export ^2 > backend-build.dockerbuild + ``` deprecated: false hidden: false experimental: false diff --git a/data/buildx/docker_buildx_history_import.yaml b/data/buildx/docker_buildx_history_import.yaml index 089a7b328da..bf6e2ac1fd0 100644 --- a/data/buildx/docker_buildx_history_import.yaml +++ b/data/buildx/docker_buildx_history_import.yaml @@ -1,7 +1,10 @@ command: docker buildx history import -short: Import a build into Docker Desktop -long: Import a build into Docker Desktop -usage: docker buildx history import [OPTIONS] < bundle.dockerbuild +short: Import build records into Docker Desktop +long: |- + Import a build record from a `.dockerbuild` archive into Docker Desktop. This + lets you view, inspect, and analyze builds created in other environments or CI + pipelines. +usage: docker buildx history import [OPTIONS] - pname: docker buildx history plink: docker_buildx_history.yaml options: @@ -10,6 +13,7 @@ options: value_type: stringArray default_value: '[]' description: Import from a file path + details_url: '#file' deprecated: false hidden: false experimental: false @@ -37,6 +41,30 @@ inherited_options: experimentalcli: false kubernetes: false swarm: false +examples: |- + ### Import a `.dockerbuild` archive from standard input + + ```console + docker buildx history import < mybuild.dockerbuild + ``` + + ### Import a build archive from a file (--file) {#file} + + ```console + docker buildx history import --file ./artifacts/backend-build.dockerbuild + ``` + + ### Open a build manually + + By default, the `import` command automatically opens the imported build in Docker + Desktop. You don't need to run `open` unless you're opening a specific build + or re-opening it later. + + If you've imported multiple builds, you can open one manually: + + ```console + docker buildx history open ci-build + ``` deprecated: false hidden: false experimental: false diff --git a/data/buildx/docker_buildx_history_inspect.yaml b/data/buildx/docker_buildx_history_inspect.yaml index 65bbe11d597..23c5ee37b4e 100644 --- a/data/buildx/docker_buildx_history_inspect.yaml +++ b/data/buildx/docker_buildx_history_inspect.yaml @@ -1,6 +1,9 @@ command: docker buildx history inspect -short: Inspect a build -long: Inspect a build +short: Inspect a build record +long: |- + Inspect a build record to view metadata such as duration, status, build inputs, + platforms, outputs, and attached artifacts. You can also use flags to extract + provenance, SBOMs, or other detailed information. usage: docker buildx history inspect [OPTIONS] [REF] pname: docker buildx history plink: docker_buildx_history.yaml @@ -42,11 +45,53 @@ inherited_options: kubernetes: false swarm: false examples: |- + ### Inspect the most recent build + + ```console + $ docker buildx history inspect + Name: buildx (binaries) + Context: . + Dockerfile: Dockerfile + VCS Repository: https://github.com/crazy-max/buildx.git + VCS Revision: f15eaa1ee324ffbbab29605600d27a84cab86361 + Target: binaries + Platforms: linux/amd64 + Keep Git Dir: true + + Started: 2025-02-07 11:56:24 + Duration: 1m 1s + Build Steps: 16/16 (25% cached) + + Image Resolve Mode: local + + Materials: + URI DIGEST + pkg:docker/docker/dockerfile@1 sha256:93bfd3b68c109427185cd78b4779fc82b484b0b7618e36d0f104d4d801e66d25 + pkg:docker/golang@1.23-alpine3.21?platform=linux%2Famd64 sha256:2c49857f2295e89b23b28386e57e018a86620a8fede5003900f2d138ba9c4037 + pkg:docker/tonistiigi/xx@1.6.1?platform=linux%2Famd64 sha256:923441d7c25f1e2eb5789f82d987693c47b8ed987c4ab3b075d6ed2b5d6779a3 + + Attachments: + DIGEST PLATFORM TYPE + sha256:217329d2af959d4f02e3a96dcbe62bf100cab1feb8006a047ddfe51a5397f7e3 https://slsa.dev/provenance/v0.2 + ``` + + ### Inspect a specific build + + ```console + # Using a build ID + docker buildx history inspect qu2gsuo8ejqrwdfii23xkkckt + + # Or using a relative offset + docker buildx history inspect ^1 + ``` + ### Format the output (--format) {#format} The formatting options (`--format`) pretty-prints the output to `pretty` (default), `json` or using a Go template. + #### Pretty output + ```console $ docker buildx history inspect Name: buildx (binaries) @@ -77,6 +122,8 @@ examples: |- Print build logs: docker buildx history logs g9808bwrjrlkbhdamxklx660b ``` + #### JSON output + ```console $ docker buildx history inspect --format json { @@ -130,6 +177,8 @@ examples: |- } ``` + #### Go template output + ```console $ docker buildx history inspect --format "{{.Name}}: {{.VCSRepository}} ({{.VCSRevision}})" buildx (binaries): https://github.com/crazy-max/buildx.git (f15eaa1ee324ffbbab29605600d27a84cab86361) diff --git a/data/buildx/docker_buildx_history_inspect_attachment.yaml b/data/buildx/docker_buildx_history_inspect_attachment.yaml index c43308120bb..ba883f47483 100644 --- a/data/buildx/docker_buildx_history_inspect_attachment.yaml +++ b/data/buildx/docker_buildx_history_inspect_attachment.yaml @@ -1,6 +1,9 @@ command: docker buildx history inspect attachment -short: Inspect a build attachment -long: Inspect a build attachment +short: Inspect a build record attachment +long: |- + Inspect a specific attachment from a build record, such as a provenance file or + SBOM. Attachments are optional artifacts stored with the build and may be + platform-specific. usage: docker buildx history inspect attachment [OPTIONS] REF [DIGEST] pname: docker buildx history inspect plink: docker_buildx_history_inspect.yaml @@ -17,6 +20,7 @@ options: - option: type value_type: string description: Type of attachment + details_url: '#type' deprecated: false hidden: false experimental: false @@ -44,6 +48,64 @@ inherited_options: experimentalcli: false kubernetes: false swarm: false +examples: |- + ### Inspect a provenance attachment from a build (--type) {#type} + + Supported types include `provenance` and `sbom`. + + ```console + $ docker buildx history inspect attachment qu2gsuo8ejqrwdfii23xkkckt --type provenance + { + "_type": "https://slsa.dev/provenance/v0.2", + "buildDefinition": { + "buildType": "https://build.docker.com/BuildKit@v1", + "externalParameters": { + "target": "app", + "platforms": ["linux/amd64"] + } + }, + "runDetails": { + "builder": "docker", + "by": "ci@docker.com" + } + } + ``` + + ### Inspect a SBOM for linux/amd64 + + ```console + $ docker buildx history inspect attachment ^0 \ + --type sbom \ + --platform linux/amd64 + { + "bomFormat": "CycloneDX", + "specVersion": "1.5", + "version": 1, + "components": [ + { + "type": "library", + "name": "alpine", + "version": "3.18.2" + } + ] + } + ``` + + ### Inspect an attachment by digest + + You can inspect an attachment directly using its digset, which you can get from + the `inspect` output: + + ```console + # Using a build ID + docker buildx history inspect attachment qu2gsuo8ejqrwdfii23xkkckt sha256:abcdef123456... + + # Or using a relative offset + docker buildx history inspect attachment ^0 sha256:abcdef123456... + ``` + + Use `--type sbom` or `--type provenance` to filter attachments by type. To + inspect a specific attachment by digest, omit the `--type` flag. deprecated: false hidden: false experimental: false diff --git a/data/buildx/docker_buildx_history_logs.yaml b/data/buildx/docker_buildx_history_logs.yaml index c6afba47cda..3a15e9efd24 100644 --- a/data/buildx/docker_buildx_history_logs.yaml +++ b/data/buildx/docker_buildx_history_logs.yaml @@ -1,6 +1,15 @@ command: docker buildx history logs -short: Print the logs of a build -long: Print the logs of a build +short: Print the logs of a build record +long: |- + Print the logs for a completed build. The output appears in the same format as + `--progress=plain`, showing the full logs for each step. + + By default, this shows logs for the most recent build on the current builder. + + You can also specify an earlier build using an offset. For example: + + - `^1` shows logs for the build before the most recent + - `^2` shows logs for the build two steps back usage: docker buildx history logs [OPTIONS] [REF] pname: docker buildx history plink: docker_buildx_history.yaml @@ -9,6 +18,7 @@ options: value_type: string default_value: plain description: Set type of progress output (plain, rawjson, tty) + details_url: '#progress' deprecated: false hidden: false experimental: false @@ -36,6 +46,42 @@ inherited_options: experimentalcli: false kubernetes: false swarm: false +examples: |- + ### Print logs for the most recent build + + ```console + $ docker buildx history logs + #1 [internal] load build definition from Dockerfile + #1 transferring dockerfile: 31B done + #1 DONE 0.0s + #2 [internal] load .dockerignore + #2 transferring context: 2B done + #2 DONE 0.0s + ... + ``` + + By default, this shows logs for the most recent build on the current builder. + + ### Print logs for a specific build + + To print logs for a specific build, use a build ID or offset: + + ```console + # Using a build ID + docker buildx history logs qu2gsuo8ejqrwdfii23xkkckt + + # Or using a relative offset + docker buildx history logs ^1 + ``` + + ### Set type of progress output (--progress) {#progress} + + ```console + $ docker buildx history logs ^1 --progress rawjson + {"id":"buildx_step_1","status":"START","timestamp":"2024-05-01T12:34:56.789Z","detail":"[internal] load build definition from Dockerfile"} + {"id":"buildx_step_1","status":"COMPLETE","timestamp":"2024-05-01T12:34:57.001Z","duration":212000000} + ... + ``` deprecated: false hidden: false experimental: false diff --git a/data/buildx/docker_buildx_history_ls.yaml b/data/buildx/docker_buildx_history_ls.yaml index ab7a3abbb3b..d49eec62ce7 100644 --- a/data/buildx/docker_buildx_history_ls.yaml +++ b/data/buildx/docker_buildx_history_ls.yaml @@ -1,7 +1,12 @@ command: docker buildx history ls short: List build records -long: List build records -usage: docker buildx history ls +long: |- + List completed builds recorded by the active builder. Each entry includes the + build ID, name, status, timestamp, and duration. + + By default, only records for the current builder are shown. You can filter + results using flags. +usage: docker buildx history ls [OPTIONS] pname: docker buildx history plink: docker_buildx_history.yaml options: @@ -9,6 +14,7 @@ options: value_type: stringArray default_value: '[]' description: Provide filter values (e.g., `status=error`) + details_url: '#filter' deprecated: false hidden: false experimental: false @@ -19,6 +25,7 @@ options: value_type: string default_value: table description: Format the output + details_url: '#format' deprecated: false hidden: false experimental: false @@ -29,6 +36,7 @@ options: value_type: bool default_value: "false" description: List records for current repository only + details_url: '#local' deprecated: false hidden: false experimental: false @@ -39,6 +47,7 @@ options: value_type: bool default_value: "false" description: Don't truncate output + details_url: '#no-trunc' deprecated: false hidden: false experimental: false @@ -66,6 +75,80 @@ inherited_options: experimentalcli: false kubernetes: false swarm: false +examples: |- + ### List all build records for the current builder + + ```console + $ docker buildx history ls + BUILD ID NAME STATUS CREATED AT DURATION + qu2gsuo8ejqrwdfii23xkkckt .dev/2850 Completed 3 days ago 1.4s + qsiifiuf1ad9pa9qvppc0z1l3 .dev/2850 Completed 3 days ago 1.3s + g9808bwrjrlkbhdamxklx660b .dev/3120 Completed 5 days ago 2.1s + ``` + + ### List failed builds (--filter) {#filter} + + ```console + docker buildx history ls --filter status=error + ``` + + You can filter the list using the `--filter` flag. Supported filters include: + + | Filter | Supported comparisons | Example | + |:---------------------------------------|:-------------------------------------------------|:---------------------------| + | `ref`, `repository`, `status` | Support `=` and `!=` comparisons | `--filter status!=success` | + | `startedAt`, `completedAt`, `duration` | Support `<` and `>` comparisons with time values | `--filter duration>30s` | + + You can combine multiple filters by repeating the `--filter` flag: + + ```console + docker buildx history ls --filter status=error --filter duration>30s + ``` + + ### List builds from the current project (--local) {#local} + + ```console + docker buildx history ls --local + ``` + + ### Display full output without truncation (--no-trunc) {#no-trunc} + + ```console + docker buildx history ls --no-trunc + ``` + + ### Format output (--format) {#format} + + #### JSON output + + ```console + $ docker buildx history ls --format json + [ + { + "ID": "qu2gsuo8ejqrwdfii23xkkckt", + "Name": ".dev/2850", + "Status": "Completed", + "CreatedAt": "2025-04-15T12:33:00Z", + "Duration": "1.4s" + }, + { + "ID": "qsiifiuf1ad9pa9qvppc0z1l3", + "Name": ".dev/2850", + "Status": "Completed", + "CreatedAt": "2025-04-15T12:29:00Z", + "Duration": "1.3s" + } + ] + ``` + + #### Go template output + + ```console + $ docker buildx history ls --format '{{.Name}} - {{.Duration}}' + .dev/2850 - 1.4s + .dev/2850 - 1.3s + .dev/3120 - 2.1s + ``` deprecated: false hidden: false experimental: false diff --git a/data/buildx/docker_buildx_history_open.yaml b/data/buildx/docker_buildx_history_open.yaml index e79b0ba5699..1b760fcf645 100644 --- a/data/buildx/docker_buildx_history_open.yaml +++ b/data/buildx/docker_buildx_history_open.yaml @@ -1,6 +1,8 @@ command: docker buildx history open -short: Open a build in Docker Desktop -long: Open a build in Docker Desktop +short: Open a build record in Docker Desktop +long: |- + Open a build record in Docker Desktop for visual inspection. This requires + Docker Desktop to be installed and running on the host machine. usage: docker buildx history open [OPTIONS] [REF] pname: docker buildx history plink: docker_buildx_history.yaml @@ -25,6 +27,24 @@ inherited_options: experimentalcli: false kubernetes: false swarm: false +examples: |- + ### Open the most recent build in Docker Desktop + + ```console + docker buildx history open + ``` + + By default, this opens the most recent build on the current builder. + + ### Open a specific build + + ```console + # Using a build ID + docker buildx history open qu2gsuo8ejqrwdfii23xkkckt + + # Or using a relative offset + docker buildx history open ^1 + ``` deprecated: false hidden: false experimental: false diff --git a/data/buildx/docker_buildx_history_rm.yaml b/data/buildx/docker_buildx_history_rm.yaml index aa3ddd173cb..2c35a727758 100644 --- a/data/buildx/docker_buildx_history_rm.yaml +++ b/data/buildx/docker_buildx_history_rm.yaml @@ -1,6 +1,9 @@ command: docker buildx history rm short: Remove build records -long: Remove build records +long: |- + Remove one or more build records from the current builder’s history. You can + remove specific builds by ID or offset, or delete all records at once using + the `--all` flag. usage: docker buildx history rm [OPTIONS] [REF...] pname: docker buildx history plink: docker_buildx_history.yaml @@ -9,6 +12,7 @@ options: value_type: bool default_value: "false" description: Remove all build records + details_url: '#all' deprecated: false hidden: false experimental: false @@ -36,6 +40,32 @@ inherited_options: experimentalcli: false kubernetes: false swarm: false +examples: |- + ### Remove a specific build + + ```console + # Using a build ID + docker buildx history rm qu2gsuo8ejqrwdfii23xkkckt + + # Or using a relative offset + docker buildx history rm ^1 + ``` + + ### Remove multiple builds + + ```console + # Using build IDs + docker buildx history rm qu2gsuo8ejqrwdfii23xkkckt qsiifiuf1ad9pa9qvppc0z1l3 + + # Or using relative offsets + docker buildx history rm ^1 ^2 + ``` + + ### Remove all build records from the current builder (--all) {#all} + + ```console + docker buildx history rm --all + ``` deprecated: false hidden: false experimental: false diff --git a/data/buildx/docker_buildx_history_trace.yaml b/data/buildx/docker_buildx_history_trace.yaml index 54a4f4cd787..866f7673843 100644 --- a/data/buildx/docker_buildx_history_trace.yaml +++ b/data/buildx/docker_buildx_history_trace.yaml @@ -1,6 +1,10 @@ command: docker buildx history trace short: Show the OpenTelemetry trace of a build record -long: Show the OpenTelemetry trace of a build record +long: |- + View the OpenTelemetry trace for a completed build. This command loads the + trace into a Jaeger UI viewer and opens it in your browser. + + This helps analyze build performance, step timing, and internal execution flows. usage: docker buildx history trace [OPTIONS] [REF] pname: docker buildx history plink: docker_buildx_history.yaml @@ -9,6 +13,7 @@ options: value_type: string default_value: 127.0.0.1:0 description: Address to bind the UI server + details_url: '#addr' deprecated: false hidden: false experimental: false @@ -17,7 +22,8 @@ options: swarm: false - option: compare value_type: string - description: Compare with another build reference + description: Compare with another build record + details_url: '#compare' deprecated: false hidden: false experimental: false @@ -45,6 +51,50 @@ inherited_options: experimentalcli: false kubernetes: false swarm: false +examples: |- + ### Open the OpenTelemetry trace for the most recent build + + This command starts a temporary Jaeger UI server and opens your default browser + to view the trace. + + ```console + docker buildx history trace + ``` + + ### Open the trace for a specific build + + ```console + # Using a build ID + docker buildx history trace qu2gsuo8ejqrwdfii23xkkckt + + # Or using a relative offset + docker buildx history trace ^1 + ``` + + ### Run the Jaeger UI on a specific port (--addr) {#addr} + + ```console + # Using a build ID + docker buildx history trace qu2gsuo8ejqrwdfii23xkkckt --addr 127.0.0.1:16686 + + # Or using a relative offset + docker buildx history trace ^1 --addr 127.0.0.1:16686 + ``` + + ### Compare two build traces (--compare) {#compare} + + Compare two specific builds by name: + + ```console + # Using build IDs + docker buildx history trace --compare=qu2gsuo8ejqrwdfii23xkkckt qsiifiuf1ad9pa9qvppc0z1l3 + + # Or using a single relative offset + docker buildx history trace --compare=^1 + ``` + + When you use a single reference with `--compare`, it compares that build + against the most recent one. deprecated: false hidden: false experimental: false diff --git a/data/buildx/docker_buildx_imagetools_create.yaml b/data/buildx/docker_buildx_imagetools_create.yaml index 4bcb085db3d..3ade4138ddc 100644 --- a/data/buildx/docker_buildx_imagetools_create.yaml +++ b/data/buildx/docker_buildx_imagetools_create.yaml @@ -10,7 +10,7 @@ long: |- a list or index, the output will be a manifest list, however you can disable this behavior with `--prefer-index=false` which attempts to preserve the source manifest format in the output. -usage: docker buildx imagetools create [OPTIONS] [SOURCE] [SOURCE...] +usage: docker buildx imagetools create [OPTIONS] [SOURCE...] pname: docker buildx imagetools plink: docker_buildx_imagetools.yaml options: diff --git a/data/buildx/docker_buildx_rm.yaml b/data/buildx/docker_buildx_rm.yaml index 94eed6c8da3..b5c632ebed1 100644 --- a/data/buildx/docker_buildx_rm.yaml +++ b/data/buildx/docker_buildx_rm.yaml @@ -3,7 +3,7 @@ short: Remove one or more builder instances long: |- Removes the specified or current builder. It is a no-op attempting to remove the default builder. -usage: docker buildx rm [OPTIONS] [NAME] [NAME...] +usage: docker buildx rm [OPTIONS] [NAME...] pname: docker buildx plink: docker_buildx.yaml options: diff --git a/go.mod b/go.mod index ebea548b95e..8a6351f1176 100644 --- a/go.mod +++ b/go.mod @@ -7,12 +7,12 @@ require ( github.com/docker/cli v28.1.1+incompatible // indirect github.com/docker/compose/v2 v2.36.0 // indirect github.com/docker/scout-cli v1.15.0 // indirect - github.com/moby/buildkit v0.21.1 // indirect + github.com/moby/buildkit v0.22.0-rc1 // indirect github.com/moby/moby v28.1.0-rc.2+incompatible // indirect ) replace ( - github.com/docker/buildx => github.com/docker/buildx v0.23.0 + github.com/docker/buildx => github.com/docker/buildx v0.24.0-rc1 github.com/docker/cli => github.com/docker/cli v28.1.0-rc.2+incompatible github.com/docker/compose/v2 => github.com/docker/compose/v2 v2.36.0 github.com/docker/scout-cli => github.com/docker/scout-cli v1.15.0 diff --git a/go.sum b/go.sum index 8e4053f2ce2..334f8f05b28 100644 --- a/go.sum +++ b/go.sum @@ -104,6 +104,7 @@ github.com/docker/buildx v0.22.0 h1:pGTcGZa+kxpYUlM/6ACsp1hXhkEDulz++RNXPdE8Afk= github.com/docker/buildx v0.22.0/go.mod h1:ThbnUe4kNiStlq6cLXruElyEdSTdPL3k/QerNUmPvHE= github.com/docker/buildx v0.23.0 h1:qoYhuWyZ6PVCrWbkxClLzBWDBCUkyFK6Chjzg6nU+V8= github.com/docker/buildx v0.23.0/go.mod h1:y/6Zf/y3Bf0zTWqgg8PuNFATcqnuhFmQuNf4VyrnPtg= +github.com/docker/buildx v0.24.0-rc1/go.mod h1:poh1qI/j0EMizaPUArN/l9gWKNKQDeLpJ66ZOIo96hE= github.com/docker/cli v24.0.2+incompatible h1:QdqR7znue1mtkXIJ+ruQMGQhpw2JzMJLRXp6zpzF6tM= github.com/docker/cli v24.0.2+incompatible/go.mod h1:JLrzqnKDaYBop7H2jaqPtU4hHvMKP+vjCwu2uszcLI8= github.com/docker/cli v24.0.4+incompatible h1:Y3bYF9ekNTm2VFz5U/0BlMdJy73D+Y1iAAZ8l63Ydzw=