diff --git a/.github/vale/Vocab/Industry/accept.txt b/.github/vale/Vocab/Industry/accept.txt index eb0f8a9198..6c4b090737 100644 --- a/.github/vale/Vocab/Industry/accept.txt +++ b/.github/vale/Vocab/Industry/accept.txt @@ -1,6 +1,7 @@ ARM AWS Amazon +Anchore Apple Artifactory Azure( Blob Storage)? @@ -43,7 +44,10 @@ QEMU RHEL Raspbian S3 +SBOMs? SLES +SLSA +SPDX SQLite Slack Snyk diff --git a/Gemfile b/Gemfile index 6ac458fb5c..72c950d75a 100644 --- a/Gemfile +++ b/Gemfile @@ -16,7 +16,7 @@ end gem 'rouge', '3.27.0' gem 'front_matter_parser', '1.0.1' -gem 'git', '1.12.0' +gem 'git', '1.13.0' gem 'html-proofer', '3.19.4' gem 'mdl', '0.11.0' gem 'octopress-hooks', '2.6.2' diff --git a/Gemfile.lock b/Gemfile.lock index 2a3593fcfc..6bdce6a01a 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -16,7 +16,7 @@ GEM ffi (1.15.5) forwardable-extended (2.6.0) front_matter_parser (1.0.1) - git (1.12.0) + git (1.13.0) addressable (~> 2.8) rchardet (~> 1.8) html-proofer (3.19.4) @@ -88,7 +88,7 @@ GEM parallel (1.22.1) pathutil (0.16.2) forwardable-extended (~> 2.6) - public_suffix (5.0.0) + public_suffix (5.0.1) racc (1.6.1) rainbow (3.1.1) rake (13.0.6) @@ -116,7 +116,7 @@ PLATFORMS DEPENDENCIES front_matter_parser (= 1.0.1) - git (= 1.12.0) + git (= 1.13.0) html-proofer (= 3.19.4) jekyll (= 4.2.2) jekyll-redirect-from diff --git a/_config.yml b/_config.yml index 313b83bdd2..e96dbac572 100644 --- a/_config.yml +++ b/_config.yml @@ -45,7 +45,7 @@ exclude: latest_engine_api_version: "1.41" docker_ce_version: "20.10" compose_v1_version: "1.29.2" -compose_version: "v2.14.2" +compose_version: "v2.15.1" compose_file_v3: "3.9" compose_file_v2: "2.4" machine_version: "0.16.0" @@ -171,7 +171,12 @@ fetch-remote: - repo: "https://github.com/docker/docker" default_branch: "master" - ref: "20.10" + # The default branch has separate files for each API version, so we can + # consume the swagger files from that branch (we only publish the ones + # that have been released through the stubs in the engine/api/ directory). + # Using the default (master) branch allows for API docs changes to be + # published without them being cherry-picked into the release branch. + ref: "master" paths: - dest: "engine/api" src: @@ -209,3 +214,9 @@ fetch-remote: - dest: "build/buildkit/toml-configuration.md" src: - "docs/buildkitd.toml.md" + - dest: "build/attestations/slsa-definitions.md" + src: + - "docs/attestations/slsa-definitions.md" + - dest: "build/attestations/attestation-storage.md" + src: + - "docs/attestations/attestation-storage.md" diff --git a/_data/buildx/docker_buildx_bake.yaml b/_data/buildx/docker_buildx_bake.yaml index af05e9180b..584f974df4 100644 --- a/_data/buildx/docker_buildx_bake.yaml +++ b/_data/buildx/docker_buildx_bake.yaml @@ -82,6 +82,16 @@ options: experimentalcli: false kubernetes: false swarm: false + - option: provenance + value_type: string + description: Shorthand for `--set=*.attest=type=provenance` + details_url: '#provenance' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: pull value_type: bool default_value: "false" @@ -103,6 +113,16 @@ options: experimentalcli: false kubernetes: false swarm: false + - option: sbom + value_type: string + description: Shorthand for `--set=*.attest=type=sbom` + details_url: '#sbom' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: set value_type: stringArray default_value: '[]' @@ -204,10 +224,18 @@ examples: |- Same as [`build --progress`](buildx_build.md#progress). + ### Create provenance attestations (--provenance) {#provenance} + + Same as [`build --provenance`](buildx_build.md#provenance). + ### Always attempt to pull a newer version of the image (--pull) {#pull} Same as `build --pull`. + ### Create SBOM attestations (--sbom) {#sbom} + + Same as [`build --sbom`](buildx_build.md#sbom). + ### Override target configurations from command line (--set) {#set} ``` diff --git a/_data/buildx/docker_buildx_build.yaml b/_data/buildx/docker_buildx_build.yaml index d97e90fb6f..964edce353 100644 --- a/_data/buildx/docker_buildx_build.yaml +++ b/_data/buildx/docker_buildx_build.yaml @@ -16,7 +16,7 @@ options: value_type: stringSlice default_value: '[]' description: 'Add a custom host-to-IP mapping (format: `host:ip`)' - details_url: /engine/reference/commandline/build/#add-entries-to-container-hosts-file---add-host + details_url: /engine/reference/commandline/build/#add-host deprecated: false hidden: false experimental: false @@ -35,6 +35,17 @@ options: experimentalcli: false kubernetes: false swarm: false + - option: attest + value_type: stringArray + default_value: '[]' + description: 'Attestation parameters (format: `type=sbom,generator=image`)' + details_url: '#attest' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: build-arg value_type: stringArray default_value: '[]' @@ -84,7 +95,7 @@ options: - option: cgroup-parent value_type: string description: Optional parent cgroup for the container - details_url: /engine/reference/commandline/build/#use-a-custom-parent-cgroup---cgroup-parent + details_url: /engine/reference/commandline/build/#cgroup-parent deprecated: false hidden: false experimental: false @@ -154,7 +165,7 @@ options: shorthand: f value_type: string description: 'Name of the Dockerfile (default: `PATH/Dockerfile`)' - details_url: /engine/reference/commandline/build/#specify-a-dockerfile--f + details_url: /engine/reference/commandline/build/#file deprecated: false hidden: false experimental: false @@ -324,6 +335,16 @@ options: experimentalcli: false kubernetes: false swarm: false + - option: provenance + value_type: string + description: Shortand for `--attest=type=provenance` + details_url: '#provenance' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: pull value_type: bool default_value: "false" @@ -366,6 +387,16 @@ options: experimentalcli: false kubernetes: false swarm: false + - option: sbom + value_type: string + description: Shorthand for `--attest=type=sbom` + details_url: '#sbom' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: secret value_type: stringArray default_value: '[]' @@ -426,7 +457,7 @@ options: value_type: stringArray default_value: '[]' description: 'Name and optionally a tag (format: `name:tag`)' - details_url: /engine/reference/commandline/build/#tag-an-image--t + details_url: /engine/reference/commandline/build/#tag deprecated: false hidden: false experimental: false @@ -436,7 +467,7 @@ options: - option: target value_type: string description: Set the target build stage to build - details_url: /engine/reference/commandline/build/#specifying-target-build-stage---target + details_url: /engine/reference/commandline/build/#target deprecated: false hidden: false experimental: false @@ -466,6 +497,30 @@ inherited_options: kubernetes: false swarm: false examples: |- + ### Create attestations (--attest) {#attest} + + ``` + --attest=type=sbom,... + --attest=type=provenance,... + ``` + + Create [image attestations](/build/attestations/). + BuildKit currently supports: + + - `sbom` - Software Bill of Materials. + + Use `--attest=type=sbom` to generate an SBOM for an image at build-time. + Alternatively, you can use the [`--sbom` shorthand](#sbom). + + For more information, see [here](/build/attestations/sbom/). + + - `provenance` - SLSA Provenance + + Use `--attest=type=provenance` to generate provenance for an image at + build-time. Alternatively, you can use the [`--provenance` shorthand](#provenance). + + For more information, see [here](/build/attestations/slsa-provenance/). + ### Allow extra privileged entitlement (--allow) {#allow} ``` @@ -490,7 +545,7 @@ examples: |- ### Set build-time variables (--build-arg) {#build-arg} - Same as [`docker build` command](/engine/reference/commandline/build/#set-build-time-variables---build-arg). + Same as [`docker build` command](/engine/reference/commandline/build/#build-arg). There are also useful built-in build args like: @@ -531,36 +586,33 @@ examples: |- # docker buildx build --build-context project=https://github.com/myuser/project.git . ``` - ```Dockerfile + ```dockerfile + # syntax=docker/dockerfile:1 FROM alpine COPY --from=project myfile / ``` #### Source image from OCI layout directory {#source-oci-layout} - Source an image from a local [OCI layout compliant directory](https://github.com/opencontainers/image-spec/blob/main/image-layout.md): + Source an image from a local [OCI layout compliant directory](https://github.com/opencontainers/image-spec/blob/main/image-layout.md), + either by tag, or by digest: ```console - $ docker buildx build --build-context foo=oci-layout:///path/to/local/layout@sha256:abcd12345 . + $ docker buildx build --build-context foo=oci-layout:///path/to/local/layout: + $ docker buildx build --build-context foo=oci-layout:///path/to/local/layout@sha256: ``` - ```Dockerfile + ```dockerfile + # syntax=docker/dockerfile:1 FROM alpine RUN apk add git - COPY --from=foo myfile / FROM foo ``` - The OCI layout directory must be compliant with the [OCI layout specification](https://github.com/opencontainers/image-spec/blob/main/image-layout.md). It looks _solely_ for hashes. It does not - do any form of `image:tag` resolution to find the hash of the manifest; that is up to you. - - The format of the `--build-context` must be: `=oci-layout://@sha256:`, where: - - * `context` is the name of the build context as used in the `Dockerfile`. - * `path-to-local-layout` is the path on the local machine, where you are running `docker build`, to the spec-compliant OCI layout. - * `hash-of-manifest` is the hash of the manifest for the image. It can be a single-architecture manifest or a multi-architecture index. + The OCI layout directory must be compliant with the [OCI layout specification](https://github.com/opencontainers/image-spec/blob/main/image-layout.md). + You can reference an image in the layout using either tags, or the exact digest. ### Override the configured builder instance (--builder) {#builder} @@ -573,7 +625,7 @@ examples: |- ``` Use an external cache source for a build. Supported types are `registry`, - `local` and `gha`. + `local`, `gha` and `s3`. - [`registry` source](https://github.com/moby/buildkit#registry-push-image-and-cache-separately) can import cache from a cache manifest or (special) image configuration on the @@ -583,6 +635,9 @@ examples: |- - [`gha` source](https://github.com/moby/buildkit#github-actions-cache-experimental) can import cache from a previously exported cache with `--cache-to` in your GitHub repository + - [`s3` source](https://github.com/moby/buildkit#s3-cache-experimental) + can import cache from a previously exported cache with `--cache-to` in your + S3 bucket If no type is specified, `registry` exporter is used with a specified reference. @@ -594,6 +649,7 @@ examples: |- $ docker buildx build --cache-from=type=registry,ref=user/app . $ docker buildx build --cache-from=type=local,src=path/to/cache . $ docker buildx build --cache-from=type=gha . + $ docker buildx build --cache-from=type=s3,region=eu-west-1,bucket=mybucket . ``` More info about cache exporters and available attributes: https://github.com/moby/buildkit#export-cache @@ -605,15 +661,17 @@ examples: |- ``` Export build cache to an external cache destination. Supported types are - `registry`, `local`, `inline` and `gha`. + `registry`, `local`, `inline`, `gha` and `s3`. - [`registry` type](https://github.com/moby/buildkit#registry-push-image-and-cache-separately) exports build cache to a cache manifest in the registry. - - [`local` type](https://github.com/moby/buildkit#local-directory-1) type - exports cache to a local directory on the client. + - [`local` type](https://github.com/moby/buildkit#local-directory-1) exports + cache to a local directory on the client. - [`inline` type](https://github.com/moby/buildkit#inline-push-image-and-cache-together) - type writes the cache metadata into the image configuration. + writes the cache metadata into the image configuration. - [`gha` type](https://github.com/moby/buildkit#github-actions-cache-experimental) - type exports cache through the [Github Actions Cache service API](https://github.com/tonistiigi/go-actions-cache/blob/master/api.md#authentication). + exports cache through the [GitHub Actions Cache service API](https://github.com/tonistiigi/go-actions-cache/blob/master/api.md#authentication). + - [`s3` type](https://github.com/moby/buildkit#s3-cache-experimental) exports + cache to a S3 bucket. `docker` driver currently only supports exporting inline cache metadata to image configuration. Alternatively, `--build-arg BUILDKIT_INLINE_CACHE=1` can be used @@ -631,6 +689,7 @@ examples: |- $ docker buildx build --cache-to=type=registry,ref=user/app . $ docker buildx build --cache-to=type=local,dest=path/to/cache . $ docker buildx build --cache-to=type=gha . + $ docker buildx build --cache-to=type=s3,region=eu-west-1,bucket=mybucket . ``` More info about cache exporters and available attributes: https://github.com/moby/buildkit#export-cache @@ -847,11 +906,21 @@ examples: |- > Check also our [Color output controls guide](https://github.com/docker/buildx/blob/master/docs/guides/color-output.md) > for modifying the colors that are used to output information to the terminal. + ### Create provenance attestations (--provenance) {#provenance} + + Shorthand for [`--attest=type=provenance`](#attest). Enables provenance + attestations for the build result. + ### Push the build result to a registry (--push) {#push} Shorthand for [`--output=type=registry`](#registry). Will automatically push the build result to registry. + ### Create SBOM attestations (--sbom) {#sbom} + + Shorthand for [`--attest=type=sbom`](#attest). Enables SBOM attestations for + the build result. + ### Secret to expose to the build (--secret) {#secret} ``` @@ -871,7 +940,7 @@ examples: |- - `src`, `source` - Secret filename. `id` used if unset. ```dockerfile - # syntax=docker/dockerfile:1.4 + # syntax=docker/dockerfile:1 FROM python:3 RUN pip install awscli RUN --mount=type=secret,id=aws,target=/root/.aws/credentials \ @@ -890,7 +959,7 @@ examples: |- - `env` - Secret environment variable. `id` used if unset, otherwise will look for `src`, `source` if `id` unset. ```dockerfile - # syntax=docker/dockerfile:1.4 + # syntax=docker/dockerfile:1 FROM node:alpine RUN --mount=type=bind,target=. \ --mount=type=secret,id=SECRET_TOKEN \ @@ -922,7 +991,7 @@ examples: |- Example to access Gitlab using an SSH agent socket: ```dockerfile - # syntax=docker/dockerfile:1.4 + # syntax=docker/dockerfile:1 FROM alpine RUN apk add --no-cache openssh-client RUN mkdir -p -m 0700 ~/.ssh && ssh-keyscan gitlab.com >> ~/.ssh/known_hosts diff --git a/_data/buildx/docker_buildx_create.yaml b/_data/buildx/docker_buildx_create.yaml index d4b5392a29..34065598c4 100644 --- a/_data/buildx/docker_buildx_create.yaml +++ b/_data/buildx/docker_buildx_create.yaml @@ -35,6 +35,14 @@ options: experimentalcli: false kubernetes: false swarm: false + - option: builder + value_type: string + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: buildkitd-flags value_type: string description: Flags for buildkitd daemon @@ -130,16 +138,6 @@ options: experimentalcli: false kubernetes: false swarm: false -inherited_options: - - option: builder - value_type: string - description: Override the configured builder instance - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false examples: |- ### Append a new node to an existing builder (--append) {#append} diff --git a/_data/buildx/docker_buildx_imagetools_inspect.yaml b/_data/buildx/docker_buildx_imagetools_inspect.yaml index 2e2a02e2e6..d7ebf80dd2 100644 --- a/_data/buildx/docker_buildx_imagetools_inspect.yaml +++ b/_data/buildx/docker_buildx_imagetools_inspect.yaml @@ -88,7 +88,6 @@ examples: |- * `.Name`: provides the reference of the image * `.Manifest`: provides the manifest or manifest list * `.Image`: provides the image config - * `.BuildInfo`: provides [build info from image config](https://github.com/moby/buildkit/blob/master/docs/build-repro.md#image-config) #### `.Name` @@ -138,39 +137,6 @@ examples: |- Platform: linux/riscv64 ``` - #### `.BuildInfo` - - ```console - $ docker buildx imagetools inspect crazymax/buildx:buildinfo --format "{{.BuildInfo}}" - Name: docker.io/crazymax/buildx:buildinfo - Frontend: dockerfile.v0 - Attrs: - filename: Dockerfile - source: docker/dockerfile-upstream:master-labs - build-arg:bar: foo - build-arg:foo: bar - Sources: - Type: docker-image - Ref: docker.io/docker/buildx-bin:0.6.1@sha256:a652ced4a4141977c7daaed0a074dcd9844a78d7d2615465b12f433ae6dd29f0 - Pin: sha256:a652ced4a4141977c7daaed0a074dcd9844a78d7d2615465b12f433ae6dd29f0 - - Type: docker-image - Ref: docker.io/library/alpine:3.13 - Pin: sha256:026f721af4cf2843e07bba648e158fb35ecc876d822130633cc49f707f0fc88c - - Type: docker-image - Ref: docker.io/moby/buildkit:v0.9.0 - Pin: sha256:8dc668e7f66db1c044aadbed306020743516a94848793e0f81f94a087ee78cab - - Type: docker-image - Ref: docker.io/tonistiigi/xx@sha256:21a61be4744f6531cb5f33b0e6f40ede41fa3a1b8c82d5946178f80cc84bfc04 - Pin: sha256:21a61be4744f6531cb5f33b0e6f40ede41fa3a1b8c82d5946178f80cc84bfc04 - - Type: http - Ref: https://raw.githubusercontent.com/moby/moby/master/README.md - Pin: sha256:419455202b0ef97e480d7f8199b26a721a417818bc0e2d106975f74323f25e6c - ``` - #### JSON output A `json` go template func is also available if you want to render fields as @@ -182,7 +148,7 @@ examples: |- ```json { "mediaType": "application/vnd.docker.distribution.manifest.v2+json", - "digest": "sha256:08602e7340970e92bde5e0a2e887c1fde4d9ae753d1e05efb4c8ef3b609f97f1", + "digest": "sha256:a9ca35b798e0b198f9be7f3b8b53982e9a6cf96814cb10d78083f40ad8c127f1", "size": 949 } ``` @@ -193,23 +159,23 @@ examples: |- ```json { "schemaVersion": 2, - "mediaType": "application/vnd.docker.distribution.manifest.list.v2+json", - "digest": "sha256:79d97f205e2799d99a3a8ae2a1ef17acb331e11784262c3faada847dc6972c52", - "size": 2010, + "mediaType": "application/vnd.oci.image.index.v1+json", + "digest": "sha256:d895e8fdcf5e2bb39acb5966f97fc4cd87a2d13d27c939c320025eb4aca5440c", + "size": 4654, "manifests": [ { - "mediaType": "application/vnd.docker.distribution.manifest.v2+json", - "digest": "sha256:bd1e78f06de26610fadf4eb9d04b1a45a545799d6342701726e952cc0c11c912", - "size": 1158, + "mediaType": "application/vnd.oci.image.manifest.v1+json", + "digest": "sha256:ac9dd4fbec9e36b562f910618975a2936533f8e411a3fea2858aacc0ac972e1c", + "size": 1054, "platform": { "architecture": "amd64", "os": "linux" } }, { - "mediaType": "application/vnd.docker.distribution.manifest.v2+json", - "digest": "sha256:d37dcced63ec0965824fca644f0ac9efad8569434ec15b4c83adfcb3dcfc743b", - "size": 1158, + "mediaType": "application/vnd.oci.image.manifest.v1+json", + "digest": "sha256:0f4dc6797db467372cbf52c7236816203654a839f64a6542c9135d1973c9d744", + "size": 1054, "platform": { "architecture": "arm", "os": "linux", @@ -217,260 +183,356 @@ examples: |- } }, { - "mediaType": "application/vnd.docker.distribution.manifest.v2+json", - "digest": "sha256:ce142eb2255e6af46f2809e159fd03081697c7605a3de03b9cbe9a52ddb244bf", - "size": 1158, + "mediaType": "application/vnd.oci.image.manifest.v1+json", + "digest": "sha256:d62bb533d95afe17c4a9caf1e7c57a3b0a7a67409ccfa7af947aeb0f670ffb87", + "size": 1054, "platform": { "architecture": "arm64", "os": "linux" } }, { - "mediaType": "application/vnd.docker.distribution.manifest.v2+json", - "digest": "sha256:f59bfb5062fff76ce464bfa4e25ebaaaac887d6818238e119d68613c456d360c", - "size": 1158, + "mediaType": "application/vnd.oci.image.manifest.v1+json", + "digest": "sha256:b4944057e0c68203cdcc3dceff3b2df3c7d9e3dd801724fa977b01081da7771e", + "size": 1054, "platform": { "architecture": "s390x", "os": "linux" } }, { - "mediaType": "application/vnd.docker.distribution.manifest.v2+json", - "digest": "sha256:cc96426e0c50a78105d5637d31356db5dd6ec594f21b24276e534a32da09645c", - "size": 1159, + "mediaType": "application/vnd.oci.image.manifest.v1+json", + "digest": "sha256:825702a51eb4234904fc9253d8b0bf0a584787ffd8fc3fd6fa374188233ce399", + "size": 1054, "platform": { "architecture": "ppc64le", "os": "linux" } }, { - "mediaType": "application/vnd.docker.distribution.manifest.v2+json", - "digest": "sha256:39f9c1e2878e6c333acb23187d6b205ce82ed934c60da326cb2c698192631478", - "size": 1158, + "mediaType": "application/vnd.oci.image.manifest.v1+json", + "digest": "sha256:dfb27c6acc9b9f3a7c9d47366d137089565062f43c8063c9f5e408d34c87ee4a", + "size": 1054, "platform": { "architecture": "riscv64", "os": "linux" } + }, + { + "mediaType": "application/vnd.oci.image.manifest.v1+json", + "digest": "sha256:f2fe69bccc878e658caf21dfc99eaf726fb20d28f17398c1d66a90e62cc019f9", + "size": 1113, + "annotations": { + "vnd.docker.reference.digest": "sha256:ac9dd4fbec9e36b562f910618975a2936533f8e411a3fea2858aacc0ac972e1c", + "vnd.docker.reference.type": "attestation-manifest" + }, + "platform": { + "architecture": "unknown", + "os": "unknown" + } + }, + { + "mediaType": "application/vnd.oci.image.manifest.v1+json", + "digest": "sha256:9e112f8d4e383186f36369fba7b454e246d2e9ca5def797f1b84ede265e9f3ca", + "size": 1113, + "annotations": { + "vnd.docker.reference.digest": "sha256:0f4dc6797db467372cbf52c7236816203654a839f64a6542c9135d1973c9d744", + "vnd.docker.reference.type": "attestation-manifest" + }, + "platform": { + "architecture": "unknown", + "os": "unknown" + } + }, + { + "mediaType": "application/vnd.oci.image.manifest.v1+json", + "digest": "sha256:09d593587f8665269ec6753eaed7fbdb09968f71587dd53e06519502cbc16775", + "size": 1113, + "annotations": { + "vnd.docker.reference.digest": "sha256:d62bb533d95afe17c4a9caf1e7c57a3b0a7a67409ccfa7af947aeb0f670ffb87", + "vnd.docker.reference.type": "attestation-manifest" + }, + "platform": { + "architecture": "unknown", + "os": "unknown" + } + }, + { + "mediaType": "application/vnd.oci.image.manifest.v1+json", + "digest": "sha256:985a3f4544dfb042db6a8703f5f76438667dd7958aba14cb04bebe3b4cbd9307", + "size": 1113, + "annotations": { + "vnd.docker.reference.digest": "sha256:b4944057e0c68203cdcc3dceff3b2df3c7d9e3dd801724fa977b01081da7771e", + "vnd.docker.reference.type": "attestation-manifest" + }, + "platform": { + "architecture": "unknown", + "os": "unknown" + } + }, + { + "mediaType": "application/vnd.oci.image.manifest.v1+json", + "digest": "sha256:cfccb6afeede7dc29bf8abef4815d56f2723fa482ea63c9cd519cd991c379294", + "size": 1113, + "annotations": { + "vnd.docker.reference.digest": "sha256:825702a51eb4234904fc9253d8b0bf0a584787ffd8fc3fd6fa374188233ce399", + "vnd.docker.reference.type": "attestation-manifest" + }, + "platform": { + "architecture": "unknown", + "os": "unknown" + } + }, + { + "mediaType": "application/vnd.oci.image.manifest.v1+json", + "digest": "sha256:2e93733432c6a14cb57db33928b3a17d7ca298b3babe24d9f56dca2754dbde3b", + "size": 1113, + "annotations": { + "vnd.docker.reference.digest": "sha256:dfb27c6acc9b9f3a7c9d47366d137089565062f43c8063c9f5e408d34c87ee4a", + "vnd.docker.reference.type": "attestation-manifest" + }, + "platform": { + "architecture": "unknown", + "os": "unknown" + } } ] } ``` + Following command provides [SLSA](https://github.com/moby/buildkit/blob/master/docs/attestations/slsa-provenance.md) JSON output: + ```console - $ docker buildx imagetools inspect crazymax/buildx:buildinfo --format "{{json .BuildInfo}}" + $ docker buildx imagetools inspect crazymax/buildkit:attest --format "{{json .Provenance}}" ``` ```json { - "frontend": "dockerfile.v0", - "attrs": { - "build-arg:bar": "foo", - "build-arg:foo": "bar", - "filename": "Dockerfile", - "source": "crazymax/dockerfile:buildattrs" - }, - "sources": [ - { - "type": "docker-image", - "ref": "docker.io/docker/buildx-bin:0.6.1@sha256:a652ced4a4141977c7daaed0a074dcd9844a78d7d2615465b12f433ae6dd29f0", - "pin": "sha256:a652ced4a4141977c7daaed0a074dcd9844a78d7d2615465b12f433ae6dd29f0" + "SLSA": { + "builder": { + "id": "" }, - { - "type": "docker-image", - "ref": "docker.io/library/alpine:3.13@sha256:026f721af4cf2843e07bba648e158fb35ecc876d822130633cc49f707f0fc88c", - "pin": "sha256:026f721af4cf2843e07bba648e158fb35ecc876d822130633cc49f707f0fc88c" + "buildType": "https://mobyproject.org/buildkit@v1", + "materials": [ + { + "uri": "pkg:docker/docker/buildkit-syft-scanner@stable-1", + "digest": { + "sha256": "b45f1d207e16c3a3a5a10b254ad8ad358d01f7ea090d382b95c6b2ee2b3ef765" + } + }, + { + "uri": "pkg:docker/alpine@latest?platform=linux%2Famd64", + "digest": { + "sha256": "8914eb54f968791faf6a8638949e480fef81e697984fba772b3976835194c6d4" + } + } + ], + "invocation": { + "configSource": {}, + "parameters": { + "frontend": "dockerfile.v0", + "locals": [ + { + "name": "context" + }, + { + "name": "dockerfile" + } + ] + }, + "environment": { + "platform": "linux/amd64" + } }, - { - "type": "docker-image", - "ref": "docker.io/moby/buildkit:v0.9.0@sha256:8dc668e7f66db1c044aadbed306020743516a94848793e0f81f94a087ee78cab", - "pin": "sha256:8dc668e7f66db1c044aadbed306020743516a94848793e0f81f94a087ee78cab" - }, - { - "type": "docker-image", - "ref": "docker.io/tonistiigi/xx@sha256:21a61be4744f6531cb5f33b0e6f40ede41fa3a1b8c82d5946178f80cc84bfc04", - "pin": "sha256:21a61be4744f6531cb5f33b0e6f40ede41fa3a1b8c82d5946178f80cc84bfc04" - }, - { - "type": "http", - "ref": "https://raw.githubusercontent.com/moby/moby/master/README.md", - "pin": "sha256:419455202b0ef97e480d7f8199b26a721a417818bc0e2d106975f74323f25e6c" + "metadata": { + "buildInvocationID": "02tdha2xkbxvin87mz9drhag4", + "buildStartedOn": "2022-12-01T11:50:07.264704131Z", + "buildFinishedOn": "2022-12-01T11:50:08.243788739Z", + "reproducible": false, + "completeness": { + "parameters": true, + "environment": true, + "materials": false + }, + "https://mobyproject.org/buildkit@v1#metadata": {} } - ] + } + } + ``` + + Following command provides [SBOM](https://github.com/moby/buildkit/blob/master/docs/attestations/sbom.md) JSON output: + + ```console + $ docker buildx imagetools inspect crazymax/buildkit:attest --format "{{json .SBOM}}" + ``` + ```json + { + "SPDX": { + "SPDXID": "SPDXRef-DOCUMENT", + "creationInfo": { + "created": "2022-12-01T11:46:48.063400162Z", + "creators": [ + "Tool: syft-v0.60.3", + "Tool: buildkit-1ace2bb", + "Organization: Anchore, Inc" + ], + "licenseListVersion": "3.18" + }, + "dataLicense": "CC0-1.0", + "documentNamespace": "https://anchore.com/syft/dir/run/src/core-0a4ccc6d-1a72-4c3a-a40e-3df1a2ffca94", + "files": [...], + "spdxVersion": "SPDX-2.2" + } } ``` ```console - $ docker buildx imagetools inspect crazymax/buildx:buildinfo --format "{{json .}}" + $ docker buildx imagetools inspect crazymax/buildkit:attest --format "{{json .}}" ``` ```json { - "name": "crazymax/buildx:buildinfo", + "name": "crazymax/buildkit:attest", "manifest": { - "mediaType": "application/vnd.docker.distribution.manifest.v2+json", - "digest": "sha256:899d2c7acbc124d406820857bb51d9089717bbe4e22b97eb4bc5789e99f09f83", - "size": 2628 + "schemaVersion": 2, + "mediaType": "application/vnd.oci.image.index.v1+json", + "digest": "sha256:7007b387ccd52bd42a050f2e8020e56e64622c9269bf7bbe257b326fe99daf19", + "size": 855, + "manifests": [ + { + "mediaType": "application/vnd.oci.image.manifest.v1+json", + "digest": "sha256:fbd10fe50b4b174bb9ea273e2eb9827fa8bf5c88edd8635a93dc83e0d1aecb55", + "size": 673, + "platform": { + "architecture": "amd64", + "os": "linux" + } + }, + { + "mediaType": "application/vnd.oci.image.manifest.v1+json", + "digest": "sha256:a9de632c16998489fd63fbca42a03431df00639cfb2ecb8982bf9984b83c5b2b", + "size": 839, + "annotations": { + "vnd.docker.reference.digest": "sha256:fbd10fe50b4b174bb9ea273e2eb9827fa8bf5c88edd8635a93dc83e0d1aecb55", + "vnd.docker.reference.type": "attestation-manifest" + }, + "platform": { + "architecture": "unknown", + "os": "unknown" + } + } + ] }, "image": { - "created": "2022-02-24T12:27:43.627154558Z", + "created": "2022-12-01T11:46:47.713777178Z", "architecture": "amd64", "os": "linux", "config": { "Env": [ - "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin", - "DOCKER_TLS_CERTDIR=/certs", - "DOCKER_CLI_EXPERIMENTAL=enabled" - ], - "Entrypoint": [ - "docker-entrypoint.sh" + "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" ], "Cmd": [ - "sh" + "/bin/sh" ] }, "rootfs": { "type": "layers", "diff_ids": [ - "sha256:7fcb75871b2101082203959c83514ac8a9f4ecfee77a0fe9aa73bbe56afdf1b4", - "sha256:d3c0b963ff5684160641f936d6a4aa14efc8ff27b6edac255c07f2d03ff92e82", - "sha256:3f8d78f13fa9b1f35d3bc3f1351d03a027c38018c37baca73f93eecdea17f244", - "sha256:8e6eb1137b182ae0c3f5d40ca46341fda2eaeeeb5fa516a9a2bf96171238e2e0", - "sha256:fde4c869a56b54dd76d7352ddaa813fd96202bda30b9dceb2c2f2ad22fa2e6ce", - "sha256:52025823edb284321af7846419899234b3c66219bf06061692b709875ed0760f", - "sha256:50adb5982dbf6126c7cf279ac3181d1e39fc9116b610b947a3dadae6f7e7c5bc", - "sha256:9801c319e1c66c5d295e78b2d3e80547e73c7e3c63a4b71e97c8ca357224af24", - "sha256:dfbfac44d5d228c49b42194c8a2f470abd6916d072f612a6fb14318e94fde8ae", - "sha256:3dfb74e19dedf61568b917c19b0fd3ee4580870027ca0b6054baf239855d1322", - "sha256:b182e707c23e4f19be73f9022a99d2d1ca7bf1ca8f280d40e4d1c10a6f51550e" + "sha256:ded7a220bb058e28ee3254fbba04ca90b679070424424761a53a043b93b612bf", + "sha256:d85d09ab4b4e921666ccc2db8532e857bf3476b7588e52c9c17741d7af14204f" ] }, "history": [ { - "created": "2021-11-12T17:19:58.698676655Z", - "created_by": "/bin/sh -c #(nop) ADD file:5a707b9d6cb5fff532e4c2141bc35707593f21da5528c9e71ae2ddb6ba4a4eb6 in / " + "created": "2022-11-22T22:19:28.870801855Z", + "created_by": "/bin/sh -c #(nop) ADD file:587cae71969871d3c6456d844a8795df9b64b12c710c275295a1182b46f630e7 in / " }, { - "created": "2021-11-12T17:19:58.948920855Z", + "created": "2022-11-22T22:19:29.008562326Z", "created_by": "/bin/sh -c #(nop) CMD [\"/bin/sh\"]", "empty_layer": true }, { - "created": "2022-02-24T12:27:38.285594601Z", - "created_by": "RUN /bin/sh -c apk --update --no-cache add bash ca-certificates openssh-client \u0026\u0026 rm -rf /tmp/* /var/cache/apk/* # buildkit", + "created": "2022-12-01T11:46:47.713777178Z", + "created_by": "RUN /bin/sh -c apk add curl # buildkit", "comment": "buildkit.dockerfile.v0" - }, - { - "created": "2022-02-24T12:27:41.061874167Z", - "created_by": "COPY /opt/docker/ /usr/local/bin/ # buildkit", - "comment": "buildkit.dockerfile.v0" - }, - { - "created": "2022-02-24T12:27:41.174098947Z", - "created_by": "COPY /usr/bin/buildctl /usr/local/bin/buildctl # buildkit", - "comment": "buildkit.dockerfile.v0" - }, - { - "created": "2022-02-24T12:27:41.320343683Z", - "created_by": "COPY /usr/bin/buildkit* /usr/local/bin/ # buildkit", - "comment": "buildkit.dockerfile.v0" - }, - { - "created": "2022-02-24T12:27:41.447149933Z", - "created_by": "COPY /buildx /usr/libexec/docker/cli-plugins/docker-buildx # buildkit", - "comment": "buildkit.dockerfile.v0" - }, - { - "created": "2022-02-24T12:27:43.057722191Z", - "created_by": "COPY /opt/docker-compose /usr/libexec/docker/cli-plugins/docker-compose # buildkit", - "comment": "buildkit.dockerfile.v0" - }, - { - "created": "2022-02-24T12:27:43.145224134Z", - "created_by": "ADD https://raw.githubusercontent.com/moby/moby/master/README.md / # buildkit", - "comment": "buildkit.dockerfile.v0" - }, - { - "created": "2022-02-24T12:27:43.422212427Z", - "created_by": "ENV DOCKER_TLS_CERTDIR=/certs", - "comment": "buildkit.dockerfile.v0", - "empty_layer": true - }, - { - "created": "2022-02-24T12:27:43.422212427Z", - "created_by": "ENV DOCKER_CLI_EXPERIMENTAL=enabled", - "comment": "buildkit.dockerfile.v0", - "empty_layer": true - }, - { - "created": "2022-02-24T12:27:43.422212427Z", - "created_by": "RUN /bin/sh -c docker --version \u0026\u0026 buildkitd --version \u0026\u0026 buildctl --version \u0026\u0026 docker buildx version \u0026\u0026 docker compose version \u0026\u0026 mkdir /certs /certs/client \u0026\u0026 chmod 1777 /certs /certs/client # buildkit", - "comment": "buildkit.dockerfile.v0" - }, - { - "created": "2022-02-24T12:27:43.514320155Z", - "created_by": "COPY rootfs/modprobe.sh /usr/local/bin/modprobe # buildkit", - "comment": "buildkit.dockerfile.v0" - }, - { - "created": "2022-02-24T12:27:43.627154558Z", - "created_by": "COPY rootfs/docker-entrypoint.sh /usr/local/bin/ # buildkit", - "comment": "buildkit.dockerfile.v0" - }, - { - "created": "2022-02-24T12:27:43.627154558Z", - "created_by": "ENTRYPOINT [\"docker-entrypoint.sh\"]", - "comment": "buildkit.dockerfile.v0", - "empty_layer": true - }, - { - "created": "2022-02-24T12:27:43.627154558Z", - "created_by": "CMD [\"sh\"]", - "comment": "buildkit.dockerfile.v0", - "empty_layer": true } ] }, - "buildinfo": { - "frontend": "dockerfile.v0", - "attrs": { - "build-arg:bar": "foo", - "build-arg:foo": "bar", - "filename": "Dockerfile", - "source": "docker/dockerfile-upstream:master-labs" - }, - "sources": [ - { - "type": "docker-image", - "ref": "docker.io/docker/buildx-bin:0.6.1@sha256:a652ced4a4141977c7daaed0a074dcd9844a78d7d2615465b12f433ae6dd29f0", - "pin": "sha256:a652ced4a4141977c7daaed0a074dcd9844a78d7d2615465b12f433ae6dd29f0" + "Provenance": { + "SLSA": { + "builder": { + "id": "" }, - { - "type": "docker-image", - "ref": "docker.io/library/alpine:3.13", - "pin": "sha256:026f721af4cf2843e07bba648e158fb35ecc876d822130633cc49f707f0fc88c" + "buildType": "https://mobyproject.org/buildkit@v1", + "materials": [ + { + "uri": "pkg:docker/docker/buildkit-syft-scanner@stable-1", + "digest": { + "sha256": "b45f1d207e16c3a3a5a10b254ad8ad358d01f7ea090d382b95c6b2ee2b3ef765" + } + }, + { + "uri": "pkg:docker/alpine@latest?platform=linux%2Famd64", + "digest": { + "sha256": "8914eb54f968791faf6a8638949e480fef81e697984fba772b3976835194c6d4" + } + } + ], + "invocation": { + "configSource": {}, + "parameters": { + "frontend": "dockerfile.v0", + "locals": [ + { + "name": "context" + }, + { + "name": "dockerfile" + } + ] + }, + "environment": { + "platform": "linux/amd64" + } }, - { - "type": "docker-image", - "ref": "docker.io/moby/buildkit:v0.9.0", - "pin": "sha256:8dc668e7f66db1c044aadbed306020743516a94848793e0f81f94a087ee78cab" - }, - { - "type": "docker-image", - "ref": "docker.io/tonistiigi/xx@sha256:21a61be4744f6531cb5f33b0e6f40ede41fa3a1b8c82d5946178f80cc84bfc04", - "pin": "sha256:21a61be4744f6531cb5f33b0e6f40ede41fa3a1b8c82d5946178f80cc84bfc04" - }, - { - "type": "http", - "ref": "https://raw.githubusercontent.com/moby/moby/master/README.md", - "pin": "sha256:419455202b0ef97e480d7f8199b26a721a417818bc0e2d106975f74323f25e6c" + "metadata": { + "buildInvocationID": "02tdha2xkbxvin87mz9drhag4", + "buildStartedOn": "2022-12-01T11:50:07.264704131Z", + "buildFinishedOn": "2022-12-01T11:50:08.243788739Z", + "reproducible": false, + "completeness": { + "parameters": true, + "environment": true, + "materials": false + }, + "https://mobyproject.org/buildkit@v1#metadata": {} } - ] + } + }, + "SBOM": { + "SPDX": { + "SPDXID": "SPDXRef-DOCUMENT", + "creationInfo": { + "created": "2022-12-01T11:46:48.063400162Z", + "creators": [ + "Tool: syft-v0.60.3", + "Tool: buildkit-1ace2bb", + "Organization: Anchore, Inc" + ], + "licenseListVersion": "3.18" + }, + "dataLicense": "CC0-1.0", + "documentNamespace": "https://anchore.com/syft/dir/run/src/core-0a4ccc6d-1a72-4c3a-a40e-3df1a2ffca94", + "files": [...], + "spdxVersion": "SPDX-2.2" + } } } ``` #### Multi-platform - Multi-platform images are supported for `.Image` and `.BuildInfo` fields. If - you want to pick up a specific platform, you can specify it using the `index` + Multi-platform images are supported for `.Image`, `.SLSA` and `.SBOM` fields. + If you want to pick up a specific platform, you can specify it using the `index` go template function: ```console @@ -478,7 +540,7 @@ examples: |- ``` ```json { - "created": "2022-02-25T17:13:27.89891722Z", + "created": "2022-11-30T17:42:26.414957336Z", "architecture": "s390x", "os": "linux", "config": { @@ -497,8 +559,8 @@ examples: |- "diff_ids": [ "sha256:41048e32d0684349141cf05f629c5fc3c5915d1f3426b66dbb8953a540e01e1e", "sha256:2651209b9208fff6c053bc3c17353cb07874e50f1a9bc96d6afd03aef63de76a", - "sha256:6741ed7e73039d853fa8902246a4c7e8bf9dd09652fd1b08251bc5f9e8876a7f", - "sha256:92ac046adeeb65c86ae3f0b458dee04ad4a462e417661c04d77642c66494f69b" + "sha256:88577322e65f094ce8ac27435880f1a8a9baadb569258026bb141770451bafcb", + "sha256:de8f9a790e4ed10ff1f1f8ea923c9da4f97246a7e200add2dc6650eba3f10a20" ] }, "history": [ @@ -517,23 +579,23 @@ examples: |- "comment": "buildkit.dockerfile.v0" }, { - "created": "2022-02-24T00:34:00.924540012Z", + "created": "2022-08-25T00:39:25.652811078Z", "created_by": "COPY examples/buildctl-daemonless/buildctl-daemonless.sh /usr/bin/ # buildkit", "comment": "buildkit.dockerfile.v0" }, { - "created": "2022-02-25T17:13:27.89891722Z", + "created": "2022-11-30T17:42:26.414957336Z", "created_by": "VOLUME [/var/lib/buildkit]", "comment": "buildkit.dockerfile.v0", "empty_layer": true }, { - "created": "2022-02-25T17:13:27.89891722Z", + "created": "2022-11-30T17:42:26.414957336Z", "created_by": "COPY / /usr/bin/ # buildkit", "comment": "buildkit.dockerfile.v0" }, { - "created": "2022-02-25T17:13:27.89891722Z", + "created": "2022-11-30T17:42:26.414957336Z", "created_by": "ENTRYPOINT [\"buildkitd\"]", "comment": "buildkit.dockerfile.v0", "empty_layer": true @@ -557,24 +619,24 @@ examples: |- "schemaVersion": 2, "config": { "mediaType": "application/vnd.docker.container.image.v1+json", - "digest": "sha256:7ace7d324e79b360b2db8b820d83081863d96d22e734cdf297a8e7fd83f6ceb3", - "size": 2298 + "digest": "sha256:a98999183d2c7a8845f6d56496e51099ce6e4359ee7255504174b05430c4b78b", + "size": 2762 }, "layers": [ { "mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip", - "digest": "sha256:5843afab387455b37944e709ee8c78d7520df80f8d01cf7f861aae63beeddb6b", - "size": 2811478 + "digest": "sha256:8663204ce13b2961da55026a2034abb9e5afaaccf6a9cfb44ad71406dcd07c7b", + "size": 2818370 }, { "mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip", - "digest": "sha256:726d3732a87e1c430d67e8969de6b222a889d45e045ebae1a008a37ba38f3b1f", - "size": 1776812 + "digest": "sha256:f0868a92f8e1e5018ed4e60eb845ed4ff0e2229897f4105e5a4735c1d6fd874f", + "size": 1821402 }, { "mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip", - "digest": "sha256:5d7cf9b33148a8f220c84f27dd2cfae46aca019a3ea3fbf7274f6d6dbfae8f3b", - "size": 382855 + "digest": "sha256:d010066dbdfcf7c12fca30cd4b567aa7218eb6762ab53169d043655b7a8d7f2e", + "size": 404457 } ] } @@ -590,7 +652,7 @@ examples: |- "manifests": [ { "mediaType": "application/vnd.docker.distribution.manifest.v2+json", - "digest": "sha256:667d28c9fb33820ce686887a717a148e89fa77f9097f9352996bbcce99d352b1", + "digest": "sha256:f9f41c85124686c2afe330a985066748a91d7a5d505777fe274df804ab5e077e", "size": 1158, "platform": { "architecture": "amd64", @@ -599,7 +661,7 @@ examples: |- }, { "mediaType": "application/vnd.docker.distribution.manifest.v2+json", - "digest": "sha256:71789527b64ab3d7b3de01d364b449cd7f7a3da758218fbf73b9c9aae05a6775", + "digest": "sha256:82097c2be19c617aafb3c3e43c88548738d4b2bf3db5c36666283a918b390266", "size": 1158, "platform": { "architecture": "arm", @@ -609,7 +671,7 @@ examples: |- }, { "mediaType": "application/vnd.docker.distribution.manifest.v2+json", - "digest": "sha256:fb64667e1ce6ab0d05478f3a8402af07b27737598dcf9a510fb1d792b13a66be", + "digest": "sha256:b6b91e6c823d7220ded7d3b688e571ba800b13d91bbc904c1d8053593e3ee42c", "size": 1158, "platform": { "architecture": "arm64", @@ -618,7 +680,7 @@ examples: |- }, { "mediaType": "application/vnd.docker.distribution.manifest.v2+json", - "digest": "sha256:1c3ddf95a0788e23f72f25800c05abc4458946685e2b66788c3d978cde6da92b", + "digest": "sha256:797061bcc16778de048b96f769c018ec24da221088050bbe926ea3b8d51d77e8", "size": 1158, "platform": { "architecture": "s390x", @@ -627,7 +689,7 @@ examples: |- }, { "mediaType": "application/vnd.docker.distribution.manifest.v2+json", - "digest": "sha256:05bcde6d460a284e5bc88026cd070277e8380355de3126cbc8fe8a452708c6b1", + "digest": "sha256:b93d3a84d18c4d0b8c279e77343d854d9b5177df7ea55cf468d461aa2523364e", "size": 1159, "platform": { "architecture": "ppc64le", @@ -636,7 +698,7 @@ examples: |- }, { "mediaType": "application/vnd.docker.distribution.manifest.v2+json", - "digest": "sha256:c04c57765304ab84f4f9807fff3e11605c3a60e16435c734b02c723680f6bd6e", + "digest": "sha256:d5c950dd1b270d437c838187112a0cb44c9258248d7a3a8bcb42fae8f717dc01", "size": 1158, "platform": { "architecture": "riscv64", diff --git a/_data/buildx/docker_buildx_install.yaml b/_data/buildx/docker_buildx_install.yaml index 4e8ed387ef..9fe42f0919 100644 --- a/_data/buildx/docker_buildx_install.yaml +++ b/_data/buildx/docker_buildx_install.yaml @@ -4,12 +4,11 @@ long: Install buildx as a 'docker builder' alias usage: docker buildx install pname: docker buildx plink: docker_buildx.yaml -inherited_options: +options: - option: builder value_type: string - description: Override the configured builder instance deprecated: false - hidden: false + hidden: true experimental: false experimentalcli: false kubernetes: false diff --git a/_data/buildx/docker_buildx_ls.yaml b/_data/buildx/docker_buildx_ls.yaml index 00b3514b28..d78d5d38eb 100644 --- a/_data/buildx/docker_buildx_ls.yaml +++ b/_data/buildx/docker_buildx_ls.yaml @@ -19,12 +19,11 @@ long: |- usage: docker buildx ls pname: docker buildx plink: docker_buildx.yaml -inherited_options: +options: - option: builder value_type: string - description: Override the configured builder instance deprecated: false - hidden: false + hidden: true experimental: false experimentalcli: false kubernetes: false diff --git a/_data/buildx/docker_buildx_uninstall.yaml b/_data/buildx/docker_buildx_uninstall.yaml index 6a45c6c5be..b497999ad0 100644 --- a/_data/buildx/docker_buildx_uninstall.yaml +++ b/_data/buildx/docker_buildx_uninstall.yaml @@ -4,12 +4,11 @@ long: Uninstall the 'docker builder' alias usage: docker buildx uninstall pname: docker buildx plink: docker_buildx.yaml -inherited_options: +options: - option: builder value_type: string - description: Override the configured builder instance deprecated: false - hidden: false + hidden: true experimental: false experimentalcli: false kubernetes: false diff --git a/_data/buildx/docker_buildx_version.yaml b/_data/buildx/docker_buildx_version.yaml index 2e2abfa487..d6619459e4 100644 --- a/_data/buildx/docker_buildx_version.yaml +++ b/_data/buildx/docker_buildx_version.yaml @@ -10,12 +10,11 @@ long: |- usage: docker buildx version pname: docker buildx plink: docker_buildx.yaml -inherited_options: +options: - option: builder value_type: string - description: Override the configured builder instance deprecated: false - hidden: false + hidden: true experimental: false experimentalcli: false kubernetes: false diff --git a/_data/compose-cli/docker_compose_pull.yaml b/_data/compose-cli/docker_compose_pull.yaml index a06e8387fe..c07afde137 100644 --- a/_data/compose-cli/docker_compose_pull.yaml +++ b/_data/compose-cli/docker_compose_pull.yaml @@ -7,10 +7,20 @@ usage: docker compose pull [OPTIONS] [SERVICE...] pname: docker compose plink: docker_compose.yaml options: + - option: ignore-buildable + value_type: bool + default_value: "false" + description: Ignore images that can be built. + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: ignore-pull-failures value_type: bool default_value: "false" - description: Pull what it can and ignores images with pull failures + description: Pull what it can and ignores images with pull failures. deprecated: false hidden: false experimental: false @@ -20,7 +30,7 @@ options: - option: include-deps value_type: bool default_value: "false" - description: Also pull services declared as dependencies + description: Also pull services declared as dependencies. deprecated: false hidden: false experimental: false @@ -51,7 +61,7 @@ options: shorthand: q value_type: bool default_value: "false" - description: Pull without printing progress information + description: Pull without printing progress information. deprecated: false hidden: false experimental: false @@ -99,6 +109,9 @@ examples: |- ⠹ 77a0c198cde5 Waiting 9.3s ⠹ c8752d5b785c Waiting 9.3s ``` + + `docker compose pull` will try to pull image for services with a build section. If pull fails, it will let + user know this service image MUST be built. You can skip this by setting `--ignore-buildable` flag deprecated: false experimental: false experimentalcli: false diff --git a/_data/compose-cli/docker_compose_up.yaml b/_data/compose-cli/docker_compose_up.yaml index fd873ef7da..f8ab468e7b 100644 --- a/_data/compose-cli/docker_compose_up.yaml +++ b/_data/compose-cli/docker_compose_up.yaml @@ -6,6 +6,9 @@ long: |- Unless they are already running, this command also starts any linked services. The `docker compose up` command aggregates the output of each container (like `docker compose logs --follow` does). + One can optionally select a subset of services to attach to using `--attach` flag, or exclude some services using + `--no-attach` to prevent output to be flooded by some verbose services. + When the command exits, all containers are stopped. Running `docker compose up --detach` starts the containers in the background and leaves them running. @@ -104,6 +107,16 @@ options: experimentalcli: false kubernetes: false swarm: false + - option: no-attach + value_type: stringArray + default_value: '[]' + description: Don't attach to specified service. + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: no-build value_type: bool default_value: "false" diff --git a/_data/engine-cli/docker_attach.yaml b/_data/engine-cli/docker_attach.yaml index 062dfcd49c..e29783a11f 100644 --- a/_data/engine-cli/docker_attach.yaml +++ b/_data/engine-cli/docker_attach.yaml @@ -26,12 +26,12 @@ long: |- > so. It is forbidden to redirect the standard input of a `docker attach` command - while attaching to a tty-enabled container (i.e.: launched with `-t`). + while attaching to a TTY-enabled container (using the `-i` and `-t` options). - While a client is connected to container's stdio using `docker attach`, Docker - uses a ~1MB memory buffer to maximize the throughput of the application. If - this buffer is filled, the speed of the API connection will start to have an - effect on the process output writing speed. This is similar to other + While a client is connected to container's `stdio` using `docker attach`, Docker + uses a ~1MB memory buffer to maximize the throughput of the application. + Once this buffer is full, the speed of the API connection is affected, and so + this impacts the output process' writing speed. This is similar to other applications like SSH. Because of this, it is not recommended to run performance critical applications that generate a lot of output in the foreground over a slow client connection. Instead, users should use the @@ -93,45 +93,68 @@ options: examples: |- ### Attach to and detach from a running container + The following example starts an ubuntu container running `top` in detached mode, + then attaches to the container; + ```console - $ docker run -d --name topdemo ubuntu /usr/bin/top -b + $ docker run -d --name topdemo ubuntu:22.04 /usr/bin/top -b $ docker attach topdemo - top - 02:05:52 up 3:05, 0 users, load average: 0.01, 0.02, 0.05 + top - 12:27:44 up 3 days, 21:54, 0 users, load average: 0.00, 0.00, 0.00 Tasks: 1 total, 1 running, 0 sleeping, 0 stopped, 0 zombie - Cpu(s): 0.1%us, 0.2%sy, 0.0%ni, 99.7%id, 0.0%wa, 0.0%hi, 0.0%si, 0.0%st - Mem: 373572k total, 355560k used, 18012k free, 27872k buffers - Swap: 786428k total, 0k used, 786428k free, 221740k cached + %Cpu(s): 0.1 us, 0.1 sy, 0.0 ni, 99.8 id, 0.0 wa, 0.0 hi, 0.0 si, 0.0 st + MiB Mem : 3934.3 total, 770.1 free, 674.2 used, 2490.1 buff/cache + MiB Swap: 1024.0 total, 839.3 free, 184.7 used. 2814.0 avail Mem - PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND - 1 root 20 0 17200 1116 912 R 0 0.3 0:00.03 top + PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND + 1 root 20 0 7180 2896 2568 R 0.0 0.1 0:00.02 top + ``` - top - 02:05:55 up 3:05, 0 users, load average: 0.01, 0.02, 0.05 - Tasks: 1 total, 1 running, 0 sleeping, 0 stopped, 0 zombie - Cpu(s): 0.0%us, 0.2%sy, 0.0%ni, 99.8%id, 0.0%wa, 0.0%hi, 0.0%si, 0.0%st - Mem: 373572k total, 355244k used, 18328k free, 27872k buffers - Swap: 786428k total, 0k used, 786428k free, 221776k cached + As the container was started without the `-i`, and `-t` options, signals are + forwarded to the attached process, which means that the default `CTRL-p CTRL-q` + detach key sequence produces no effect, but pressing `CTRL-c` terminates the + container: - PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND - 1 root 20 0 17208 1144 932 R 0 0.3 0:00.03 top + ```console + <...> + PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND + 1 root 20 0 7180 2896 2568 R 0.0 0.1 0:00.02 top^P^Q + ^C + $ docker ps -a --filter name=topdemo - top - 02:05:58 up 3:06, 0 users, load average: 0.01, 0.02, 0.05 - Tasks: 1 total, 1 running, 0 sleeping, 0 stopped, 0 zombie - Cpu(s): 0.2%us, 0.3%sy, 0.0%ni, 99.5%id, 0.0%wa, 0.0%hi, 0.0%si, 0.0%st - Mem: 373572k total, 355780k used, 17792k free, 27880k buffers - Swap: 786428k total, 0k used, 786428k free, 221776k cached + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + 4cf0d0ebb079 ubuntu:22.04 "/usr/bin/top -b" About a minute ago Exited (0) About a minute ago topdemo + ``` - PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND - 1 root 20 0 17208 1144 932 R 0 0.3 0:00.03 top - ^C$ + Repeating the example above, but this time with the `-i` and `-t` options set; - $ echo $? - 0 - $ docker ps -a | grep topdemo + ```console + $ docker run -dit --name topdemo2 ubuntu:22.04 /usr/bin/top -b + ``` - 7998ac8581f9 ubuntu:14.04 "/usr/bin/top -b" 38 seconds ago Exited (0) 21 seconds ago topdemo + Now, when attaching to the container, and pressing the `CTRL-p CTRL-q` ("read + escape sequence"), the Docker CLI is handling the detach sequence, and the + `attach` command is detached from the container. Checking the container's status + with `docker ps` shows that the container is still running in the background: + + ```console + $ docker attach topdemo2 + + top - 12:44:32 up 3 days, 22:11, 0 users, load average: 0.00, 0.00, 0.00 + Tasks: 1 total, 1 running, 0 sleeping, 0 stopped, 0 zombie + %Cpu(s): 50.0 us, 0.0 sy, 0.0 ni, 50.0 id, 0.0 wa, 0.0 hi, 0.0 si, 0.0 st + MiB Mem : 3934.3 total, 770.6 free, 672.4 used, 2491.4 buff/cache + MiB Swap: 1024.0 total, 839.3 free, 184.7 used. 2815.8 avail Mem + + PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND + 1 root 20 0 7180 2776 2452 R 0.0 0.1 0:00.02 topread escape sequence + + $ docker ps -a --filter name=topdemo2 + + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + b1661dce0fc2 ubuntu:22.04 "/usr/bin/top -b" 2 minutes ago Up 2 minutes topdemo2 ``` ### Get the exit code of the container's command @@ -140,20 +163,19 @@ examples: |- process is returned by the `docker attach` command to its caller too: ```console - $ docker run --name test -d -it debian + $ docker run --name test -dit alpine 275c44472aebd77c926d4527885bb09f2f6db21d878c75f0a1c212c03d3bcfab $ docker attach test - root@f38c87f2a42d:/# exit 13 - - exit + /# exit 13 $ echo $? 13 - $ docker ps -a | grep test + $ docker ps -a --filter name=test - 275c44472aeb debian:7 "/bin/bash" 26 seconds ago Exited (13) 17 seconds ago test + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + a2fe3fd886db alpine "/bin/sh" About a minute ago Exited (13) 40 seconds ago test ``` deprecated: false experimental: false diff --git a/_data/engine-cli/docker_build.yaml b/_data/engine-cli/docker_build.yaml index bbdfca7014..43b6891f15 100644 --- a/_data/engine-cli/docker_build.yaml +++ b/_data/engine-cli/docker_build.yaml @@ -570,7 +570,7 @@ examples: |- expect to ignore different sets of files. - ### Tag an image (-t) + ### Tag an image (-t, --tag) ```console $ docker build -t vieux/apache:2.0 . @@ -590,7 +590,7 @@ examples: |- $ docker build -t whenry/fedora-jboss:latest -t whenry/fedora-jboss:v2.1 . ``` - ### Specify a Dockerfile (-f) + ### Specify a Dockerfile (-f, --file) ```console $ docker build -f Dockerfile.debug . @@ -637,17 +637,17 @@ examples: |- > repeatable builds on remote Docker hosts. This is also the reason why > `ADD ../file` does not work. - ### Use a custom parent cgroup (--cgroup-parent) + ### Use a custom parent cgroup (--cgroup-parent) When `docker build` is run with the `--cgroup-parent` option the containers used in the build will be run with the [corresponding `docker run` flag](../run.md#specify-custom-cgroups). - ### Set ulimits in container (--ulimit) + ### Set ulimits in container (--ulimit) Using the `--ulimit` option with `docker build` will cause each build step's - container to be started using those [`--ulimit` flag values](run.md#set-ulimits-in-container---ulimit). + container to be started using those [`--ulimit` flag values](run.md#ulimit). - ### Set build-time variables (--build-arg) + ### Set build-time variables (--build-arg) You can use `ENV` instructions in a Dockerfile to define variable values. These values persist in the built image. However, often @@ -682,16 +682,16 @@ examples: |- $ docker build --build-arg HTTP_PROXY . ``` - This is similar to how `docker run -e` works. Refer to the [`docker run` documentation](https://docs.docker.com/engine/reference/commandline/run/#set-environment-variables--e---env---env-file) + This is similar to how `docker run -e` works. Refer to the [`docker run` documentation](run.md#env) for more information. - ### Optional security options (--security-opt) + ### Optional security options (--security-opt) This flag is only supported on a daemon running on Windows, and only supports the `credentialspec` option. The `credentialspec` must be in the format `file://spec.txt` or `registry://keyname`. - ### Specify isolation technology for container (--isolation) + ### Specify isolation technology for container (--isolation) This option is useful in situations where you are running Docker containers on Windows. The `--isolation=` option sets a container's isolation @@ -707,7 +707,7 @@ examples: |- Specifying the `--isolation` flag without a value is the same as setting `--isolation="default"`. - ### Add entries to container hosts file (--add-host) + ### Add entries to container hosts file (--add-host) You can add other hosts into a container's `/etc/hosts` file by using one or more `--add-host` flags. This example adds a static address for a host named @@ -715,7 +715,7 @@ examples: |- $ docker build --add-host=docker:10.180.0.1 . - ### Specifying target build stage (--target) + ### Specifying target build stage (--target) When building a Dockerfile with multiple build stages, `--target` can be used to specify an intermediate build stage by name as a final stage for the resulting @@ -733,7 +733,14 @@ examples: |- $ docker build -t mybuildimage --target build-env . ``` - ### Custom build outputs + ### Custom build outputs (--output) + + > **Note** + > + > This feature requires the BuildKit backend. You can either + > [enable BuildKit](https://docs.docker.com/build/buildkit/#getting-started) or + > use the [buildx](https://github.com/docker/buildx) plugin which provides more + > output type options. By default, a local container image is created from the build result. The `--output` (or `-o`) flag allows you to override this behavior, and a specify a @@ -820,14 +827,14 @@ examples: |- vndr ``` + ### Specifying external cache sources (--cache-from) + > **Note** > > This feature requires the BuildKit backend. You can either > [enable BuildKit](https://docs.docker.com/build/buildkit/#getting-started) or - > use the [buildx](https://github.com/docker/buildx) plugin which provides more - > output type options. - - ### Specifying external cache sources + > use the [buildx](https://github.com/docker/buildx) plugin. The previous + > builder has limited support for reusing cache from pre-pulled images. In addition to local build cache, the builder can reuse the cache generated from previous builds with the `--cache-from` flag pointing to an image in the registry. @@ -863,14 +870,7 @@ examples: |- $ docker build --cache-from myname/myapp . ``` - > **Note** - > - > This feature requires the BuildKit backend. You can either - > [enable BuildKit](https://docs.docker.com/build/buildkit/#getting-started) or - > use the [buildx](https://github.com/docker/buildx) plugin. The previous - > builder has limited support for reusing cache from pre-pulled images. - - ### Squash an image's layers (--squash) (experimental) + ### Squash an image's layers (--squash) (experimental) #### Overview diff --git a/_data/engine-cli/docker_commit.yaml b/_data/engine-cli/docker_commit.yaml index eed4a13d28..a6e6efa2c2 100644 --- a/_data/engine-cli/docker_commit.yaml +++ b/_data/engine-cli/docker_commit.yaml @@ -66,8 +66,8 @@ examples: |- $ docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - c3f279d17e0a ubuntu:12.04 /bin/bash 7 days ago Up 25 hours desperate_dubinsky - 197387f1b436 ubuntu:12.04 /bin/bash 7 days ago Up 25 hours focused_hamilton + c3f279d17e0a ubuntu:22.04 /bin/bash 7 days ago Up 25 hours desperate_dubinsky + 197387f1b436 ubuntu:22.04 /bin/bash 7 days ago Up 25 hours focused_hamilton $ docker commit c3f279d17e0a svendowideit/testimage:version3 @@ -79,14 +79,14 @@ examples: |- svendowideit/testimage version3 f5283438590d 16 seconds ago 335.7 MB ``` - ### Commit a container with new configurations + ### Commit a container with new configurations (--change) ```console $ docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - c3f279d17e0a ubuntu:12.04 /bin/bash 7 days ago Up 25 hours desperate_dubinsky - 197387f1b436 ubuntu:12.04 /bin/bash 7 days ago Up 25 hours focused_hamilton + c3f279d17e0a ubuntu:22.04 /bin/bash 7 days ago Up 25 hours desperate_dubinsky + 197387f1b436 ubuntu:22.04 /bin/bash 7 days ago Up 25 hours focused_hamilton $ docker inspect -f "{{ .Config.Env }}" c3f279d17e0a @@ -107,8 +107,8 @@ examples: |- $ docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - c3f279d17e0a ubuntu:12.04 /bin/bash 7 days ago Up 25 hours desperate_dubinsky - 197387f1b436 ubuntu:12.04 /bin/bash 7 days ago Up 25 hours focused_hamilton + c3f279d17e0a ubuntu:22.04 /bin/bash 7 days ago Up 25 hours desperate_dubinsky + 197387f1b436 ubuntu:22.04 /bin/bash 7 days ago Up 25 hours focused_hamilton $ docker commit --change='CMD ["apachectl", "-DFOREGROUND"]' -c "EXPOSE 80" c3f279d17e0a svendowideit/testimage:version4 @@ -122,8 +122,8 @@ examples: |- CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 89373736e2e7 testimage:version4 "apachectl -DFOREGROU" 3 seconds ago Up 2 seconds 80/tcp distracted_fermat - c3f279d17e0a ubuntu:12.04 /bin/bash 7 days ago Up 25 hours desperate_dubinsky - 197387f1b436 ubuntu:12.04 /bin/bash 7 days ago Up 25 hours focused_hamilton + c3f279d17e0a ubuntu:22.04 /bin/bash 7 days ago Up 25 hours desperate_dubinsky + 197387f1b436 ubuntu:22.04 /bin/bash 7 days ago Up 25 hours focused_hamilton ``` deprecated: false experimental: false diff --git a/_data/engine-cli/docker_config_create.yaml b/_data/engine-cli/docker_config_create.yaml index 376be84c82..e9991284f3 100644 --- a/_data/engine-cli/docker_config_create.yaml +++ b/_data/engine-cli/docker_config_create.yaml @@ -60,7 +60,7 @@ examples: |- dg426haahpi5ezmkkj5kyl3sn my_config 7 seconds ago 7 seconds ago ``` - ### Create a config with labels + ### Create a config with labels (-l, --label) ```console $ docker config create \ diff --git a/_data/engine-cli/docker_config_inspect.yaml b/_data/engine-cli/docker_config_inspect.yaml index 41b001263c..3335b0817d 100644 --- a/_data/engine-cli/docker_config_inspect.yaml +++ b/_data/engine-cli/docker_config_inspect.yaml @@ -80,7 +80,7 @@ examples: |- ] ``` - ### Formatting + ### Format the output (--format) You can use the --format option to obtain specific information about a config. The following example command outputs the creation time of the diff --git a/_data/engine-cli/docker_config_ls.yaml b/_data/engine-cli/docker_config_ls.yaml index 351c86a264..d6934213c0 100644 --- a/_data/engine-cli/docker_config_ls.yaml +++ b/_data/engine-cli/docker_config_ls.yaml @@ -53,7 +53,7 @@ examples: |- mem02h8n73mybpgqjf0kfi1n0 test_config 3 seconds ago 3 seconds ago ``` - ### Filtering + ### Filtering (-f, --filter) The filtering flag (`-f` or `--filter`) format is a `key=value` pair. If there is more than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`) @@ -113,7 +113,7 @@ examples: |- mem02h8n73mybpgqjf0kfi1n0 test_config About an hour ago About an hour ago ``` - ### Format the output + ### Format the output (--format) The formatting option (`--format`) pretty prints configs output using a Go template. diff --git a/_data/engine-cli/docker_container_prune.yaml b/_data/engine-cli/docker_container_prune.yaml index d45fff23f8..db52af03d1 100644 --- a/_data/engine-cli/docker_container_prune.yaml +++ b/_data/engine-cli/docker_container_prune.yaml @@ -37,7 +37,7 @@ examples: |- Total reclaimed space: 212 B ``` - ### Filtering + ### Filtering (--filter) The filtering flag (`--filter`) format is of "key=value". If there is more than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`) diff --git a/_data/engine-cli/docker_context_create.yaml b/_data/engine-cli/docker_context_create.yaml index cc162463aa..562ee3c474 100644 --- a/_data/engine-cli/docker_context_create.yaml +++ b/_data/engine-cli/docker_context_create.yaml @@ -65,7 +65,7 @@ examples: |- my-context ``` - ### Create a context based on an existing context + ### Create a context based on an existing context (--from) Use the `--from=` option to create a new context from an existing context. The example below creates a new context named `my-context` diff --git a/_data/engine-cli/docker_cp.yaml b/_data/engine-cli/docker_cp.yaml index e39d37d19a..12eb2d1201 100644 --- a/_data/engine-cli/docker_cp.yaml +++ b/_data/engine-cli/docker_cp.yaml @@ -111,7 +111,7 @@ examples: |- ### Corner cases It is not possible to copy certain system files such as resources under - `/proc`, `/sys`, `/dev`, [tmpfs](run.md#mount-tmpfs---tmpfs), and mounts created by + `/proc`, `/sys`, `/dev`, [tmpfs](run.md#tmpfs), and mounts created by the user in the container. However, you can still copy such files by manually running `tar` in `docker exec`. Both of the following examples do the same thing in different ways (consider `SRC_PATH` and `DEST_PATH` are directories): diff --git a/_data/engine-cli/docker_events.yaml b/_data/engine-cli/docker_events.yaml index f5eda10eaf..45b9557f82 100644 --- a/_data/engine-cli/docker_events.yaml +++ b/_data/engine-cli/docker_events.yaml @@ -121,7 +121,7 @@ long: |- ### Limiting, filtering, and formatting the output - #### Limit events by time + #### Limit events by time (--since, --until) The `--since` and `--until` parameters can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed @@ -139,7 +139,7 @@ long: |- Only the last 1000 log events are returned. You can use filters to further limit the number of events returned. - #### Filtering + #### Filtering (--filter) The filtering flag (`-f` or `--filter`) format is of "key=value". If you would like to use multiple filters, pass multiple flags (e.g., @@ -170,7 +170,7 @@ long: |- * type (`type=`) * volume (`volume=`) - #### Format + #### Format the output (--format) If a format (`--format`) is specified, the given template will be executed instead of the default @@ -355,8 +355,8 @@ examples: |- $ docker events --filter 'container=container_1' --filter 'container=container_2' - 2014-09-03T15:49:29.999999999Z07:00 container die 4386fb97867d (image=ubuntu-1:14.04) - 2014-05-10T17:42:14.999999999Z07:00 container stop 4386fb97867d (image=ubuntu-1:14.04) + 2014-09-03T15:49:29.999999999Z07:00 container die 4386fb97867d (image=ubuntu:22.04) + 2014-05-10T17:42:14.999999999Z07:00 container stop 4386fb97867d (image=ubuntu:22.04) 2014-05-10T17:42:14.999999999Z07:00 container die 7805c1d35632 (imager=redis:2.8) 2014-09-03T15:49:29.999999999Z07:00 container stop 7805c1d35632 (image=redis:2.8) diff --git a/_data/engine-cli/docker_exec.yaml b/_data/engine-cli/docker_exec.yaml index 9d1a7b5fb0..7e20a0cf68 100644 --- a/_data/engine-cli/docker_exec.yaml +++ b/_data/engine-cli/docker_exec.yaml @@ -7,13 +7,13 @@ long: |- process (`PID 1`) is running, and it is not restarted if the container is restarted. - COMMAND will run in the default directory of the container. If the - underlying image has a custom directory specified with the WORKDIR directive - in its Dockerfile, this will be used instead. + COMMAND runs in the default directory of the container. If the underlying image + has a custom directory specified with the WORKDIR directive in its Dockerfile, + this directory is used instead. - COMMAND should be an executable, a chained or a quoted command - will not work. Example: `docker exec -ti my_container "echo a && echo b"` will - not work, but `docker exec -ti my_container sh -c "echo a && echo b"` will. + COMMAND must be an executable. A chained or a quoted command does not work. + For example, `docker exec -it my_container sh -c "echo a && echo b"` works, + work, but `docker exec -it my_container "echo a && echo b"` does not. usage: docker exec [OPTIONS] CONTAINER COMMAND [ARG...] pname: docker plink: docker.yaml @@ -103,80 +103,40 @@ options: experimentalcli: false kubernetes: false swarm: false -examples: |- - ### Run `docker exec` on a running container - - First, start a container. - - ```console - $ docker run --name ubuntu_bash --rm -i -t ubuntu bash - ``` - - This will create a container named `ubuntu_bash` and start a Bash session. - - Next, execute a command on the container. - - ```console - $ docker exec -d ubuntu_bash touch /tmp/execWorks - ``` - - This will create a new file `/tmp/execWorks` inside the running container - `ubuntu_bash`, in the background. - - Next, execute an interactive `bash` shell on the container. - - ```console - $ docker exec -it ubuntu_bash bash - ``` - - This will create a new Bash session in the container `ubuntu_bash`. - - Next, set an environment variable in the current bash session. - - ```console - $ docker exec -it -e VAR=1 ubuntu_bash bash - ``` - - This will create a new Bash session in the container `ubuntu_bash` with environment - variable `$VAR` set to "1". Note that this environment variable will only be valid - on the current Bash session. - - By default `docker exec` command runs in the same working directory set when container was created. - - ```console - $ docker exec -it ubuntu_bash pwd - / - ``` - - You can select working directory for the command to execute into - - ```console - $ docker exec -it -w /root ubuntu_bash pwd - /root - ``` - - - ### Try to run `docker exec` on a paused container - - If the container is paused, then the `docker exec` command will fail with an error: - - ```console - $ docker pause test - - test - - $ docker ps - - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 1ae3b36715d2 ubuntu:latest "bash" 17 seconds ago Up 16 seconds (Paused) test - - $ docker exec test ls - - FATA[0000] Error response from daemon: Container test is paused, unpause the container before exec - - $ echo $? - 1 - ``` +examples: "### Run `docker exec` on a running container\n\nFirst, start a container.\n\n```console\n$ + docker run --name mycontainer -d -i -t alpine /bin/sh\n```\n\nThis creates and starts + a container named `mycontainer` from an `alpine` image\nwith an `sh` shell as its + main process. The `-d` option (shorthand for `--detach`)\nsets the container to + run in the background, in detached mode, with a pseudo-TTY\nattached (`-t`). The + `-i` option is set to keep `STDIN` attached (`-i`), which\nprevents the `sh` process + from exiting immediately.\n\nNext, execute a command on the container.\n\n```console\n$ + docker exec -d mycontainer touch /tmp/execWorks\n```\n\nThis creates a new file + `/tmp/execWorks` inside the running container\n`mycontainer`, in the background.\n\nNext, + execute an interactive `sh` shell on the container.\n\n```console\n$ docker exec + -it mycontainer sh\n```\n\nThis starts a new shell session in the container `mycontainer`.\n\n### + Set environment variables for the exec process (--env, -e)\n\nNext, + set environment variables in the current bash session.\n\nBy default, the `docker + exec` command, inherits the environment variables that\nare set at the time the + container is created. Use the `--env` (or the `-e` shorthand)\nto override global + environment variables, or to set additional environment variables\nfor the process + started by `docker exec`.\n\nThe example below creates a new shell session in the + container `mycontainer` with\nenvironment variables `$VAR_A` and `$VAR_B` set to + \"1\" and \"2\" respectively.\nThese environment variables are only valid for the + `sh` process started by that\n`docker exec` command, and are not available to other + processes running inside\nthe container.\n\n```console\n$ docker exec -e VAR_A=1 + -e VAR_B=2 mycontainer env\nPATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin\nHOSTNAME=f64a4851eb71\nVAR_A=1\nVAR_B=2\nHOME=/root\n```\n\n### + Set the working directory for the exec process (--workdir, + -w)\n\nBy default `docker exec` command runs in the same working directory set when + \nthe container was created.\n\n```console\n$ docker exec -it mycontainer pwd\n/\n```\n\nYou + can specify an alternative working directory for the command to execute \nusing + the `--workdir` option (or the `-w` shorthand):\n\n```console\n$ docker exec -it + -w /root mycontainer pwd\n/root\n```\n\n\n### Try to run `docker exec` on a paused + container\n\nIf the container is paused, then the `docker exec` command fails with + an error:\n\n```console\n$ docker pause mycontainer\nmycontainer\n\n$ docker ps\n\nCONTAINER + ID IMAGE COMMAND CREATED STATUS PORTS NAMES\n482efdf39fac + \ alpine \"/bin/sh\" 17 seconds ago Up 16 seconds (Paused) mycontainer\n\n$ + docker exec mycontainer sh\n\nError response from daemon: Container mycontainer + is paused, unpause the container before exec\n\n$ echo $?\n1\n```" deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_export.yaml b/_data/engine-cli/docker_export.yaml index f2cd6d68e5..a5fd064131 100644 --- a/_data/engine-cli/docker_export.yaml +++ b/_data/engine-cli/docker_export.yaml @@ -6,7 +6,7 @@ long: |- the container, `docker export` will export the contents of the *underlying* directory, not the contents of the volume. - Refer to [Back up, restore, or migrate data volumes](https://docs.docker.com/storage/volumes/#back-up-restore-or-migrate-data-volumes) + Refer to [Backup, restore, or migrate data volumes](https://docs.docker.com/storage/volumes/#back-up-restore-or-migrate-data-volumes) in the user guide for examples on exporting data in a volume. usage: docker export [OPTIONS] CONTAINER pname: docker diff --git a/_data/engine-cli/docker_history.yaml b/_data/engine-cli/docker_history.yaml index 64db5a5894..9fa0f65fe1 100644 --- a/_data/engine-cli/docker_history.yaml +++ b/_data/engine-cli/docker_history.yaml @@ -68,7 +68,7 @@ examples: |- 511136ea3c5a 19 months ago 0 B Imported from - ``` - ### Format the output + ### Format the output (--format) The formatting option (`--format`) will pretty-prints history output using a Go template. diff --git a/_data/engine-cli/docker_image_prune.yaml b/_data/engine-cli/docker_image_prune.yaml index 7ffbdf3a09..cea6ab0a76 100644 --- a/_data/engine-cli/docker_image_prune.yaml +++ b/_data/engine-cli/docker_image_prune.yaml @@ -70,7 +70,7 @@ examples: |- Total reclaimed space: 16.43 MB ``` - ### Filtering + ### Filtering (--filter) The filtering flag (`--filter`) format is of "key=value". If there is more than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`) diff --git a/_data/engine-cli/docker_images.yaml b/_data/engine-cli/docker_images.yaml index 2532e2fcce..4f1795e259 100644 --- a/_data/engine-cli/docker_images.yaml +++ b/_data/engine-cli/docker_images.yaml @@ -133,7 +133,7 @@ examples: |- REPOSITORY TAG IMAGE ID CREATED SIZE ``` - ### List the full length image IDs + ### List the full length image IDs (--no-trunc) ```console $ docker images --no-trunc @@ -150,7 +150,7 @@ examples: |- sha256:5ed6274db6ceb2397844896966ea239290555e74ef307030ebb01ff91b1914df 24 hours ago 1.089 GB ``` - ### List image digests + ### List image digests (--digests) Images that use the v2 or later format have a content-addressable identifier called a `digest`. As long as the input used to generate the image is @@ -168,7 +168,7 @@ examples: |- also reference by digest in `create`, `run`, and `rmi` commands, as well as the `FROM` image reference in a Dockerfile. - ### Filtering + ### Filtering (--filter) The filtering flag (`-f` or `--filter`) format is of "key=value". If there is more than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`) @@ -316,7 +316,7 @@ examples: |- busybox glibc 21c16b6787c6 5 weeks ago 4.19 MB ``` - ### Format the output + ### Format the output (--format) The formatting option (`--format`) will pretty print container output using a Go template. diff --git a/_data/engine-cli/docker_info.yaml b/_data/engine-cli/docker_info.yaml index 88643e3286..7ba2f05360 100644 --- a/_data/engine-cli/docker_info.yaml +++ b/_data/engine-cli/docker_info.yaml @@ -34,9 +34,9 @@ options: examples: |- ### Show output - The example below shows the output for a daemon running on Red Hat Enterprise Linux, - using the `devicemapper` storage driver. As can be seen in the output, additional - information about the `devicemapper` storage driver is shown: + The example below shows the output for a daemon running on Ubuntu Linux, + using the `overlay2` storage driver. As can be seen in the output, additional + information about the `overlay2` storage driver is shown: ```console $ docker info @@ -44,6 +44,16 @@ examples: |- Client: Context: default Debug Mode: false + Plugins: + buildx: Docker Buildx (Docker Inc.) + Version: v0.8.2 + Path: /usr/libexec/docker/cli-plugins/docker-buildx + compose: Docker Compose (Docker Inc.) + Version: v2.6.0 + Path: /usr/libexec/docker/cli-plugins/docker-compose + scan: Docker Scan (Docker Inc.) + Version: v0.17.0 + Path: /usr/libexec/docker/cli-plugins/docker-scan Server: Containers: 14 @@ -51,142 +61,52 @@ examples: |- Paused: 1 Stopped: 10 Images: 52 - Server Version: 1.10.3 - Storage Driver: devicemapper - Pool Name: docker-202:2-25583803-pool - Pool Blocksize: 65.54 kB - Base Device Size: 10.74 GB - Backing Filesystem: xfs - Data file: /dev/loop0 - Metadata file: /dev/loop1 - Data Space Used: 1.68 GB - Data Space Total: 107.4 GB - Data Space Available: 7.548 GB - Metadata Space Used: 2.322 MB - Metadata Space Total: 2.147 GB - Metadata Space Available: 2.145 GB - Udev Sync Supported: true - Deferred Removal Enabled: false - Deferred Deletion Enabled: false - Deferred Deleted Device Count: 0 - Data loop file: /var/lib/docker/devicemapper/devicemapper/data - Metadata loop file: /var/lib/docker/devicemapper/devicemapper/metadata - Library Version: 1.02.107-RHEL7 (2015-12-01) - Execution Driver: native-0.2 + Server Version: 22.06.0 + Storage Driver: overlay2 + Backing Filesystem: extfs + Supports d_type: true + Using metacopy: false + Native Overlay Diff: true + userxattr: false Logging Driver: json-file + Cgroup Driver: systemd + Cgroup Version: 2 Plugins: Volume: local - Network: null host bridge - Kernel Version: 3.10.0-327.el7.x86_64 - Operating System: Red Hat Enterprise Linux Server 7.2 (Maipo) + Network: bridge host ipvlan macvlan null overlay + Log: awslogs fluentd gcplogs gelf journald json-file local logentries splunk syslog + Swarm: inactive + Runtimes: io.containerd.runc.v2 io.containerd.runtime.v1.linux runc + Default Runtime: runc + Init Binary: docker-init + containerd version: 212e8b6fa2f44b9c21b2798135fc6fb7c53efc16 + runc version: v1.1.1-0-g52de29d + init version: de40ad0 + Security Options: + apparmor + seccomp + Profile: builtin + cgroupns + Kernel Version: 5.15.0-25-generic + Operating System: Ubuntu 22.04 LTS OSType: linux Architecture: x86_64 CPUs: 1 Total Memory: 991.7 MiB Name: ip-172-30-0-91.ec2.internal - ID: I54V:OLXT:HVMM:TPKO:JPHQ:CQCD:JNLC:O3BZ:4ZVJ:43XJ:PFHZ:6N2S + ID: 4cee4408-10d2-4e17-891c-a41736ac4536 Docker Root Dir: /var/lib/docker Debug Mode: false Username: gordontheturtle Registry: https://index.docker.io/v1/ + Experimental: false Insecure registries: myinsecurehost:5000 127.0.0.0/8 - ``` - - ### Show debugging output - - Here is a sample output for a daemon running on Ubuntu, using the overlay2 - storage driver and a node that is part of a 2-node swarm: - - ```console - $ docker --debug info - - Client: - Context: default - Debug Mode: true - - Server: - Containers: 14 - Running: 3 - Paused: 1 - Stopped: 10 - Images: 52 - Server Version: 1.13.0 - Storage Driver: overlay2 - Backing Filesystem: extfs - Supports d_type: true - Native Overlay Diff: false - Logging Driver: json-file - Cgroup Driver: cgroupfs - Plugins: - Volume: local - Network: bridge host macvlan null overlay - Swarm: active - NodeID: rdjq45w1op418waxlairloqbm - Is Manager: true - ClusterID: te8kdyw33n36fqiz74bfjeixd - Managers: 1 - Nodes: 2 - Orchestration: - Task History Retention Limit: 5 - Raft: - Snapshot Interval: 10000 - Number of Old Snapshots to Retain: 0 - Heartbeat Tick: 1 - Election Tick: 3 - Dispatcher: - Heartbeat Period: 5 seconds - CA Configuration: - Expiry Duration: 3 months - Root Rotation In Progress: false - Node Address: 172.16.66.128 172.16.66.129 - Manager Addresses: - 172.16.66.128:2477 - Runtimes: runc - Default Runtime: runc - Init Binary: docker-init - containerd version: 8517738ba4b82aff5662c97ca4627e7e4d03b531 - runc version: ac031b5bf1cc92239461125f4c1ffb760522bbf2 - init version: N/A (expected: v0.13.0) - Security Options: - apparmor - seccomp - Profile: default - Kernel Version: 4.4.0-31-generic - Operating System: Ubuntu 16.04.1 LTS - OSType: linux - Architecture: x86_64 - CPUs: 2 - Total Memory: 1.937 GiB - Name: ubuntu - ID: H52R:7ZR6:EIIA:76JG:ORIY:BVKF:GSFU:HNPG:B5MK:APSC:SZ3Q:N326 - Docker Root Dir: /var/lib/docker - Debug Mode: true - File Descriptors: 30 - Goroutines: 123 - System Time: 2016-11-12T17:24:37.955404361-08:00 - EventsListeners: 0 - Http Proxy: http://test:test@proxy.example.com:8080 - Https Proxy: https://test:test@proxy.example.com:8080 - No Proxy: localhost,127.0.0.1,docker-registry.somecorporation.com - Registry: https://index.docker.io/v1/ - WARNING: No swap limit support - Labels: - storage=ssd - staging=true - Experimental: false - Insecure Registries: - 127.0.0.0/8 - Registry Mirrors: - http://192.168.1.2/ - http://registry-mirror.example.com:5000/ Live Restore Enabled: false ``` - The global `-D` option causes all `docker` commands to output debug information. - - ### Format the output + ### Format the output (--format) You can also specify the output format: @@ -198,13 +118,18 @@ examples: |- ### Run `docker info` on Windows - Here is a sample output for a daemon running on Windows Server 2016: + Here is a sample output for a daemon running on Windows Server: ```console - E:\docker>docker info + C:\> docker info + Client: Context: default Debug Mode: false + Plugins: + buildx: Docker Buildx (Docker Inc., v0.8.2-docker) + compose: Docker Compose (Docker Inc., v2.6.0) + scan: Docker Scan (Docker Inc., v0.17.0) Server: Containers: 1 @@ -212,27 +137,29 @@ examples: |- Paused: 0 Stopped: 1 Images: 17 - Server Version: 1.13.0 + Server Version: 20.10.16 Storage Driver: windowsfilter - Windows: Logging Driver: json-file Plugins: Volume: local - Network: nat null overlay + Network: ics internal l2bridge l2tunnel nat null overlay private transparent + Log: awslogs etwlogs fluentd gcplogs gelf json-file local logentries splunk syslog Swarm: inactive Default Isolation: process - Kernel Version: 10.0 14393 (14393.206.amd64fre.rs1_release.160912-1937) - Operating System: Windows Server 2016 Datacenter + Kernel Version: 10.0 20348 (20348.1.amd64fre.fe_release.210507-1500) + Operating System: Microsoft Windows Server Version 21H2 (OS Build 20348.707) OSType: windows Architecture: x86_64 CPUs: 8 Total Memory: 3.999 GiB Name: WIN-V0V70C0LU5P - ID: NYMS:B5VK:UMSL:FVDZ:EWB5:FKVK:LPFL:FJMQ:H6FT:BZJ6:L2TD:XH62 - Docker Root Dir: C:\control + ID: 2880d38d-464e-4d01-91bd-c76f33ba3981 + Docker Root Dir: C:\ProgramData\docker Debug Mode: false Registry: https://index.docker.io/v1/ + Experimental: true Insecure Registries: + myregistry:5000 127.0.0.0/8 Registry Mirrors: http://192.168.1.2/ diff --git a/_data/engine-cli/docker_inspect.yaml b/_data/engine-cli/docker_inspect.yaml index bd610aa1f1..1415805542 100644 --- a/_data/engine-cli/docker_inspect.yaml +++ b/_data/engine-cli/docker_inspect.yaml @@ -4,6 +4,59 @@ long: |- Docker inspect provides detailed information on constructs controlled by Docker. By default, `docker inspect` will render results in a JSON array. + + ### Format the output (--format) + + If a format is specified, the given template will be executed for each result. + + Go's [text/template](https://golang.org/pkg/text/template/) package describes + all the details of the format. + + ### Specify target type (--type) + + `--type container|image|node|network|secret|service|volume|task|plugin` + + The `docker inspect` command matches any type of object by either ID or name. In + some cases multiple type of objects (for example, a container and a volume) + exist with the same name, making the result ambiguous. + + To restrict `docker inspect` to a specific type of object, use the `--type` + option. + + The following example inspects a _volume_ named "myvolume" + + ```console + $ docker inspect --type=volume myvolume + ``` + + ### Inspect the size of a container (-s, --size) + + The `--size`, or short-form `-s`, option adds two additional fields to the + `docker inspect` output. This option only works for containers. The container + doesn't have to be running, it also works for stopped containers. + + ```console + $ docker inspect --size mycontainer + ``` + + The output includes the full output of a regular `docker inspect` command, with + the following additional fields: + + - `SizeRootFs`: the total size of all the files in the container, in bytes. + - `SizeRw`: the size of the files that have been created or changed in the + container, compared to it's image, in bytes. + + ```console + $ docker run --name database -d redis + 3b2cbf074c99db4a0cad35966a9e24d7bc277f5565c17233386589029b7db273 + $ docker inspect --size database -f '{{ .SizeRootFs }}' + 123125760 + $ docker inspect --size database -f '{{ .SizeRw }}' + 8192 + $ docker exec database fallocate -l 1000 /newfile + $ docker inspect --size database -f '{{ .SizeRw }}' + 12288 + ``` usage: docker inspect [OPTIONS] NAME|ID [NAME|ID...] pname: docker plink: docker.yaml @@ -65,8 +118,7 @@ examples: |- ### List all port bindings - You can loop over arrays and maps in the results to produce simple text - output: + You can loop over arrays and maps in the results to produce simple text output: ```console $ docker inspect --format='{{range $p, $conf := .NetworkSettings.Ports}} {{$p}} -> {{(index $conf 0).HostPort}} {{end}}' $INSTANCE_ID @@ -74,13 +126,12 @@ examples: |- ### Find a specific port mapping - The `.Field` syntax doesn't work when the field name begins with a - number, but the template language's `index` function does. The - `.NetworkSettings.Ports` section contains a map of the internal port - mappings to a list of external address/port objects. To grab just the - numeric public port, you use `index` to find the specific port map, and - then `index` 0 contains the first object inside of that. Then we ask for - the `HostPort` field to get the public address. + The `.Field` syntax doesn't work when the field name begins with a number, but + the template language's `index` function does. The `.NetworkSettings.Ports` + section contains a map of the internal port mappings to a list of external + address/port objects. To grab just the numeric public port, you use `index` to + find the specific port map, and then `index` 0 contains the first object inside + of that. Then we ask for the `HostPort` field to get the public address. ```console $ docker inspect --format='{{(index (index .NetworkSettings.Ports "8787/tcp") 0).HostPort}}' $INSTANCE_ID @@ -88,10 +139,9 @@ examples: |- ### Get a subsection in JSON format - If you request a field which is itself a structure containing other - fields, by default you get a Go-style dump of the inner values. - Docker adds a template function, `json`, which can be applied to get - results in JSON format. + If you request a field which is itself a structure containing other fields, by + default you get a Go-style dump of the inner values. Docker adds a template + function, `json`, which can be applied to get results in JSON format. ```console $ docker inspect --format='{{json .Config}}' $INSTANCE_ID diff --git a/_data/engine-cli/docker_kill.yaml b/_data/engine-cli/docker_kill.yaml index d13cb948c4..6cda0bd0b3 100644 --- a/_data/engine-cli/docker_kill.yaml +++ b/_data/engine-cli/docker_kill.yaml @@ -45,7 +45,7 @@ examples: |- $ docker kill my_container ``` - ### Send a custom signal to a container + ### Send a custom signal to a container (--signal) The following example sends a `SIGHUP` signal to the container named `my_container`: diff --git a/_data/engine-cli/docker_load.yaml b/_data/engine-cli/docker_load.yaml index 40032d7cc4..e29ed84a0b 100644 --- a/_data/engine-cli/docker_load.yaml +++ b/_data/engine-cli/docker_load.yaml @@ -31,18 +31,25 @@ examples: |- $ docker image ls REPOSITORY TAG IMAGE ID CREATED SIZE + ``` + ### Load images from STDIN + + ```console $ docker load < busybox.tar.gz Loaded image: busybox:latest $ docker images REPOSITORY TAG IMAGE ID CREATED SIZE busybox latest 769b9341d937 7 weeks ago 2.489 MB + ``` + ### Load images from a file (--input) + + ```console $ docker load --input fedora.tar Loaded image: fedora:rawhide - Loaded image: fedora:20 $ docker images diff --git a/_data/engine-cli/docker_login.yaml b/_data/engine-cli/docker_login.yaml index c8173e2675..ac6593d520 100644 --- a/_data/engine-cli/docker_login.yaml +++ b/_data/engine-cli/docker_login.yaml @@ -42,7 +42,7 @@ examples: |- $ docker login localhost:8080 ``` - ### Provide a password using STDIN + ### Provide a password using STDIN (--password-stdin) To run the `docker login` command non-interactively, you can set the `--password-stdin` flag to provide a password through `STDIN`. Using diff --git a/_data/engine-cli/docker_logs.yaml b/_data/engine-cli/docker_logs.yaml index c833a2192b..64158a28f7 100644 --- a/_data/engine-cli/docker_logs.yaml +++ b/_data/engine-cli/docker_logs.yaml @@ -3,11 +3,6 @@ short: Fetch the logs of a container long: |- The `docker logs` command batch-retrieves logs present at the time of execution. - > **Note** - > - > This command is only functional for containers that are started with the - > `json-file` or `journald` logging driver. - For more information about selecting and configuring logging drivers, refer to [Configure logging drivers](https://docs.docker.com/config/containers/logging/configure/). @@ -101,7 +96,7 @@ options: kubernetes: false swarm: false examples: |- - ### Retrieve logs until a specific point in time + ### Retrieve logs until a specific point in time (--until) In order to retrieve logs before a specific point in time, run: diff --git a/_data/engine-cli/docker_network_connect.yaml b/_data/engine-cli/docker_network_connect.yaml index c8700505dd..9224936676 100644 --- a/_data/engine-cli/docker_network_connect.yaml +++ b/_data/engine-cli/docker_network_connect.yaml @@ -75,7 +75,7 @@ examples: |- $ docker run -itd --network=multi-host-network busybox ``` - ### Specify the IP address a container will use on a given network + ### Specify the IP address a container will use on a given network (--ip) You can specify the IP address you want to be assigned to the container's interface. @@ -83,7 +83,7 @@ examples: |- $ docker network connect --ip 10.10.36.122 multi-host-network container2 ``` - ### Use the legacy `--link` option + ### Use the legacy `--link` option (--link) You can use `--link` option to link another container with a preferred alias @@ -91,7 +91,7 @@ examples: |- $ docker network connect --link container1:c1 multi-host-network container2 ``` - ### Create a network alias for a container + ### Create a network alias for a container (--alias) `--alias` option can be used to resolve the container by another name in the network being connected to. diff --git a/_data/engine-cli/docker_network_create.yaml b/_data/engine-cli/docker_network_create.yaml index f4e920eb98..3795d69a1a 100644 --- a/_data/engine-cli/docker_network_create.yaml +++ b/_data/engine-cli/docker_network_create.yaml @@ -313,14 +313,14 @@ examples: |- simple-network ``` - ### Network internal mode + ### Network internal mode (--internal) By default, when you connect a container to an `overlay` network, Docker also connects a bridge network to it to provide external connectivity. If you want to create an externally isolated `overlay` network, you can specify the `--internal` option. - ### Network ingress mode + ### Network ingress mode (--ingress) You can create the network which will be used to provide the routing-mesh in the swarm cluster. You do so by specifying `--ingress` when creating the network. Only diff --git a/_data/engine-cli/docker_network_ls.yaml b/_data/engine-cli/docker_network_ls.yaml index dcc05a3bfa..0f234253b7 100644 --- a/_data/engine-cli/docker_network_ls.yaml +++ b/_data/engine-cli/docker_network_ls.yaml @@ -68,7 +68,7 @@ examples: |- 63d1ff1f77b07ca51070a8c227e962238358bd310bde1529cf62e6c307ade161 dev bridge local ``` - ### Filtering + ### Filtering (--filter) The filtering flag (`-f` or `--filter`) format is a `key=value` pair. If there is more than one filter, then pass multiple flags (e.g. `--filter "foo=bar" --filter "bif=baz"`). @@ -213,7 +213,7 @@ examples: |- A warning will be issued when trying to remove a network that has containers attached. - ### Formatting + ### Format the output (--format) The formatting options (`--format`) pretty-prints networks output using a Go template. diff --git a/_data/engine-cli/docker_network_prune.yaml b/_data/engine-cli/docker_network_prune.yaml index 1b23b8c5ca..7434b05464 100644 --- a/_data/engine-cli/docker_network_prune.yaml +++ b/_data/engine-cli/docker_network_prune.yaml @@ -36,7 +36,7 @@ examples: |- n2 ``` - ### Filtering + ### Filtering (--filter) The filtering flag (`--filter`) format is of "key=value". If there is more than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`) diff --git a/_data/engine-cli/docker_node_inspect.yaml b/_data/engine-cli/docker_node_inspect.yaml index 29ad73d0f5..bcf540e9e3 100644 --- a/_data/engine-cli/docker_node_inspect.yaml +++ b/_data/engine-cli/docker_node_inspect.yaml @@ -113,7 +113,7 @@ examples: |- ] ``` - ### Specify an output format + ### Format the output (--format) ```console $ docker node inspect --format '{{ .ManagerStatus.Leader }}' self diff --git a/_data/engine-cli/docker_node_ls.yaml b/_data/engine-cli/docker_node_ls.yaml index a6041eac64..a321eaae62 100644 --- a/_data/engine-cli/docker_node_ls.yaml +++ b/_data/engine-cli/docker_node_ls.yaml @@ -3,7 +3,7 @@ aliases: list short: List nodes in the swarm long: |- Lists all the nodes that the Docker Swarm manager knows about. You can filter - using the `-f` or `--filter` flag. Refer to the [filtering](#filtering) section + using the `-f` or `--filter` flag. Refer to the [filtering](#filter) section for more information about available filter options. > **Note** @@ -60,7 +60,7 @@ examples: |- > `e216jshn25ckzbvmwlnh5jr3g *`) means this node is the current docker daemon. - ### Filtering + ### Filtering (--filter) The filtering flag (`-f` or `--filter`) format is of "key=value". If there is more than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`) @@ -178,7 +178,7 @@ examples: |- e216jshn25ckzbvmwlnh5jr3g * swarm-manager1 Ready Active Leader ``` - ### Formatting + ### Format the output (--format) The formatting options (`--format`) pretty-prints nodes output using a Go template. diff --git a/_data/engine-cli/docker_node_ps.yaml b/_data/engine-cli/docker_node_ps.yaml index 3f3079bb88..b3dff83a7d 100644 --- a/_data/engine-cli/docker_node_ps.yaml +++ b/_data/engine-cli/docker_node_ps.yaml @@ -2,7 +2,7 @@ command: docker node ps short: List tasks running on one or more nodes, defaults to current node long: |- Lists all the tasks on a Node that Docker knows about. You can filter using the - `-f` or `--filter` flag. Refer to the [filtering](#filtering) section for more + `-f` or `--filter` flag. Refer to the [filtering](#filter) section for more information about available filter options. > **Note** @@ -72,7 +72,7 @@ examples: |- redis.10.0tgctg8h8cech4w0k0gwrmr23 redis:3.0.6 swarm-manager1 Running Running 5 seconds ``` - ### Filtering + ### Filtering (--filter) The filtering flag (`-f` or `--filter`) format is of "key=value". If there is more than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`) @@ -133,7 +133,7 @@ examples: |- The `desired-state` filter can take the values `running`, `shutdown`, or `accepted`. - ### Formatting + ### Format the output (--format) The formatting options (`--format`) pretty-prints tasks output using a Go template. diff --git a/_data/engine-cli/docker_node_rm.yaml b/_data/engine-cli/docker_node_rm.yaml index 2cdab5778d..99c1c8f075 100644 --- a/_data/engine-cli/docker_node_rm.yaml +++ b/_data/engine-cli/docker_node_rm.yaml @@ -45,7 +45,7 @@ examples: |- down and can't be removed ``` - ### Forcibly remove an inaccessible node from a swarm + ### Forcibly remove an inaccessible node from a swarm (--force) If you lose access to a worker node or need to shut it down because it has been compromised or is not behaving as expected, you can use the `--force` option. diff --git a/_data/engine-cli/docker_node_update.yaml b/_data/engine-cli/docker_node_update.yaml index 3e1cb42ec9..c2a18feef0 100644 --- a/_data/engine-cli/docker_node_update.yaml +++ b/_data/engine-cli/docker_node_update.yaml @@ -46,7 +46,7 @@ options: kubernetes: false swarm: false examples: |- - ### Add label metadata to a node + ### Add label metadata to a node (--label-add) Add metadata to a swarm node using node labels. You can specify a node label as a key with an empty value: diff --git a/_data/engine-cli/docker_plugin_inspect.yaml b/_data/engine-cli/docker_plugin_inspect.yaml index 0f67e4d4ec..12e272a7ad 100644 --- a/_data/engine-cli/docker_plugin_inspect.yaml +++ b/_data/engine-cli/docker_plugin_inspect.yaml @@ -136,7 +136,7 @@ examples: |- ``` - ### Formatting the output + ### Format the output (--format) ```console $ docker plugin inspect -f '{{.Id}}' tiborvass/sample-volume-plugin:latest diff --git a/_data/engine-cli/docker_plugin_ls.yaml b/_data/engine-cli/docker_plugin_ls.yaml index c2659bfdcd..8c8fba3850 100644 --- a/_data/engine-cli/docker_plugin_ls.yaml +++ b/_data/engine-cli/docker_plugin_ls.yaml @@ -5,7 +5,7 @@ long: |- Lists all the plugins that are currently installed. You can install plugins using the [`docker plugin install`](plugin_install.md) command. You can also filter using the `-f` or `--filter` flag. - Refer to the [filtering](#filtering) section for more information about available filter options. + Refer to the [filtering](#filter) section for more information about available filter options. usage: docker plugin ls [OPTIONS] pname: docker plugin plink: docker_plugin.yaml @@ -54,7 +54,7 @@ examples: |- 69553ca1d123 tiborvass/sample-volume-plugin:latest A test plugin for Docker true ``` - ### Filtering + ### Filtering (--filter) The filtering flag (`-f` or `--filter`) format is of "key=value". If there is more than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`) @@ -84,7 +84,7 @@ examples: |- ID NAME DESCRIPTION ENABLED ``` - ### Formatting + ### Format the output (--format) The formatting options (`--format`) pretty-prints plugins output using a Go template. diff --git a/_data/engine-cli/docker_ps.yaml b/_data/engine-cli/docker_ps.yaml index 15b1facd5c..f93a48f062 100644 --- a/_data/engine-cli/docker_ps.yaml +++ b/_data/engine-cli/docker_ps.yaml @@ -82,7 +82,7 @@ options: kubernetes: false swarm: false examples: |- - ### Prevent truncating output + ### Do not truncate output (--no-trunc) Running `docker ps --no-trunc` showing 2 linked containers. @@ -90,14 +90,14 @@ examples: |- $ docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 4c01db0b339c ubuntu:12.04 bash 17 seconds ago Up 16 seconds 3300-3310/tcp webapp + 4c01db0b339c ubuntu:22.04 bash 17 seconds ago Up 16 seconds 3300-3310/tcp webapp d7886598dbe2 crosbymichael/redis:latest /redis-server --dir 33 minutes ago Up 33 minutes 6379/tcp redis,webapp/db ``` - ### Show both running and stopped containers + ### Show both running and stopped containers (-a, --all) The `docker ps` command only shows running containers by default. To see all - containers, use the `-a` (or `--all`) flag: + containers, use the `--all` (or `-a`) flag: ```console $ docker ps -a @@ -107,12 +107,12 @@ examples: |- container that exposes TCP ports `100, 101, 102` displays `100-102/tcp` in the `PORTS` column. - ### Show disk usage by container + ### Show disk usage by container (--size) - The `docker ps -s` command displays two different on-disk-sizes for each container: + The `docker ps --size` (or `-s`) command displays two different on-disk-sizes for each container: ```console - $ docker ps -s + $ docker ps --size CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES SIZE SIZE e90b8831a4b8 nginx "/bin/bash -c 'mkdir " 11 weeks ago Up 4 hours my_nginx 35.58 kB (virtual 109.2 MB) @@ -124,9 +124,9 @@ examples: |- For more information, refer to the [container size on disk](https://docs.docker.com/storage/storagedriver/#container-size-on-disk) section. - ### Filtering + ### Filtering (--filter) - The filtering flag (`-f` or `--filter`) format is a `key=value` pair. If there is more + The `--filter` (or `-f`) flag format is a `key=value` pair. If there is more than one filter, then pass multiple flags (e.g. `--filter "foo=bar" --filter "bif=baz"`) The currently supported filters are: @@ -287,13 +287,13 @@ examples: |- 919e1179bdb8 ubuntu-c1 "top" About a minute ago Up About a minute admiring_lovelace ``` - Match containers based on the `ubuntu` version `12.04.5` image: + Match containers based on the `ubuntu` version `22.04` image: ```console - $ docker ps --filter ancestor=ubuntu:12.04.5 + $ docker ps --filter ancestor=ubuntu:22.04 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 82a598284012 ubuntu:12.04.5 "top" 3 minutes ago Up 3 minutes sleepy_bose + 82a598284012 ubuntu:22.04 "top" 3 minutes ago Up 3 minutes sleepy_bose ``` The following matches containers based on the layer `d0e008c6cf02` or an image @@ -303,7 +303,7 @@ examples: |- $ docker ps --filter ancestor=d0e008c6cf02 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 82a598284012 ubuntu:12.04.5 "top" 3 minutes ago Up 3 minutes sleepy_bose + 82a598284012 ubuntu:22.04 "top" 3 minutes ago Up 3 minutes sleepy_bose ``` #### Create time @@ -435,7 +435,7 @@ examples: |- CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES ``` - ### Formatting + ### Format the output (--format) The formatting option (`--format`) pretty-prints container output using a Go template. diff --git a/_data/engine-cli/docker_pull.yaml b/_data/engine-cli/docker_pull.yaml index b33ba647c8..4ff66d2707 100644 --- a/_data/engine-cli/docker_pull.yaml +++ b/_data/engine-cli/docker_pull.yaml @@ -71,36 +71,36 @@ examples: |- ### Pull an image from Docker Hub To download a particular image, or set of images (i.e., a repository), use - `docker pull`. If no tag is provided, Docker Engine uses the `:latest` tag as a - default. This command pulls the `debian:latest` image: + `docker image pull` (or the `docker pull` shorthand). If no tag is provided, + Docker Engine uses the `:latest` tag as a default. This example pulls the + `debian:latest` image: ```console - $ docker pull debian + $ docker image pull debian Using default tag: latest latest: Pulling from library/debian - fdd5d7827f33: Pull complete - a3ed95caeb02: Pull complete - Digest: sha256:e7d38b3517548a1c71e41bffe9c8ae6d6d29546ce46bf62159837aad072c90aa + e756f3fdd6a3: Pull complete + Digest: sha256:3f1d6c17773a45c97bd8f158d665c9709d7b29ed7917ac934086ad96f92e4510 Status: Downloaded newer image for debian:latest + docker.io/library/debian:latest ``` Docker images can consist of multiple layers. In the example above, the image - consists of two layers; `fdd5d7827f33` and `a3ed95caeb02`. + consists of a single layer; `e756f3fdd6a3`. - Layers can be reused by images. For example, the `debian:jessie` image shares - both layers with `debian:latest`. Pulling the `debian:jessie` image therefore - only pulls its metadata, but not its layers, because all layers are already - present locally: + Layers can be reused by images. For example, the `debian:bullseye` image shares + its layer with the `debian:latest`. Pulling the `debian:bullseye` image therefore + only pulls its metadata, but not its layers, because the layer is already present + locally: ```console - $ docker pull debian:jessie + $ docker image pull debian:bullseye - jessie: Pulling from library/debian - fdd5d7827f33: Already exists - a3ed95caeb02: Already exists - Digest: sha256:a9c958be96d7d40df920e7041608f2f017af81800ca5ad23e327bc402626b58e - Status: Downloaded newer image for debian:jessie + bullseye: Pulling from library/debian + Digest: sha256:3f1d6c17773a45c97bd8f158d665c9709d7b29ed7917ac934086ad96f92e4510 + Status: Downloaded newer image for debian:bullseye + docker.io/library/debian:bullseye ``` To see which images are present locally, use the [`docker images`](images.md) @@ -109,17 +109,16 @@ examples: |- ```console $ docker images - REPOSITORY TAG IMAGE ID CREATED SIZE - debian jessie f50f9524513f 5 days ago 125.1 MB - debian latest f50f9524513f 5 days ago 125.1 MB + REPOSITORY TAG IMAGE ID CREATED SIZE + debian bullseye 4eacea30377a 8 days ago 124MB + debian latest 4eacea30377a 8 days ago 124MB ``` Docker uses a content-addressable image store, and the image ID is a SHA256 digest covering the image's configuration and layers. In the example above, - `debian:jessie` and `debian:latest` have the same image ID because they are - actually the *same* image tagged with different names. Because they are the - same image, their layers are stored only once and do not consume extra disk - space. + `debian:bullseye` and `debian:latest` have the same image ID because they are + the *same* image tagged with different names. Because they are the same image, + their layers are stored only once and do not consume extra disk space. For more information about images, layers, and the content-addressable store, refer to [understand images, containers, and storage drivers](https://docs.docker.com/storage/storagedriver/). @@ -130,8 +129,8 @@ examples: |- So far, you've pulled images by their name (and "tag"). Using names and tags is a convenient way to work with images. When using tags, you can `docker pull` an image again to make sure you have the most up-to-date version of that image. - For example, `docker pull ubuntu:20.04` pulls the latest version of the Ubuntu - 20.04 image. + For example, `docker pull ubuntu:22.04` pulls the latest version of the Ubuntu + 22.04 image. In some cases you don't want images to be updated to newer versions, but prefer to use a fixed version of an image. Docker enables you to pull an image by its @@ -140,23 +139,23 @@ examples: |- and guarantee that the image you're using is always the same. To know the digest of an image, pull the image first. Let's pull the latest - `ubuntu:20.04` image from Docker Hub: + `ubuntu:22.04` image from Docker Hub: ```console - $ docker pull ubuntu:20.04 + $ docker pull ubuntu:22.04 - 20.04: Pulling from library/ubuntu - 16ec32c2132b: Pull complete - Digest: sha256:82becede498899ec668628e7cb0ad87b6e1c371cb8a1e597d83a47fac21d6af3 - Status: Downloaded newer image for ubuntu:20.04 - docker.io/library/ubuntu:20.04 + 22.04: Pulling from library/ubuntu + 125a6e411906: Pull complete + Digest: sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d + Status: Downloaded newer image for ubuntu:22.04 + docker.io/library/ubuntu:22.04 ``` Docker prints the digest of the image after the pull has finished. In the example above, the digest of the image is: ```console - sha256:82becede498899ec668628e7cb0ad87b6e1c371cb8a1e597d83a47fac21d6af3 + sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d ``` Docker also prints the digest of an image when *pushing* to a registry. This @@ -166,25 +165,25 @@ examples: |- pull the above image by digest, run the following command: ```console - $ docker pull ubuntu@sha256:82becede498899ec668628e7cb0ad87b6e1c371cb8a1e597d83a47fac21d6af3 + $ docker pull ubuntu@sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d - docker.io/library/ubuntu@sha256:82becede498899ec668628e7cb0ad87b6e1c371cb8a1e597d83a47fac21d6af3: Pulling from library/ubuntu - Digest: sha256:82becede498899ec668628e7cb0ad87b6e1c371cb8a1e597d83a47fac21d6af3 - Status: Image is up to date for ubuntu@sha256:82becede498899ec668628e7cb0ad87b6e1c371cb8a1e597d83a47fac21d6af3 - docker.io/library/ubuntu@sha256:82becede498899ec668628e7cb0ad87b6e1c371cb8a1e597d83a47fac21d6af3 + docker.io/library/ubuntu@sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d: Pulling from library/ubuntu + Digest: sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d + Status: Image is up to date for ubuntu@sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d + docker.io/library/ubuntu@sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d ``` Digest can also be used in the `FROM` of a Dockerfile, for example: ```dockerfile - FROM ubuntu@sha256:82becede498899ec668628e7cb0ad87b6e1c371cb8a1e597d83a47fac21d6af3 + FROM ubuntu@sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d LABEL org.opencontainers.image.authors="some maintainer " ``` > **Note** > > Using this feature "pins" an image to a specific version in time. - > Docker will therefore not pull updated versions of an image, which may include + > Docker does therefore not pull updated versions of an image, which may include > security updates. If you want to pull an updated image, you need to change the > digest accordingly. @@ -200,7 +199,7 @@ examples: |- listening on port 5000 (`myregistry.local:5000`): ```console - $ docker pull myregistry.local:5000/testing/test-image + $ docker image pull myregistry.local:5000/testing/test-image ``` Registry credentials are managed by [docker login](login.md). @@ -210,39 +209,41 @@ examples: |- [insecure registries](dockerd.md#insecure-registries) section for more information. - ### Pull a repository with multiple images + ### Pull a repository with multiple images (-a, --all-tags) By default, `docker pull` pulls a *single* image from the registry. A repository can contain multiple images. To pull all images from a repository, provide the `-a` (or `--all-tags`) option when using `docker pull`. - This command pulls all images from the `fedora` repository: + This command pulls all images from the `ubuntu` repository: ```console - $ docker pull --all-tags fedora + $ docker image pull --all-tags ubuntu - Pulling repository fedora + Pulling repository ubuntu ad57ef8d78d7: Download complete 105182bb5e8b: Download complete 511136ea3c5a: Download complete 73bd853d2ea5: Download complete .... - Status: Downloaded newer image for fedora + Status: Downloaded newer image for ubuntu ``` - After the pull has completed use the `docker images` command to see the - images that were pulled. The example below shows all the `fedora` images - that are present locally: + After the pull has completed use the `docker image ls` command (or the `docker images` + shorthand) to see the images that were pulled. The example below shows all the + `ubuntu` images that are present locally: ```console - $ docker images fedora - - REPOSITORY TAG IMAGE ID CREATED SIZE - fedora rawhide ad57ef8d78d7 5 days ago 359.3 MB - fedora 20 105182bb5e8b 5 days ago 372.7 MB - fedora heisenbug 105182bb5e8b 5 days ago 372.7 MB - fedora latest 105182bb5e8b 5 days ago 372.7 MB + $ docker image ls --filter reference=ubuntu + REPOSITORY TAG IMAGE ID CREATED SIZE + ubuntu 18.04 c6ad7e71ba7d 5 weeks ago 63.2MB + ubuntu bionic c6ad7e71ba7d 5 weeks ago 63.2MB + ubuntu 22.04 5ccefbfc0416 2 months ago 78MB + ubuntu focal ff0fea8310f3 2 months ago 72.8MB + ubuntu latest ff0fea8310f3 2 months ago 72.8MB + ubuntu jammy 41ba606c8ab9 3 months ago 79MB + ubuntu 20.04 ba6acccedd29 7 months ago 72.8MB ``` ### Cancel a pull @@ -251,21 +252,18 @@ examples: |- running in a terminal, will terminate the pull operation. ```console - $ docker pull fedora + $ docker pull ubuntu Using default tag: latest - latest: Pulling from library/fedora + latest: Pulling from library/ubuntu a3ed95caeb02: Pulling fs layer 236608c7b546: Pulling fs layer ^C ``` - > **Note** - > - > The Engine terminates a pull operation when the connection between the Docker - > Engine daemon and the Docker Engine client initiating the pull is lost. If the - > connection with the Engine daemon is lost for other reasons than a manual - > interaction, the pull is also aborted. + The Engine terminates a pull operation when the connection between the daemon + and the client (initiating the pull) is cut or lost for any reason or the + command is manually terminated. deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_push.yaml b/_data/engine-cli/docker_push.yaml index 09c47adab1..a9a9e63b47 100644 --- a/_data/engine-cli/docker_push.yaml +++ b/_data/engine-cli/docker_push.yaml @@ -86,7 +86,7 @@ examples: |- You should see both `rhel-httpd` and `registry-host:5000/myadmin/rhel-httpd` listed. - ### Push all tags of an image + ### Push all tags of an image (-a, --all-tags) Use the `-a` (or `--all-tags`) option to push all tags of a local image. diff --git a/_data/engine-cli/docker_rm.yaml b/_data/engine-cli/docker_rm.yaml index 0020d657f7..550d7bf7e8 100644 --- a/_data/engine-cli/docker_rm.yaml +++ b/_data/engine-cli/docker_rm.yaml @@ -46,7 +46,7 @@ examples: |- /redis ``` - ### Remove a link specified with `--link` on the default bridge network + ### Remove a link specified with `--link` on the default bridge network (--link) This removes the underlying link between `/webapp` and the `/redis` containers on the default bridge network, removing all network communication @@ -59,7 +59,7 @@ examples: |- /webapp/redis ``` - ### Force-remove a running container + ### Force-remove a running container (--force) This command force-removes a running container. @@ -102,10 +102,10 @@ examples: |- $ docker ps --filter status=exited -q | xargs docker rm ``` - ### Remove a container and its volumes + ### Remove a container and its volumes (-v, --volumes) ```console - $ docker rm -v redis + $ docker rm --volumes redis redis ``` diff --git a/_data/engine-cli/docker_run.yaml b/_data/engine-cli/docker_run.yaml index 067fff38ef..14b01ef1be 100644 --- a/_data/engine-cli/docker_run.yaml +++ b/_data/engine-cli/docker_run.yaml @@ -8,9 +8,6 @@ long: |- previous changes intact using `docker start`. See `docker ps -a` to view a list of all containers. - The `docker run` command can be used in combination with `docker commit` to - [*change the command that a container runs*](commit.md). There is additional detailed information about `docker run` in the [Docker run reference](../run.md). - For information on connecting a container to a network, see the ["*Docker network overview*"](https://docs.docker.com/network/). usage: docker run [OPTIONS] IMAGE [COMMAND] [ARG...] pname: docker @@ -925,7 +922,7 @@ options: kubernetes: false swarm: false examples: |- - ### Assign name and allocate pseudo-TTY (--name, -it) + ### Assign name and allocate pseudo-TTY (--name, -it) ```console $ docker run --name test -it debian @@ -944,7 +941,7 @@ examples: |- `exit 13`. This exit code is passed on to the caller of `docker run`, and is recorded in the `test` container's metadata. - ### Capture container ID (--cidfile) + ### Capture container ID (--cidfile) ```console $ docker run --cidfile /tmp/docker_test.cid ubuntu echo "test" @@ -955,7 +952,7 @@ examples: |- If the file exists already, Docker will return an error. Docker will close this file when `docker run` exits. - ### Full container capabilities (--privileged) + ### Full container capabilities (--privileged) ```console $ docker run -t -i --rm ubuntu bash @@ -980,7 +977,7 @@ examples: |- words, the container can then do almost everything that the host can do. This flag exists to allow special use-cases, like running Docker within Docker. - ### Set working directory (-w) + ### Set working directory (-w, --workdir) ```console $ docker run -w /path/to/dir/ -i -t ubuntu pwd @@ -989,22 +986,22 @@ examples: |- The `-w` lets the command being executed inside directory given, here `/path/to/dir/`. If the path does not exist it is created inside the container. - ### Set storage driver options per container + ### Set storage driver options per container (--storage-opt) ```console $ docker run -it --storage-opt size=120G fedora /bin/bash ``` - This (size) will allow to set the container rootfs size to 120G at creation time. + This (size) will allow to set the container filesystem size to 120G at creation time. This option is only available for the `devicemapper`, `btrfs`, `overlay2`, `windowsfilter` and `zfs` graph drivers. For the `devicemapper`, `btrfs`, `windowsfilter` and `zfs` graph drivers, user cannot pass a size less than the Default BaseFS Size. For the `overlay2` storage driver, the size option is only available if the - backing fs is `xfs` and mounted with the `pquota` mount option. - Under these conditions, user can pass any size less than the backing fs size. + backing filesystem is `xfs` and mounted with the `pquota` mount option. + Under these conditions, user can pass any size less than the backing filesystem size. - ### Mount tmpfs (--tmpfs) + ### Mount tmpfs (--tmpfs) ```console $ docker run -d --tmpfs /run:rw,noexec,nosuid,size=65536k my_image @@ -1013,7 +1010,7 @@ examples: |- The `--tmpfs` flag mounts an empty tmpfs into the container with the `rw`, `noexec`, `nosuid`, `size=65536k` options. - ### Mount volume (-v, --read-only) + ### Mount volume (-v, --read-only) ```console $ docker run -v `pwd`:`pwd` -w `pwd` -i -t ubuntu pwd @@ -1047,8 +1044,8 @@ examples: |- $ docker run -t -i -v /var/run/docker.sock:/var/run/docker.sock -v /path/to/static-docker-binary:/usr/bin/docker busybox sh ``` - By bind-mounting the docker unix socket and statically linked docker - binary (refer to [get the linux binary](https://docs.docker.com/engine/install/binaries/#install-static-binaries)), + By bind-mounting the Docker Unix socket and statically linked Docker + binary (refer to [get the Linux binary](https://docs.docker.com/engine/install/binaries/#install-static-binaries)), you give the container the full access to create and manipulate the host's Docker daemon. @@ -1079,7 +1076,7 @@ examples: |- For in-depth information about volumes, refer to [manage data in containers](https://docs.docker.com/storage/volumes/) - ### Add bind mounts or volumes using the --mount flag + ### Add bind mounts or volumes using the --mount flag The `--mount` flag allows you to mount volumes, host-directories and `tmpfs` mounts in a container. @@ -1087,7 +1084,7 @@ examples: |- The `--mount` flag supports most options that are supported by the `-v` or the `--volume` flag, but uses a different syntax. For in-depth information on the `--mount` flag, and a comparison between `--volume` and `--mount`, refer to - the [service create command reference](service_create.md#add-bind-mounts-volumes-or-memory-filesystems). + [Bind mounts](https://docs.docker.com/storage/bind-mounts/). Even though there is no plan to deprecate `--volume`, usage of `--mount` is recommended. @@ -1101,7 +1098,7 @@ examples: |- $ docker run -t -i --mount type=bind,src=/data,dst=/data busybox sh ``` - ### Publish or expose port (-p, --expose) + ### Publish or expose port (-p, --expose) ```console $ docker run -p 127.0.0.1:80:8080/tcp ubuntu bash @@ -1139,7 +1136,7 @@ examples: |- When creating (and running) a container from an image, the daemon checks if the image exists in the local image cache. If the image is missing, an error is - returned to the cli, allowing it to initiate a pull. + returned to the CLI, allowing it to initiate a pull. The default (`missing`) is to only pull the image if it is not present in the daemon's image cache. This default allows you to run images that only exist @@ -1166,7 +1163,7 @@ examples: |- docker: Error response from daemon: No such image: hello-world:latest. ``` - ### Set environment variables (-e, --env, --env-file) + ### Set environment variables (-e, --env, --env-file) ```console $ docker run -e MYVAR1 --env MYVAR2=foo --env-file ./env.list ubuntu bash @@ -1217,7 +1214,7 @@ examples: |- USER=jonzeolla ``` - ### Set metadata on container (-l, --label, --label-file) + ### Set metadata on container (-l, --label, --label-file) A label is a `key=value` pair that applies metadata to a container. To label a container with two labels: @@ -1259,12 +1256,14 @@ examples: |- metadata in Docker*](https://docs.docker.com/config/labels-custom-metadata/) in the Docker User Guide. - ### Connect a container to a network (--network) + ### Connect a container to a network (--network) When you start a container use the `--network` flag to connect it to a network. - This adds the `busybox` container to the `my-net` network. + The following commands create a network named `my-net`, and adds a `busybox` container + to the `my-net` network. ```console + $ docker network create my-net $ docker run -itd --network=my-net busybox ``` @@ -1285,14 +1284,14 @@ examples: |- > **Note** > - > Service discovery is unavailable on the default bridge network. Containers can - > communicate via their IP addresses by default. To communicate by name, they - > must be linked. + > The default bridge network only allow containers to communicate with each other using + > internal IP addresses. User-created bridge networks provide DNS resolution between + > containers using container names. You can disconnect a container from a network using the `docker network disconnect` command. - ### Mount volumes from container (--volumes-from) + ### Mount volumes from container (--volumes-from) ```console $ docker run --volumes-from 777f7dc92da7 --volumes-from ba8c0c54f0f2:ro -i -t ubuntu pwd @@ -1318,11 +1317,11 @@ examples: |- The `Z` option tells Docker to label the content with a private unshared label. Only the current container can use a private volume. - ### Attach to STDIN/STDOUT/STDERR (-a) + ### Attach to STDIN/STDOUT/STDERR (-a, --attach) - The `-a` flag tells `docker run` to bind to the container's `STDIN`, `STDOUT` - or `STDERR`. This makes it possible to manipulate the output and input as - needed. + The `--attach` (or `-a`) flag tells `docker run` to bind to the container's + `STDIN`, `STDOUT` or `STDERR`. This makes it possible to manipulate the output + and input as needed. ```console $ echo "test" | docker run -i -a stdin ubuntu cat - @@ -1343,13 +1342,15 @@ examples: |- $ cat somefile | docker run -i -a stdin mybuilder dobuild ``` - This is how piping a file into a container could be done for a build. + This is a way of using `--attach` to pipe a build file into a container. The container's ID will be printed after the build is done and the build logs could be retrieved using `docker logs`. This is useful if you need to pipe a file or something else into a container and retrieve the container's ID once the container has finished running. - ### Add host device to container (--device) + See also [the `docker cp` command](cp.md). + + ### Add host device to container (--device) ```console $ docker run -it --rm \ @@ -1442,14 +1443,14 @@ examples: |- > **Note**: initially present devices still need to be explicitly added to the > `docker run` / `docker create` command. - ### Access an NVIDIA GPU + ### Access an NVIDIA GPU The `--gpus` flag allows you to access NVIDIA GPU resources. First you need to install [nvidia-container-runtime](https://nvidia.github.io/nvidia-container-runtime/). Visit [Specify a container's resources](https://docs.docker.com/config/containers/resource_constraints/) for more information. - To use `--gpus`, specify which GPUs (or all) to use. If no value is provied, all + To use `--gpus`, specify which GPUs (or all) to use. If no value is provided, all available GPUs are used. The example below exposes all available GPUs. ```console @@ -1469,7 +1470,7 @@ examples: |- $ docker run -it --rm --gpus '"device=0,2"' nvidia-smi ``` - ### Restart policies (--restart) + ### Restart policies (--restart) Use Docker's `--restart` to specify a container's *restart policy*. A restart policy controls whether the Docker daemon restarts a container after exit. @@ -1493,7 +1494,7 @@ examples: |- [Restart Policies (--restart)](../run.md#restart-policies---restart) section of the Docker run reference page. - ### Add entries to container hosts file (--add-host) + ### Add entries to container hosts file (--add-host) You can add other hosts into a container's `/etc/hosts` file by using one or more `--add-host` flags. This example adds a static address for a host named @@ -1531,7 +1532,7 @@ examples: |- devices, replace `eth0` with the correct device name (for example `docker0` for the bridge device). - ### Set ulimits in container (--ulimit) + ### Set ulimits in container (--ulimit) Since setting `ulimit` settings in a container requires extra privileges not available in the default container, you can set these using the `--ulimit` flag. @@ -1560,7 +1561,7 @@ examples: |- #### For `nproc` usage Be careful setting `nproc` with the `ulimit` flag as `nproc` is designed by Linux to set the - maximum number of processes available to a user, not to a container. For example, start four + maximum number of processes available to a user, not to a container. For example, start four containers with `daemon` user: ```console @@ -1577,7 +1578,7 @@ examples: |- This fails because the caller set `nproc=3` resulting in the first three containers using up the three processes quota set for the `daemon` user. - ### Stop container with signal (--stop-signal) + ### Stop container with signal (--stop-signal) The `--stop-signal` flag sets the system call signal that will be sent to the container to exit. This signal can be a signal name in the format `SIG`, @@ -1586,12 +1587,12 @@ examples: |- The default is `SIGTERM` if not specified. - ### Optional security options (--security-opt) + ### Optional security options (--security-opt) On Windows, this flag can be used to specify the `credentialspec` option. The `credentialspec` must be in the format `file://spec.txt` or `registry://keyname`. - ### Stop container with timeout (--stop-timeout) + ### Stop container with timeout (--stop-timeout) The `--stop-timeout` flag sets the number of seconds to wait for the container to stop after sending the pre-defined (see `--stop-signal`) system call signal. @@ -1604,7 +1605,7 @@ examples: |- The default is determined by the daemon, and is 10 seconds for Linux containers, and 30 seconds for Windows containers. - ### Specify isolation technology for container (--isolation) + ### Specify isolation technology for container (--isolation) This option is useful in situations where you are running Docker containers on Windows. The `--isolation=` option sets a container's isolation technology. @@ -1625,8 +1626,8 @@ examples: |- | `hyperv` | Hyper-V hypervisor partition-based isolation. | The default isolation on Windows server operating systems is `process`, and `hyperv` - on Windows client operating systems, such as Windows 10. Process isolation is more - performant, but requires the image to + on Windows client operating systems, such as Windows 10. Process isolation has better + performance, but requires that the image and host use the same kernel version. On Windows server, assuming the default configuration, these commands are equivalent and result in `process` isolation: @@ -1647,7 +1648,7 @@ examples: |- PS C:\> docker run -d --isolation hyperv microsoft/nanoserver powershell echo hyperv ``` - ### Specify hard limits on memory available to containers (-m, --memory) + ### Specify hard limits on memory available to containers (-m, --memory) These parameters always set an upper limit on the memory available to the container. On Linux, this is set on the cgroup and applications in a container can query it at `/sys/fs/cgroup/memory/memory.limit_in_bytes`. @@ -1685,7 +1686,7 @@ examples: |- ``` - ### Configure namespaced kernel parameters (sysctls) at runtime + ### Configure namespaced kernel parameters (sysctls) at runtime (--sysctl) The `--sysctl` sets namespaced kernel parameters (sysctls) in the container. For example, to turn on IP forwarding in the containers diff --git a/_data/engine-cli/docker_search.yaml b/_data/engine-cli/docker_search.yaml index e7b82b5a47..31dd1730a1 100644 --- a/_data/engine-cli/docker_search.yaml +++ b/_data/engine-cli/docker_search.yaml @@ -76,7 +76,7 @@ examples: |- marclop/busybox-solr ``` - ### Display non-truncated description (--no-trunc) + ### Display non-truncated description (--no-trunc) This example displays images with a name containing 'busybox', at least 3 stars and the description isn't truncated in the output: @@ -90,12 +90,12 @@ examples: |- radial/busyboxplus Full-chain, Internet enabled, busybox made from scratch. Comes in git and cURL flavors. 8 [OK] ``` - ### Limit search results (--limit) + ### Limit search results (--limit) The flag `--limit` is the maximum number of results returned by a search. This value could be in the range between 1 and 100. The default value of `--limit` is 25. - ### Filtering + ### Filtering (--filter) The filtering flag (`-f` or `--filter`) format is a `key=value` pair. If there is more than one filter, then pass multiple flags (e.g. `--filter is-automated=true --filter stars=3`) @@ -145,7 +145,7 @@ examples: |- busybox Busybox base image. 325 [OK] ``` - ### Format the output + ### Format the output (--format) The formatting option (`--format`) pretty-prints search output using a Go template. diff --git a/_data/engine-cli/docker_secret_create.yaml b/_data/engine-cli/docker_secret_create.yaml index ffedb1b8ff..f58aa284c5 100644 --- a/_data/engine-cli/docker_secret_create.yaml +++ b/_data/engine-cli/docker_secret_create.yaml @@ -70,7 +70,7 @@ examples: |- dg426haahpi5ezmkkj5kyl3sn my_secret 7 seconds ago 7 seconds ago ``` - ### Create a secret with labels + ### Create a secret with labels (--label) ```console $ docker secret create \ diff --git a/_data/engine-cli/docker_secret_inspect.yaml b/_data/engine-cli/docker_secret_inspect.yaml index 0e21f0ce08..b62135b9bf 100644 --- a/_data/engine-cli/docker_secret_inspect.yaml +++ b/_data/engine-cli/docker_secret_inspect.yaml @@ -79,7 +79,7 @@ examples: |- ] ``` - ### Formatting + ### Format the output (--format) You can use the --format option to obtain specific information about a secret. The following example command outputs the creation time of the diff --git a/_data/engine-cli/docker_secret_ls.yaml b/_data/engine-cli/docker_secret_ls.yaml index 5fd6473acf..fd63d8a023 100644 --- a/_data/engine-cli/docker_secret_ls.yaml +++ b/_data/engine-cli/docker_secret_ls.yaml @@ -53,7 +53,7 @@ examples: |- mem02h8n73mybpgqjf0kfi1n0 test_secret 3 seconds ago 3 seconds ago ``` - ### Filtering + ### Filtering (--filter) The filtering flag (`-f` or `--filter`) format is a `key=value` pair. If there is more than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`) @@ -113,7 +113,7 @@ examples: |- mem02h8n73mybpgqjf0kfi1n0 test_secret About an hour ago About an hour ago ``` - ### Format the output + ### Format the output (--format) The formatting option (`--format`) pretty prints secrets output using a Go template. diff --git a/_data/engine-cli/docker_service_create.yaml b/_data/engine-cli/docker_service_create.yaml index a994bc1bb6..feff327953 100644 --- a/_data/engine-cli/docker_service_create.yaml +++ b/_data/engine-cli/docker_service_create.yaml @@ -687,7 +687,7 @@ examples: |- a8q9dasaafud redis2 global 1/1 redis:3.0.6 ``` - #### Create a service using an image on a private registry + #### Create a service using an image on a private registry (--with-registry-auth) If your image is available on a private registry which requires login, use the `--with-registry-auth` flag with `docker service create`, after logging in. If @@ -707,7 +707,7 @@ examples: |- service is deployed, using the encrypted WAL logs. With this information, the nodes are able to log into the registry and pull the image. - ### Create a service with 5 replica tasks (--replicas) + ### Create a service with 5 replica tasks (--replicas) Use the `--replicas` flag to set the number of replica tasks for a replicated service. The following command creates a `redis` service with `5` replica tasks: @@ -743,7 +743,7 @@ examples: |- 4cdgfyky7ozw redis replicated 5/5 redis:3.0.7 ``` - ### Create a service with secrets + ### Create a service with secrets (--secret) Use the `--secret` flag to give a container access to a [secret](secret_create.md). @@ -775,7 +775,7 @@ examples: |- example above, two files are created: `/run/secrets/ssh` and `/run/secrets/app` for each of the secret targets specified. - ### Create a service with configs + ### Create a service with configs (--config) Use the `--config` flag to give a container access to a [config](config_create.md). @@ -804,7 +804,7 @@ examples: |- target is specified, the name of the config is used as the name of the file in the container. If a target is specified, that is used as the filename. - ### Create a service with a rolling update policy + ### Create a service with a rolling update policy ```console $ docker service create \ @@ -820,7 +820,7 @@ examples: |- refer to the [rolling updates tutorial](https://docs.docker.com/engine/swarm/swarm-tutorial/rolling-update/). - ### Set environment variables (-e, --env) + ### Set environment variables (-e, --env) This sets an environment variable for all tasks in a service. For example: @@ -844,7 +844,7 @@ examples: |- redis:3.0.6 ``` - ### Create a service with specific hostname (--hostname) + ### Create a service with specific hostname (--hostname) This option sets the docker service containers hostname to a specific string. For example: @@ -853,7 +853,7 @@ examples: |- $ docker service create --name redis --hostname myredis redis:3.0.6 ``` - ### Set metadata on a service (-l, --label) + ### Set metadata on a service (-l, --label) A label is a `key=value` pair that applies metadata to a service. To label a service with two labels: @@ -861,7 +861,7 @@ examples: |- ```console $ docker service create \ --name redis_2 \ - --label com.example.foo="bar" + --label com.example.foo="bar" \ --label bar=baz \ redis:3.0.6 ``` @@ -869,7 +869,7 @@ examples: |- For more information about labels, refer to [apply custom metadata](https://docs.docker.com/config/labels-custom-metadata/). - ### Add bind mounts, volumes or memory filesystems + ### Add bind mounts, volumes or memory filesystems (--mount) Docker supports three different kinds of mounts, which allow containers to read from or write to files or directories, either on the host operating system, or @@ -1232,7 +1232,7 @@ examples: |- redis:3.0.6 ``` - ### Specify service constraints (--constraint) + ### Specify service constraints (--constraint) You can limit the set of nodes where a task can be scheduled by defining constraint expressions. Constraint expressions can either use a _match_ (`==`) @@ -1248,7 +1248,7 @@ examples: |- | `node.platform.os` | Node operating system | `node.platform.os==windows` | | `node.platform.arch` | Node architecture | `node.platform.arch==x86_64` | | `node.labels` | User-defined node labels | `node.labels.security==high` | - | `engine.labels` | Docker Engine's labels | `engine.labels.operatingsystem==ubuntu-14.04` | + | `engine.labels` | Docker Engine's labels | `engine.labels.operatingsystem==ubuntu-22.04` | `engine.labels` apply to Docker Engine labels like operating system, drivers, etc. Swarm administrators add `node.labels` for operational purposes by using @@ -1299,7 +1299,7 @@ examples: |- b6lww17hrr4e web replicated 1/1 nginx:alpine ``` - ### Specify service placement preferences (--placement-pref) + ### Specify service placement preferences (--placement-pref) You can set up the service to divide tasks evenly over different categories of nodes. One example of where this can be useful is to balance tasks over a set @@ -1370,7 +1370,7 @@ examples: |- `--placement-pref-rm` removes an existing placement preference that matches the argument. - ### Specify memory requirements and constraints for a service (--reserve-memory and --limit-memory) + ### Specify memory requirements and constraints for a service (--reserve-memory and --limit-memory) If your service needs a minimum amount of memory in order to run correctly, you can use `--reserve-memory` to specify that the service should only be @@ -1438,7 +1438,7 @@ examples: |- host at the level of the host operating system, using `cgroups` or other relevant operating system tools. - ### Specify maximum replicas per node (--replicas-max-per-node) + ### Specify maximum replicas per node (--replicas-max-per-node) Use the `--replicas-max-per-node` flag to set the maximum number of replica tasks that can run on a node. The following command creates a nginx service with 2 replica tasks but only one replica task per node. @@ -1458,7 +1458,7 @@ examples: |- nginx ``` - ### Attach a service to an existing network (--network) + ### Attach a service to an existing network (--network) You can use overlay networks to connect one or more services within the swarm. @@ -1495,7 +1495,7 @@ examples: |- Long form syntax of `--network` allows to specify list of aliases and driver options: `--network name=my-network,alias=web1,driver-opt=field1=value1` - ### Publish service ports externally to the swarm (-p, --publish) + ### Publish service ports externally to the swarm (-p, --publish) You can publish service ports to make them available externally to the swarm using the `--publish` flag. The `--publish` flag can take two different styles @@ -1566,7 +1566,7 @@ examples: |- the long syntax. For more information refer to [Use swarm mode routing mesh](https://docs.docker.com/engine/swarm/ingress/). - ### Provide credential specs for managed service accounts (Windows only) + ### Provide credential specs for managed service accounts (--credentials-spec) This option is only used for services using Windows containers. The `--credential-spec` must be in the format `file://` or @@ -1661,7 +1661,7 @@ examples: |- x3ti0erg11rjpg64m75kej2mz-hosttempl ``` - ### Specify isolation mode (Windows) + ### Specify isolation mode on Windows (--isolation) By default, tasks scheduled on Windows nodes are run using the default isolation mode configured for this particular node. To force a specific isolation mode, you can use @@ -1676,7 +1676,7 @@ examples: |- - `process`: use process isolation (Windows server only) - `hyperv`: use Hyper-V isolation - ### Create services requesting Generic Resources + ### Create services requesting Generic Resources (--generic-resources) You can narrow the kind of nodes your task can land on through the using the `--generic-resource` flag (if the nodes advertise these resources): diff --git a/_data/engine-cli/docker_service_inspect.yaml b/_data/engine-cli/docker_service_inspect.yaml index 346c9db0bd..e0aed46b0c 100644 --- a/_data/engine-cli/docker_service_inspect.yaml +++ b/_data/engine-cli/docker_service_inspect.yaml @@ -115,7 +115,7 @@ examples: |- ] ``` - ### Formatting + ### Formatting (--pretty) You can print the inspect output in a human-readable format instead of the default JSON output, by using the `--pretty` option: @@ -148,9 +148,9 @@ examples: |- You can also use `--format pretty` for the same effect. + ### Format the output (--format) - #### Find the number of tasks running as part of a service - + You can use the --format option to obtain specific information about a The `--format` option can be used to obtain specific information about a service. For example, the following command outputs the number of replicas of the "redis" service. diff --git a/_data/engine-cli/docker_service_ls.yaml b/_data/engine-cli/docker_service_ls.yaml index 960293d0ab..484bc60b5b 100644 --- a/_data/engine-cli/docker_service_ls.yaml +++ b/_data/engine-cli/docker_service_ls.yaml @@ -59,7 +59,7 @@ examples: |- additionally show the completion status of the job as completed tasks over total tasks the job will execute. - ### Filtering + ### Filtering (--filter) The filtering flag (`-f` or `--filter`) format is of "key=value". If there is more than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`) @@ -131,7 +131,7 @@ examples: |- 0bcjwfh8ychr redis replicated 1/1 redis:3.0.6 ``` - ### Formatting + ### Format the output (--format) The formatting options (`--format`) pretty-prints services output using a Go template. diff --git a/_data/engine-cli/docker_service_ps.yaml b/_data/engine-cli/docker_service_ps.yaml index 05bce66933..d2d50beaa4 100644 --- a/_data/engine-cli/docker_service_ps.yaml +++ b/_data/engine-cli/docker_service_ps.yaml @@ -118,7 +118,7 @@ examples: |- nvjljf7rmor4htv7l8rwcx7i7 \_ redis.2 redis:3.0.6@sha256:6a692a76c2081888b589e26e6ec835743119fe453d67ecf03df7de5b73d69842 worker2 Shutdown Rejected 5 minutes ago "No such image: redis@sha256:6a692a76c2081888b589e26e6ec835743119fe453d67ecf03df7de5b73d69842" ``` - ### Filtering + ### Filtering (--filter) The filtering flag (`-f` or `--filter`) format is a `key=value` pair. If there is more than one filter, then pass multiple flags (e.g. `--filter "foo=bar" --filter "bif=baz"`). @@ -175,7 +175,7 @@ examples: |- The `desired-state` filter can take the values `running`, `shutdown`, or `accepted`. - ### Formatting + ### Format the output (--format) The formatting options (`--format`) pretty-prints tasks output using a Go template. diff --git a/_data/engine-cli/docker_service_update.yaml b/_data/engine-cli/docker_service_update.yaml index 150fcf64cf..41422b558e 100644 --- a/_data/engine-cli/docker_service_update.yaml +++ b/_data/engine-cli/docker_service_update.yaml @@ -841,7 +841,7 @@ examples: |- $ docker service update --limit-cpu 2 redis ``` - ### Perform a rolling restart with no parameter changes + ### Perform a rolling restart with no parameter changes ```console $ docker service update --force --update-parallelism 1 --update-delay 30s redis @@ -854,7 +854,7 @@ examples: |- `--update-delay 30s` setting introduces a 30 second delay between tasks, so that the rolling restart happens gradually. - ### Add or remove mounts + ### Add or remove mounts (--mount-add, --mount-rm) Use the `--mount-add` or `--mount-rm` options add or remove a service's bind mounts or volumes. @@ -866,7 +866,7 @@ examples: |- service name. - The `--mount-add` flag takes the same parameters as the `--mount` flag on - `service create`. Refer to the [volumes and bind mounts](service_create.md#add-bind-mounts-volumes-or-memory-filesystems) + `service create`. Refer to the [volumes and bind mounts](service_create.md#mount) section in the `service create` reference for details. - The `--mount-rm` flag takes the `target` path of the mount. @@ -890,11 +890,11 @@ examples: |- myservice ``` - ### Add or remove published service ports + ### Add or remove published service ports (--publish-add, --publish-rm) Use the `--publish-add` or `--publish-rm` flags to add or remove a published port for a service. You can use the short or long syntax discussed in the - [docker service create](service_create.md#publish-service-ports-externally-to-the-swarm--p---publish) + [docker service create](service_create.md#publish) reference. The following example adds a published service port to an existing service. @@ -905,11 +905,11 @@ examples: |- myservice ``` - ### Add or remove network + ### Add or remove network (--network-add, --network-rm) Use the `--network-add` or `--network-rm` flags to add or remove a network for a service. You can use the short or long syntax discussed in the - [docker service create](service_create.md#attach-a-service-to-an-existing-network---network) + [docker service create](service_create.md#network) reference. The following example adds a new alias name to an existing service already connected to network my-network: @@ -921,7 +921,7 @@ examples: |- myservice ``` - ### Roll back to the previous version of a service + ### Roll back to the previous version of a service (--rollback) Use the `--rollback` option to roll back to the previous version of the service. @@ -987,7 +987,7 @@ examples: |- tasks at a time will get rolled back. These rollback parameters are respected both during automatic rollbacks and for rollbacks initiated manually using `--rollback`. - ### Add or remove secrets + ### Add or remove secrets (--secret-add, --secret-rm) Use the `--secret-add` or `--secret-rm` options add or remove a service's secrets. @@ -1007,7 +1007,7 @@ examples: |- See [`service create`](service_create.md#create-services-using-templates) for the reference. - ### Specify isolation mode (Windows) + ### Specify isolation mode on Windows (--isolation) `service update` supports the same `--isolation` flag as `service create` See [`service create`](service_create.md) for the reference. diff --git a/_data/engine-cli/docker_stack_deploy.yaml b/_data/engine-cli/docker_stack_deploy.yaml index e5c42b6d3d..64a86f8edc 100644 --- a/_data/engine-cli/docker_stack_deploy.yaml +++ b/_data/engine-cli/docker_stack_deploy.yaml @@ -81,7 +81,7 @@ inherited_options: kubernetes: false swarm: false examples: |- - ### Compose file + ### Compose file (--compose-file) The `deploy` command supports compose file version `3.0` and above. diff --git a/_data/engine-cli/docker_stack_ls.yaml b/_data/engine-cli/docker_stack_ls.yaml index c2ebc8ff53..41e59e0fe2 100644 --- a/_data/engine-cli/docker_stack_ls.yaml +++ b/_data/engine-cli/docker_stack_ls.yaml @@ -68,7 +68,7 @@ examples: |- vossibility-stack 6 Swarm ``` - ### Formatting + ### Format the output (--format) The formatting option (`--format`) pretty-prints stacks using a Go template. diff --git a/_data/engine-cli/docker_stack_ps.yaml b/_data/engine-cli/docker_stack_ps.yaml index bf870e8d37..74f19ef86a 100644 --- a/_data/engine-cli/docker_stack_ps.yaml +++ b/_data/engine-cli/docker_stack_ps.yaml @@ -102,7 +102,7 @@ examples: |- t72q3z038jeh voting_redis.2 redis:alpine node3 Running Running 3 minutes ago ``` - ### Filtering + ### Filtering (--filter) The filtering flag (`-f` or `--filter`) format is a `key=value` pair. If there is more than one filter, then pass multiple flags (e.g. `--filter "foo=bar" --filter "bif=baz"`). @@ -171,7 +171,7 @@ examples: |- t72q3z038jeh voting_redis.2 redis:alpine node3 Running Running 21 minutes ago ``` - ### Formatting + ### Format the output (--format) The formatting options (`--format`) pretty-prints tasks output using a Go template. @@ -208,7 +208,7 @@ examples: |- voting_redis.2: redis:alpine ``` - ### Do not map IDs to Names + ### Do not map IDs to Names (--no-resolve) The `--no-resolve` option shows IDs for task name, without mapping IDs to Names. @@ -226,7 +226,7 @@ examples: |- t72q3z038jeh tg61x8myx563ueo3urmn1ic6m.2 redis:alpine kanqcxfajd1r16wlnqcblobmm Running Running 31 minutes ago ``` - ### Do not truncate output + ### Do not truncate output (--no-trunc) When deploying a service, docker resolves the digest for the service's image, and pins the service to that digest. The digest is not shown by @@ -247,7 +247,7 @@ examples: |- t72q3z038jehe1wbh9gdum076 voting_redis.2 redis:alpine@sha256:9cd405cd1ec1410eaab064a1383d0d8854d1ef74a54e1e4a92fb4ec7bdc3ee7 node3 Running Runnin 32 minutes ago ``` - ### Only display task IDs + ### Only display task IDs (-q, --quiet) The `-q ` or `--quiet` option only shows IDs of the tasks in the stack. This example outputs all task IDs of the "voting" stack; diff --git a/_data/engine-cli/docker_stack_services.yaml b/_data/engine-cli/docker_stack_services.yaml index 3035330b31..718e09f9a2 100644 --- a/_data/engine-cli/docker_stack_services.yaml +++ b/_data/engine-cli/docker_stack_services.yaml @@ -76,7 +76,7 @@ examples: |- dn7m7nhhfb9y myapp_db 1/1 mysql@sha256:a9a5b559f8821fe73d58c3606c812d1c044868d42c63817fa5125fd9d8b7b539 ``` - ### Filtering + ### Filtering (--filter) The filtering flag (`-f` or `--filter`) format is a `key=value` pair. If there is more than one filter, then pass multiple flags (e.g. `--filter "foo=bar" --filter "bif=baz"`). @@ -113,7 +113,7 @@ examples: |- * Swarm: not supported * Kubernetes: supported - ### Formatting + ### Format the output (--format) The formatting options (`--format`) pretty-prints services output using a Go template. diff --git a/_data/engine-cli/docker_stats.yaml b/_data/engine-cli/docker_stats.yaml index 99c0aaa376..34fa3e0981 100644 --- a/_data/engine-cli/docker_stats.yaml +++ b/_data/engine-cli/docker_stats.yaml @@ -81,7 +81,7 @@ examples: |- 4bda148efbc0 random.1.vnc8on831idyr42slu578u3cr 0.00% 1.672MiB / 1.952GiB 0.08% 110kB / 0B 578kB / 0B 2 ``` - If you don't [specify a format string using `--format`](#formatting), the + If you don't [specify a format string using `--format`](#format), the following columns are shown. | Column name | Description | @@ -149,7 +149,7 @@ examples: |- 9db7aa4d986d mad_wilson 9.59% 40.09 MiB 27.6 kB / 8.81 kB 17 MB / 20.1 MB ``` - ### Formatting + ### Format the output (--format) The formatting option (`--format`) pretty prints container output using a Go template. diff --git a/_data/engine-cli/docker_swarm_ca.yaml b/_data/engine-cli/docker_swarm_ca.yaml index 09c54f39ae..199e1489e2 100644 --- a/_data/engine-cli/docker_swarm_ca.yaml +++ b/_data/engine-cli/docker_swarm_ca.yaml @@ -128,7 +128,7 @@ examples: |- -----END CERTIFICATE----- ``` - ### `--rotate` + ### Root CA rotation (--rotate) Root CA Rotation is recommended if one or more of the swarm managers have been compromised, so that those managers can no longer connect to or be trusted by @@ -151,7 +151,7 @@ examples: |- see if any nodes are down or otherwise unable to rotate TLS certificates. - ### `--detach` + ### Run root CA rotation in detached mode (--detach) Initiate the root CA rotation, but do not wait for the completion of or display the progress of the rotation. diff --git a/_data/engine-cli/docker_system_events.yaml b/_data/engine-cli/docker_system_events.yaml index 5f07232a06..590218642f 100644 --- a/_data/engine-cli/docker_system_events.yaml +++ b/_data/engine-cli/docker_system_events.yaml @@ -19,6 +19,7 @@ long: |- - `die` - `exec_create` - `exec_detach` + - `exec_die` - `exec_start` - `export` - `health_status` @@ -97,7 +98,7 @@ long: |- seconds (aka Unix epoch or Unix time), and the optional .nanoseconds field is a fraction of a second no more than nine digits long. - #### Filtering + #### Filtering (--filter) The filtering flag (`-f` or `--filter`) format is of "key=value". If you would like to use multiple filters, pass multiple flags (e.g., @@ -122,16 +123,6 @@ long: |- * plugin (`plugin=`) * type (`type=`) * volume (`volume=`) - - #### Format - - If a format (`--format`) is specified, the given template will be executed - instead of the default - format. Go's [text/template](https://golang.org/pkg/text/template/) package - describes all the details of the format. - - If a format is set to `{{json .}}`, the events are streamed as valid JSON - Lines. For information about JSON Lines, please refer to https://jsonlines.org/ . usage: docker system events [OPTIONS] pname: docker system plink: docker_system.yaml @@ -306,8 +297,8 @@ examples: |- $ docker system events --filter 'container=container_1' --filter 'container=container_2' - 2014-09-03T15:49:29.999999999Z07:00 container die 4386fb97867d (image=ubuntu-1:14.04) - 2014-05-10T17:42:14.999999999Z07:00 container stop 4386fb97867d (image=ubuntu-1:14.04) + 2014-09-03T15:49:29.999999999Z07:00 container die 4386fb97867d (image=ubuntu:22.04 ) + 2014-05-10T17:42:14.999999999Z07:00 container stop 4386fb97867d (image=ubuntu:22.04 ) 2014-05-10T17:42:14.999999999Z07:00 container die 7805c1d35632 (imager=redis:2.8) 2014-09-03T15:49:29.999999999Z07:00 container stop 7805c1d35632 (image=redis:2.8) @@ -329,7 +320,11 @@ examples: |- 2016-07-25T17:30:14.888127370Z plugin enable ec7b87f2ce84330fe076e666f17dfc049d2d7ae0b8190763de94e1f2d105993f (name=tiborvass/sample-volume-plugin:latest) ``` - ### Format the output + ### Format the output (--format) + + If a format (`--format`) is specified, the given template will be executed + instead of the default format. Go's [text/template](https://golang.org/pkg/text/template/) + package describes all the details of the format. ```console $ docker system events --filter 'type=container' --format 'Type={{.Type}} Status={{.Status}} ID={{.ID}}' @@ -344,6 +339,9 @@ examples: |- #### Format as JSON + If a format is set to `{{json .}}`, the events are streamed as valid JSON + Lines. For information about JSON Lines, please refer to https://jsonlines.org/ . + ```console $ docker system events --format '{{json .}}' diff --git a/_data/engine-cli/docker_system_prune.yaml b/_data/engine-cli/docker_system_prune.yaml index 3a724d965f..2a1f78ba42 100644 --- a/_data/engine-cli/docker_system_prune.yaml +++ b/_data/engine-cli/docker_system_prune.yaml @@ -117,7 +117,7 @@ examples: |- Total reclaimed space: 13.5 MB ``` - ### Filtering + ### Filtering (--filter) The filtering flag (`--filter`) format is of "key=value". If there is more than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`) diff --git a/_data/engine-cli/docker_update.yaml b/_data/engine-cli/docker_update.yaml index 5a8509a499..c44066c55c 100644 --- a/_data/engine-cli/docker_update.yaml +++ b/_data/engine-cli/docker_update.yaml @@ -163,7 +163,7 @@ options: examples: |- The following sections illustrate ways to use this command. - ### Update a container's cpu-shares + ### Update a container's cpu-shares (--cpu-shares) To limit a container's cpu-shares to 512, first identify the container name or ID. You can use `docker ps` to find these values. You can also @@ -173,7 +173,7 @@ examples: |- $ docker update --cpu-shares 512 abebf7571666 ``` - ### Update a container with cpu-shares and memory + ### Update a container with cpu-shares and memory (-m, --memory) To update multiple resource configurations for multiple containers: @@ -181,7 +181,7 @@ examples: |- $ docker update --cpu-shares 512 -m 300M abebf7571666 hopeful_morse ``` - ### Update a container's kernel memory constraints + ### Update a container's kernel memory constraints (--kernel-memory) You can update a container's kernel memory limit using the `--kernel-memory` option. On kernel version older than 4.6, this option can be updated on a @@ -218,7 +218,7 @@ examples: |- Kernel version newer than (include) 4.6 does not have this limitation, you can use `--kernel-memory` the same way as other options. - ### Update a container's restart policy + ### Update a container's restart policy (--restart) You can change a container's restart policy on a running container. The new restart policy takes effect instantly after you run `docker update` on a diff --git a/_data/engine-cli/docker_version.yaml b/_data/engine-cli/docker_version.yaml index dd9b0e9b1e..197174170c 100644 --- a/_data/engine-cli/docker_version.yaml +++ b/_data/engine-cli/docker_version.yaml @@ -1,11 +1,101 @@ command: docker version short: Show the Docker version information long: |- - By default, this will render all version information in an easy to read - layout. If a format is specified, the given template will be executed instead. + The version command prints the current version number for all independently + versioned Docker components. Use the [`--format`](#format) option to customize + the output. - Go's [text/template](https://golang.org/pkg/text/template/) package - describes all the details of the format. + The version command (`docker version`) outputs the version numbers of Docker + components, while the `--version` flag (`docker --version`) outputs the version + number of the Docker CLI you are using. + + ### Default output + + The default output renders all version information divided into two sections; + the "Client" section contains information about the Docker CLI and client + components, and the "Server" section contains information about the Docker + Engine and components used by the Engine, such as the "Containerd" and "Runc" + OCI Runtimes. + + The information shown may differ depending on how you installed Docker and + what components are in use. The following example shows the output on a macOS + machine running Docker Desktop: + + ```console + $ docker version + + Client: + Version: 20.10.16 + API version: 1.41 + Go version: go1.17.10 + Git commit: aa7e414 + Built: Thu May 12 09:17:28 2022 + OS/Arch: darwin/amd64 + Context: default + + Server: Docker Desktop 4.8.2 (77141) + Engine: + Version: 20.10.16 + API version: 1.41 (minimum version 1.12) + Go version: go1.17.10 + Git commit: f756502 + Built: Thu May 12 09:15:33 2022 + OS/Arch: linux/amd64 + Experimental: false + containerd: + Version: 1.6.4 + GitCommit: 212e8b6fa2f44b9c21b2798135fc6fb7c53efc16 + runc: + Version: 1.1.1 + GitCommit: v1.1.1-0-g52de29d + docker-init: + Version: 0.19.0 + GitCommit: de40ad0 + ``` + + ### Client and server versions + + Docker uses a client/server architecture, which allows you to use the Docker CLI + on your local machine to control a Docker Engine running on a remote machine, + which can be (for example) a machine running in the Cloud or inside a Virtual Machine. + + The following example switches the Docker CLI to use a [context](context.md) + named "remote-test-server", which runs an older version of the Docker Engine + on a Linux server: + + ```console + $ docker context use remote-test-server + remote-test-server + + $ docker version + + Client: + Version: 20.10.16 + API version: 1.40 (downgraded from 1.41) + Go version: go1.17.10 + Git commit: aa7e414 + Built: Thu May 12 09:17:28 2022 + OS/Arch: darwin/amd64 + Context: remote-test-server + + Server: Docker Engine - Community + Engine: + Version: 19.03.8 + API version: 1.40 (minimum version 1.12) + Go version: go1.12.17 + Git commit: afacb8b + Built: Wed Mar 11 01:29:16 2020 + OS/Arch: linux/amd64 + containerd: + Version: v1.2.13 + GitCommit: 7ad184331fa3e55e52b890ea95e65ba581ae3429 + runc: + Version: 1.0.0-rc10 + GitCommit: dc9208a3303feef5b3839f4323d9beb36df0a9dd + docker-init: + Version: 0.18.0 + GitCommit: fec3683 + ``` usage: docker version [OPTIONS] pname: docker plink: docker.yaml @@ -28,47 +118,19 @@ options: kubernetes: true swarm: false examples: |- - ### Default output + ### Format the output (--format) - ```console - $ docker version - - Client: - Version: 19.03.8 - API version: 1.40 - Go version: go1.12.17 - Git commit: afacb8b - Built: Wed Mar 11 01:21:11 2020 - OS/Arch: darwin/amd64 - Context: default - Experimental: true - - Server: - Engine: - Version: 19.03.8 - API version: 1.40 (minimum version 1.12) - Go version: go1.12.17 - Git commit: afacb8b - Built: Wed Mar 11 01:29:16 2020 - OS/Arch: linux/amd64 - Experimental: true - containerd: - Version: v1.2.13 - GitCommit: 7ad184331fa3e55e52b890ea95e65ba581ae3429 - runc: - Version: 1.0.0-rc10 - GitCommit: dc9208a3303feef5b3839f4323d9beb36df0a9dd - docker-init: - Version: 0.18.0 - GitCommit: fec3683 - ``` + The formatting option (`--format`) pretty-prints the output using a Go template, + which allows you to customize the output format, or to obtain specific information + from the output. Refer to the [format command and log output](https://docs.docker.com/config/formatting/) + page for details of the format. ### Get the server version ```console $ docker version --format '{{.Server.Version}}' - 19.03.8 + 20.10.16 ``` ### Dump raw JSON data diff --git a/_data/engine-cli/docker_volume_create.yaml b/_data/engine-cli/docker_volume_create.yaml index 720764b596..c38a4725e8 100644 --- a/_data/engine-cli/docker_volume_create.yaml +++ b/_data/engine-cli/docker_volume_create.yaml @@ -72,7 +72,7 @@ examples: |- If you specify a volume name already in use on the current driver, Docker assumes you want to re-use the existing volume and does not return an error. - ### Driver-specific options + ### Driver-specific options (-o, --opt) Some volume drivers may take options to customize the volume creation. Use the `-o` or `--opt` flags to pass driver options: diff --git a/_data/engine-cli/docker_volume_inspect.yaml b/_data/engine-cli/docker_volume_inspect.yaml index fc70b3008b..3fcc4af7fb 100644 --- a/_data/engine-cli/docker_volume_inspect.yaml +++ b/_data/engine-cli/docker_volume_inspect.yaml @@ -48,6 +48,8 @@ examples: |- ] ``` + ### Format the output (--format) + Use the `--format` flag to format the output using a Go template, for example, to print the `Mountpoint` property: diff --git a/_data/engine-cli/docker_volume_ls.yaml b/_data/engine-cli/docker_volume_ls.yaml index 4a691f0655..0a1dd059e7 100644 --- a/_data/engine-cli/docker_volume_ls.yaml +++ b/_data/engine-cli/docker_volume_ls.yaml @@ -3,7 +3,7 @@ aliases: list short: List volumes long: |- List all the volumes known to Docker. You can filter using the `-f` or - `--filter` flag. Refer to the [filtering](#filtering) section for more + `--filter` flag. Refer to the [filtering](#filter) section for more information about available filter options. usage: docker volume ls [OPTIONS] pname: docker volume @@ -55,7 +55,7 @@ examples: |- local tyler ``` - ### Filtering + ### Filtering (--filter) The filtering flag (`-f` or `--filter`) format is of "key=value". If there is more than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`) @@ -155,7 +155,7 @@ examples: |- local rosemary ``` - ### Formatting + ### Format the output (--format) The formatting options (`--format`) pretty-prints volumes output using a Go template. diff --git a/_data/engine-cli/docker_volume_prune.yaml b/_data/engine-cli/docker_volume_prune.yaml index 12bec840e2..69d04e7ff3 100644 --- a/_data/engine-cli/docker_volume_prune.yaml +++ b/_data/engine-cli/docker_volume_prune.yaml @@ -36,6 +36,20 @@ examples: |- Total reclaimed space: 36 B ``` + + ### Filtering (--filter) + + The filtering flag (`--filter`) format is of "key=value". If there is more + than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`) + + The currently supported filters are: + + * label (`label=`, `label==`, `label!=`, or `label!==`) - only remove volumes with (or without, in case `label!=...` is used) the specified labels. + + The `label` filter accepts two formats. One is the `label=...` (`label=` or `label==`), + which removes volumes with the specified labels. The other + format is the `label!=...` (`label!=` or `label!==`), which removes + volumes without the specified labels. deprecated: false min_api_version: "1.25" experimental: false diff --git a/_data/samples.yaml b/_data/samples.yaml index 91fc0d2a7d..1479632263 100644 --- a/_data/samples.yaml +++ b/_data/samples.yaml @@ -313,8 +313,8 @@ samples: - javascript - nginx - postgresql - - title: k8s-wordsmith-demo - url: https://github.com/dockersamples/k8s-wordsmith-demo + - title: wordsmith + url: https://github.com/dockersamples/wordsmith description: A demo app that runs three containers, including PostgreSQL, Java, and Go. dev_env: false services: diff --git a/_data/toc.yaml b/_data/toc.yaml index 1baf89e6c7..4fb01257a7 100644 --- a/_data/toc.yaml +++ b/_data/toc.yaml @@ -125,6 +125,8 @@ guides: path: /language/dotnet/run-containers/ - title: "Develop your app" path: /language/dotnet/develop/ + - title: "Run your tests" + path: /language/dotnet/run-tests/ - title: "Configure CI/CD" path: /language/dotnet/configure-ci-cd/ - title: "Deploy your app" @@ -844,7 +846,7 @@ reference: path: /docker-hub/api/deprecated/ - title: Registry API path: /registry/spec/api/ - - sectiontitle: Docker Extension SDK API (Beta) + - sectiontitle: Docker Extension SDK API section: - path: /desktop/extensions-sdk/dev/api/reference/interfaces/DesktopUI/ title: DesktopUI @@ -902,8 +904,6 @@ reference: title: Compose file build - path: /compose/compose-file/deploy/ title: Compose file deploy - - path: /compose/faq/ - title: Frequently asked questions - sectiontitle: Legacy versions section: - path: /compose/compose-file/compose-versioning/ @@ -1161,17 +1161,17 @@ manuals: title: Distribute your dev environment - path: /desktop/dev-environments/dev-cli/ title: Use the docker dev CLI plugin - - sectiontitle: Extensions (Beta) + - sectiontitle: Extensions section: - path: /desktop/extensions/ title: What are Docker Extensions? - path: /desktop/extensions/marketplace/ - title: Manage marketplace Extensions + title: Manage Marketplace extensions - path: /desktop/extensions/non-marketplace/ title: Manage non-Marketplace extensions - path: /desktop/extensions/settings-feedback/ - title: Change Settings and give feedback - - sectiontitle: Extensions SDK (Beta) + title: Change settings and give feedback + - sectiontitle: Extensions SDK section: - path: /desktop/extensions-sdk/ title: Overview @@ -1183,7 +1183,7 @@ manuals: section: - title: Create a simple extension path: /desktop/extensions-sdk/build/minimal-frontend-extension/ - - title: Create a more advanced frontend + - title: Create an advanced frontend extension path: /desktop/extensions-sdk/build/frontend-extension-tutorial/ - title: Add a backend to your extension path: /desktop/extensions-sdk/build/backend-extension-tutorial/ @@ -1645,6 +1645,18 @@ manuals: title: Build contexts and linking targets - path: /build/bake/compose-file/ title: Building from Compose file + - sectiontitle: Attestations + section: + - path: /build/attestations/ + title: Overview + - path: /build/attestations/sbom/ + title: SBOM + - path: /build/attestations/slsa-provenance/ + title: Provenance + - path: /build/attestations/slsa-definitions/ + title: SLSA definitions + - path: /build/attestations/attestation-storage/ + title: Attestation storage - sectiontitle: BuildKit section: - path: /build/buildkit/ @@ -1665,6 +1677,8 @@ manuals: title: Overview - path: /compose/features-uses/ title: Key features and use cases + - path: /compose/compose-v2/ + title: Evolution of Compose - sectiontitle: Install Docker Compose section: - path: /compose/install/ @@ -1677,12 +1691,7 @@ manuals: title: Uninstall Compose - path: /compose/gettingstarted/ title: Try Docker Compose - - sectiontitle: Compose V2 - section: - - path: /compose/compose-v2/ - title: Overview - - path: /compose/cli-command-compatibility/ - title: Compose v2 compatibility + - sectiontitle: Environment variables section: - path: /compose/environment-variables/ @@ -1705,6 +1714,8 @@ manuals: title: Control startup order - path: /compose/samples-for-compose/ title: Sample apps with Compose + - path: /compose/faq/ + title: FAQs - path: /compose/release-notes/ title: Release notes diff --git a/_includes/build-feature-state.md b/_includes/build-feature-state.md new file mode 100644 index 0000000000..2a1f01e222 --- /dev/null +++ b/_includes/build-feature-state.md @@ -0,0 +1,2 @@ +> This feature is supported in BuildKit version `{{ include.buildkit_v }}` +> and Buildx version `{{ include.buildx_v }}`. diff --git a/_includes/deploy.md b/_includes/deploy.md index 026e90452a..a67a3020fa 100644 --- a/_includes/deploy.md +++ b/_includes/deploy.md @@ -1,18 +1,18 @@ -Now, that we have configured a CI/CD pipleline, let's look at how we can deploy the application. Docker supports deploying containers on Azure ACI and AWS ECS. You can also deploy your application to Kubernetes if you have enabled Kubernetes in Docker Desktop. +Now that we have configured a CI/CD pipeline, let's look at how we can deploy the application. Docker supports deploying containers on Azure ACI and AWS ECS. You can also deploy your application to Kubernetes if you have enabled Kubernetes in Docker Desktop. ## Docker and Azure ACI -The Docker Azure Integration enables developers to use native Docker commands to run applications in Azure Container Instances (ACI) when building cloud-native applications. The new experience provides a tight integration between Docker Desktop and Microsoft Azure allowing developers to quickly run applications using the Docker CLI or VS Code extension, to switch seamlessly from local development to cloud deployment. +The Docker Azure Integration enables developers to use native Docker commands to run applications in Azure Container Instances (ACI) when building cloud-native applications. The new experience provides a tight integration between Docker Desktop and Microsoft Azure allowing developers to quickly run applications using the Docker CLI or VS Code extension to switch seamlessly from local development to cloud deployment. For detailed instructions, see [Deploying Docker containers on Azure](/cloud/aci-integration/). ## Docker and AWS ECS -The Docker ECS Integration enables developers to use native Docker commands in Docker Compose CLI to run applications in Amazon EC2 Container Service (ECS) when building cloud-native applications. +The Docker ECS Integration enables developers to use native Docker commands in the Docker Compose CLI to run applications in an Amazon EC2 Container Service (ECS) when building cloud-native applications. -The integration between Docker and Amazon ECS allows developers to use the Docker Compose CLI to set up an AWS context in one Docker command, allowing you to switch from a local context to a cloud context and run applications quickly and easily simplify multi-container application development on Amazon ECS using Compose files. +The integration between Docker and Amazon ECS allows developers to use the Docker Compose CLI to set up an AWS context in one Docker command, allowing them to switch from a local context to a cloud context and run applications quickly and easily to simplify multi-container application development on Amazon ECS using Compose files. For detailed instructions, see [Deploying Docker containers on ECS](/cloud/ecs-integration/). @@ -22,7 +22,7 @@ Docker Desktop includes a standalone Kubernetes server and client, as well as Do To enable Kubernetes: -1. From the Docker menu, select **Preferences** (**Settings** on Windows). +1. From the Docker menu, select **Settings**. 2. Select **Kubernetes** and click **Enable Kubernetes**. This starts a Kubernetes single-node cluster when Docker Desktop starts. diff --git a/_includes/desktop-install.html b/_includes/desktop-install.html index f3282e4241..555c4eb9f0 100644 --- a/_includes/desktop-install.html +++ b/_includes/desktop-install.html @@ -13,7 +13,7 @@ Download file

- Checksum: SHA-256 04dbd937971f1940e22f1edab9cad90722268b3f98feb77140535e1ac64606a8 + Checksum: SHA-256 20e4ba05b573610506b57a7f216115458019d2c002f18ef6d50a2419b7db545b @@ -31,7 +31,7 @@ Download file

- Checksum: SHA-256 bee41d646916e579b16b7fae014e2fb5e5e7b5dbaf7c1949821fd311d3ce430b + Checksum: SHA-256 22eecb8ea07f10892d81cde07d614fb8b342163106133a75c4280a8e28787643 @@ -49,7 +49,7 @@ Download file

- Checksum: SHA-256 fc8609d57fb8c8264122f581c0f66497e46e171f8027d85d90213527d6226362 + Checksum: SHA-256 838eabe6cc42fe7e4be2cdb4d73924c61fc7982366dac2a9467793845851cb2e @@ -64,10 +64,10 @@
- Download file + Download file

- Checksum: SHA-256 744266c6adef23e0823facded844f3b879fd0a988f8604f9b620d7585f249cf9 + Checksum: SHA-256 fa3023eb16c24dcbdc5f12021340e874d8399863e96c1a58091c9a41fd50fe58
@@ -82,10 +82,10 @@
- Download file + Download file

- Checksum: SHA-256 84e206c3e4742d37c7ef7d3d7440c5a085e1a4a77da2c628d133324a3f77f891 + Checksum: SHA-256 7f54f29a971b9ba456e7aef777d747867d7e4eccb7a2b47aa9092c99a990f8d5
@@ -100,10 +100,10 @@
- Download file + Download file

- Checksum: SHA-256 43156553268ccc8cb11eef08ac375c90af60ccdc65ae407bdf100ff2e50c6867 + Checksum: SHA-256 05e94709974e711bf81aa16845ebba976f8236a371432594c87a68ecf9a21d0f
diff --git a/_includes/desktop-update.md b/_includes/desktop-update.md index 66afae80f2..914739727e 100644 --- a/_includes/desktop-update.md +++ b/_includes/desktop-update.md @@ -1,6 +1,6 @@ -When an update is available, Docker Desktop displays an icon on the Docker menu to indicate the availability of a newer version. Additionally, the **Software Updates** section in **Settings** (**Preferences** on Mac) also notifies you of any updates available to Docker Desktop. You can choose to download the update right away, or click the **Release Notes** option to learn what's included in the updated version. +When an update is available, Docker Desktop displays an icon on the Docker menu to indicate the availability of a newer version. Additionally, the **Software Updates** section in **Settings** also notifies you of any updates available to Docker Desktop. You can choose to download the update right away, or click the **Release Notes** option to learn what's included in the updated version. Starting with Docker Desktop 4.2.0, the option to turn off the automatic check for updates is available for users on all Docker subscriptions, including Docker Personal and Docker Pro.. diff --git a/_includes/dev-envs-changing.md b/_includes/dev-envs-changing.md new file mode 100644 index 0000000000..823d42faf6 --- /dev/null +++ b/_includes/dev-envs-changing.md @@ -0,0 +1,6 @@ +> **Dev Environments is changing** +> +>We’re working hard to make Dev Environments work even better for you and your teams. In the coming months, we’ll be introducing a new vision for Dev Environments. +> +>In the mean time, it may take us longer to respond to requests for support. +{: .important} \ No newline at end of file diff --git a/_includes/eula-modal.html b/_includes/eula-modal.html index 3673066579..f00705cb2f 100644 --- a/_includes/eula-modal.html +++ b/_includes/eula-modal.html @@ -27,4 +27,4 @@ - + diff --git a/_includes/extensions-form.md b/_includes/extensions-form.md new file mode 100644 index 0000000000..75269467db --- /dev/null +++ b/_includes/extensions-form.md @@ -0,0 +1,3 @@ +> Already built an extension? +> +> Let us know about your experience using the [feedback form](https://docs.docker.com/feedback/extension/). \ No newline at end of file diff --git a/_includes/head.html b/_includes/head.html index 2fc71c8e40..4e448bd56a 100644 --- a/_includes/head.html +++ b/_includes/head.html @@ -69,6 +69,7 @@ + {%- endif -%} {%- if site.local_search -%} diff --git a/_includes/image-modal.html b/_includes/image-modal.html new file mode 100644 index 0000000000..099bd3ce51 --- /dev/null +++ b/_includes/image-modal.html @@ -0,0 +1,5 @@ +
+ × + / +
+
diff --git a/_includes/install-script.md b/_includes/install-script.md index c17f903211..4146fef790 100644 --- a/_includes/install-script.md +++ b/_includes/install-script.md @@ -34,12 +34,12 @@ of the convenience script: > Tip: preview script steps before running > -> You can run the script with the `DRY_RUN=1` option to learn what steps the +> You can run the script with the `--dry-run` option to learn what steps the > script will run when invoked: > > ```console > $ curl -fsSL https://get.docker.com -o get-docker.sh -> $ DRY_RUN=1 sudo sh ./get-docker.sh +> $ sudo sh ./get-docker.sh --dry-run > ``` This example downloads the script from diff --git a/_layouts/docs.html b/_layouts/docs.html index 64d85aed15..cca1d264e8 100644 --- a/_layouts/docs.html +++ b/_layouts/docs.html @@ -52,6 +52,8 @@ {%- assign my_min = page.toc_min | default: site.toc_min | default: 2 -%} {%- assign my_max = page.toc_max | default: site.toc_max | default: 3 -%} {%- assign my_name = page.url | default: "unnamed" -%} +
Contents:
+ {% include image-modal.html %}
Page details
    diff --git a/_redirects.yml b/_redirects.yml index a45ab0ae36..2b20baeada 100644 --- a/_redirects.yml +++ b/_redirects.yml @@ -550,3 +550,7 @@ "https://hub.docker.com/_/zookeeper/": - /samples/zookeeper - /samples/library/zookeeper + +# feedback +"https://docs.google.com/forms/d/e/1FAIpQLSenjK8KiBiOrwCpq06u_iVEZGv4tfTEpfmY_cQDmsqJrHL9Gw/viewform": + - /feedback/extension/ diff --git a/_releaser/Dockerfile b/_releaser/Dockerfile index cdd4e5edc4..752e258b8e 100644 --- a/_releaser/Dockerfile +++ b/_releaser/Dockerfile @@ -1,6 +1,6 @@ # syntax=docker/dockerfile:1 -ARG GO_VERSION=1.18 +ARG GO_VERSION=1.19 FROM scratch AS sitedir diff --git a/_releaser/go.mod b/_releaser/go.mod index 1906ecc37c..8dc22d5e0f 100644 --- a/_releaser/go.mod +++ b/_releaser/go.mod @@ -3,10 +3,10 @@ module github.com/docker/docs/_releaser go 1.18 require ( - github.com/alecthomas/kong v0.6.1 - github.com/aws/aws-sdk-go v1.44.56 - github.com/go-openapi/runtime v0.19.24 - github.com/go-openapi/strfmt v0.19.11 + github.com/alecthomas/kong v0.7.1 + github.com/aws/aws-sdk-go v1.44.180 + github.com/go-openapi/runtime v0.25.0 + github.com/go-openapi/strfmt v0.21.2 github.com/netlify/open-api v1.4.0 ) @@ -18,29 +18,34 @@ require ( github.com/Azure/go-autorest/tracing v0.5.0 // indirect github.com/PuerkitoBio/purell v1.1.1 // indirect github.com/PuerkitoBio/urlesc v0.0.0-20170810143723-de5bf2ad4578 // indirect - github.com/asaskevich/govalidator v0.0.0-20200907205600-7a23bdc65eef // indirect + github.com/asaskevich/govalidator v0.0.0-20210307081110-f21760c49a8d // indirect github.com/cenkalti/backoff/v4 v4.1.2 // indirect github.com/dgrijalva/jwt-go v3.2.0+incompatible // indirect - github.com/go-openapi/analysis v0.19.16 // indirect - github.com/go-openapi/errors v0.19.9 // indirect + github.com/go-logr/logr v1.2.3 // indirect + github.com/go-logr/stdr v1.2.2 // indirect + github.com/go-openapi/analysis v0.21.2 // indirect + github.com/go-openapi/errors v0.20.2 // indirect github.com/go-openapi/jsonpointer v0.19.5 // indirect - github.com/go-openapi/jsonreference v0.19.5 // indirect - github.com/go-openapi/loads v0.20.0 // indirect - github.com/go-openapi/spec v0.20.0 // indirect - github.com/go-openapi/swag v0.19.12 // indirect - github.com/go-openapi/validate v0.20.0 // indirect - github.com/go-stack/stack v1.8.0 // indirect - github.com/google/go-cmp v0.5.7 // indirect + github.com/go-openapi/jsonreference v0.19.6 // indirect + github.com/go-openapi/loads v0.21.1 // indirect + github.com/go-openapi/spec v0.20.4 // indirect + github.com/go-openapi/swag v0.21.1 // indirect + github.com/go-openapi/validate v0.21.0 // indirect + github.com/go-stack/stack v1.8.1 // indirect github.com/google/uuid v1.3.0 // indirect github.com/jmespath/go-jmespath v0.4.0 // indirect github.com/josharian/intern v1.0.0 // indirect - github.com/mailru/easyjson v0.7.6 // indirect - github.com/mitchellh/mapstructure v1.4.0 // indirect + github.com/mailru/easyjson v0.7.7 // indirect + github.com/mitchellh/mapstructure v1.4.3 // indirect + github.com/oklog/ulid v1.3.1 // indirect + github.com/opentracing/opentracing-go v1.2.0 // indirect github.com/rsc/goversion v1.2.0 // indirect github.com/sirupsen/logrus v1.8.1 // indirect - go.mongodb.org/mongo-driver v1.4.4 // indirect - golang.org/x/net v0.0.0-20220127200216-cd36cc0744dd // indirect - golang.org/x/sys v0.0.0-20220114195835-da31bd327af9 // indirect - golang.org/x/text v0.3.7 // indirect + go.mongodb.org/mongo-driver v1.8.3 // indirect + go.opentelemetry.io/otel v1.11.1 // indirect + go.opentelemetry.io/otel/trace v1.11.1 // indirect + golang.org/x/net v0.1.0 // indirect + golang.org/x/sys v0.1.0 // indirect + golang.org/x/text v0.4.0 // indirect gopkg.in/yaml.v2 v2.4.0 // indirect ) diff --git a/_releaser/go.sum b/_releaser/go.sum index a0a73f102a..0454e19859 100644 --- a/_releaser/go.sum +++ b/_releaser/go.sum @@ -25,10 +25,10 @@ github.com/PuerkitoBio/purell v1.1.1/go.mod h1:c11w/QuzBsJSee3cPx9rAFu61PvFxuPbt github.com/PuerkitoBio/urlesc v0.0.0-20170810143723-de5bf2ad4578 h1:d+Bc7a5rLufV/sSk/8dngufqelfh6jnri85riMAaF/M= github.com/PuerkitoBio/urlesc v0.0.0-20170810143723-de5bf2ad4578/go.mod h1:uGdkoq3SwY9Y+13GIhn11/XLaGBb4BfwItxLd5jeuXE= github.com/agnivade/levenshtein v1.0.1/go.mod h1:CURSv5d9Uaml+FovSIICkLbAUZ9S4RqaHDIsdSBg7lM= -github.com/alecthomas/kong v0.6.1 h1:1kNhcFepkR+HmasQpbiKDLylIL8yh5B5y1zPp5bJimA= -github.com/alecthomas/kong v0.6.1/go.mod h1:JfHWDzLmbh/puW6I3V7uWenoh56YNVONW+w8eKeUr9I= -github.com/alecthomas/repr v0.0.0-20210801044451-80ca428c5142 h1:8Uy0oSf5co/NZXje7U1z8Mpep++QJOldL2hs/sBQf48= -github.com/alecthomas/repr v0.0.0-20210801044451-80ca428c5142/go.mod h1:2kn6fqh/zIyPLmm3ugklbEi5hg5wS435eygvNfaDQL8= +github.com/alecthomas/assert/v2 v2.1.0 h1:tbredtNcQnoSd3QBhQWI7QZ3XHOVkw1Moklp2ojoH/0= +github.com/alecthomas/kong v0.7.1 h1:azoTh0IOfwlAX3qN9sHWTxACE2oV8Bg2gAwBsMwDQY4= +github.com/alecthomas/kong v0.7.1/go.mod h1:n1iCIO2xS46oE8ZfYCNDqdR0b0wZNrXAIAqro/2132U= +github.com/alecthomas/repr v0.1.0 h1:ENn2e1+J3k09gyj2shc0dHr/yjaWSHRlrJ4DPMevDqE= github.com/alecthomas/template v0.0.0-20160405071501-a0175ee3bccc/go.mod h1:LOuyumcjzFXgccqObfd/Ljyb9UuFJ6TxHnclSeseNhc= github.com/alecthomas/units v0.0.0-20151022065526-2efee857e7cf/go.mod h1:ybxpYRFXyAe+OPACYpWeL0wqObRcbAqCMya13uyzqw0= github.com/andreyvit/diff v0.0.0-20170406064948-c7f18ee00883/go.mod h1:rCTlJbsFo29Kk6CurOXKm700vrz8f0KW0JNfpkRJY/8= @@ -37,11 +37,12 @@ github.com/asaskevich/govalidator v0.0.0-20180720115003-f9ffefc3facf/go.mod h1:l github.com/asaskevich/govalidator v0.0.0-20190424111038-f61b66f89f4a/go.mod h1:lB+ZfQJz7igIIfQNfa7Ml4HSf2uFQQRzpGGRXenZAgY= github.com/asaskevich/govalidator v0.0.0-20200108200545-475eaeb16496/go.mod h1:oGkLhpf+kjZl6xBf758TQhh5XrAeiJv/7FRz/2spLIg= github.com/asaskevich/govalidator v0.0.0-20200428143746-21a406dcc535/go.mod h1:oGkLhpf+kjZl6xBf758TQhh5XrAeiJv/7FRz/2spLIg= -github.com/asaskevich/govalidator v0.0.0-20200907205600-7a23bdc65eef h1:46PFijGLmAjMPwCCCo7Jf0W6f9slllCkkv7vyc1yOSg= github.com/asaskevich/govalidator v0.0.0-20200907205600-7a23bdc65eef/go.mod h1:WaHUgvxTVq04UNunO+XhnAqY/wQc+bxr74GqbsZ/Jqw= +github.com/asaskevich/govalidator v0.0.0-20210307081110-f21760c49a8d h1:Byv0BzEl3/e6D5CLfI0j/7hiIEtvGVFPCZ7Ei2oq8iQ= +github.com/asaskevich/govalidator v0.0.0-20210307081110-f21760c49a8d/go.mod h1:WaHUgvxTVq04UNunO+XhnAqY/wQc+bxr74GqbsZ/Jqw= github.com/aws/aws-sdk-go v1.34.28/go.mod h1:H7NKnBqNVzoTJpGfLrQkkD+ytBA93eiDYi/+8rV9s48= -github.com/aws/aws-sdk-go v1.44.56 h1:bT+lExwagH7djxb6InKUVkEKGPAj5aAPnV85/m1fKro= -github.com/aws/aws-sdk-go v1.44.56/go.mod h1:y4AeaBuwd2Lk+GepC1E9v0qOiTws0MIWAX4oIKwKHZo= +github.com/aws/aws-sdk-go v1.44.180 h1:VLZuAHI9fa/3WME5JjpVjcPCNfpGHVMiHx8sLHWhMgI= +github.com/aws/aws-sdk-go v1.44.180/go.mod h1:aVsgQcEevwlmQ7qHE9I3h+dtQgpqhFB+i8Phjh7fkwI= github.com/beorn7/perks v0.0.0-20180321164747-3a771d992973/go.mod h1:Dwedo/Wpr24TaqPxmxbtue+5NUziq4I4S80YR8gNf3Q= github.com/beorn7/perks v1.0.0/go.mod h1:KWe93zE9D1o94FZ5RNwFwVgaQK1VOXiVxmqh+CedLV8= github.com/cenkalti/backoff/v4 v4.0.2/go.mod h1:eEew/i+1Q6OrCDZh3WiXYv3+nJwBASZ8Bog/87DQnVg= @@ -75,6 +76,11 @@ github.com/globalsign/mgo v0.0.0-20181015135952-eeefdecb41b8/go.mod h1:xkRDCp4j0 github.com/go-kit/kit v0.8.0/go.mod h1:xBxKIO96dXMWWy0MnWVtmwkA9/13aqxPnvrjFYMA2as= github.com/go-logfmt/logfmt v0.3.0/go.mod h1:Qt1PoO58o5twSAckw1HlFXLmHsOX5/0LbT9GBnD5lWE= github.com/go-logfmt/logfmt v0.4.0/go.mod h1:3RMwSq7FuexP4Kalkev3ejPJsZTpXXBr9+V4qmtdjCk= +github.com/go-logr/logr v1.2.2/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A= +github.com/go-logr/logr v1.2.3 h1:2DntVwHkVopvECVRSlL5PSo9eG+cAkDCuckLubN+rq0= +github.com/go-logr/logr v1.2.3/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A= +github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag= +github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE= github.com/go-openapi/analysis v0.0.0-20180825180245-b006789cd277/go.mod h1:k70tL6pCuVxPJOHXQ+wIac1FUrvNkHolPie/cLEU6hI= github.com/go-openapi/analysis v0.17.0/go.mod h1:IowGgpVeD0vNm45So8nr+IcQ3pxVtpRoBWb8PVZO0ik= github.com/go-openapi/analysis v0.18.0/go.mod h1:IowGgpVeD0vNm45So8nr+IcQ3pxVtpRoBWb8PVZO0ik= @@ -82,8 +88,9 @@ github.com/go-openapi/analysis v0.19.2/go.mod h1:3P1osvZa9jKjb8ed2TPng3f0i/UY9sn github.com/go-openapi/analysis v0.19.4/go.mod h1:3P1osvZa9jKjb8ed2TPng3f0i/UY9snX6gxi44djMjk= github.com/go-openapi/analysis v0.19.5/go.mod h1:hkEAkxagaIvIP7VTn8ygJNkd4kAYON2rCu0v0ObL0AU= github.com/go-openapi/analysis v0.19.10/go.mod h1:qmhS3VNFxBlquFJ0RGoDtylO9y4pgTAUNE9AEEMdlJQ= -github.com/go-openapi/analysis v0.19.16 h1:Ub9e++M8sDwtHD+S587TYi+6ANBG1NRYGZDihqk0SaY= github.com/go-openapi/analysis v0.19.16/go.mod h1:GLInF007N83Ad3m8a/CbQ5TPzdnGT7workfHwuVjNVk= +github.com/go-openapi/analysis v0.21.2 h1:hXFrOYFHUAMQdu6zwAiKKJHJQ8kqZs1ux/ru1P1wLJU= +github.com/go-openapi/analysis v0.21.2/go.mod h1:HZwRk4RRisyG8vx2Oe6aqeSQcoxRp47Xkp3+K6q+LdY= github.com/go-openapi/errors v0.17.0/go.mod h1:LcZQpmvG4wyF5j4IhA73wkLFQg+QJXOQHVjmcZxhka0= github.com/go-openapi/errors v0.18.0/go.mod h1:LcZQpmvG4wyF5j4IhA73wkLFQg+QJXOQHVjmcZxhka0= github.com/go-openapi/errors v0.19.2/go.mod h1:qX0BLWsyaKfvhluLejVpVNwNRdXZhEbTA4kxxpKBC94= @@ -92,8 +99,9 @@ github.com/go-openapi/errors v0.19.4/go.mod h1:qX0BLWsyaKfvhluLejVpVNwNRdXZhEbTA github.com/go-openapi/errors v0.19.6/go.mod h1:cM//ZKUKyO06HSwqAelJ5NsEMMcpa6VpXe8DOa1Mi1M= github.com/go-openapi/errors v0.19.7/go.mod h1:cM//ZKUKyO06HSwqAelJ5NsEMMcpa6VpXe8DOa1Mi1M= github.com/go-openapi/errors v0.19.8/go.mod h1:cM//ZKUKyO06HSwqAelJ5NsEMMcpa6VpXe8DOa1Mi1M= -github.com/go-openapi/errors v0.19.9 h1:9SnKdGhiPZHF3ttwFMiCBEb8jQ4IDdrK+5+a0oTygA4= github.com/go-openapi/errors v0.19.9/go.mod h1:cM//ZKUKyO06HSwqAelJ5NsEMMcpa6VpXe8DOa1Mi1M= +github.com/go-openapi/errors v0.20.2 h1:dxy7PGTqEh94zj2E3h1cUmQQWiM1+aeCROfAr02EmK8= +github.com/go-openapi/errors v0.20.2/go.mod h1:cM//ZKUKyO06HSwqAelJ5NsEMMcpa6VpXe8DOa1Mi1M= github.com/go-openapi/inflect v0.19.0/go.mod h1:lHpZVlpIQqLyKwJ4N+YSc9hchQy/i12fJykb83CRBH4= github.com/go-openapi/jsonpointer v0.17.0/go.mod h1:cOnomiV+CVVwFLk0A/MExoFMjwdsUdVpsRhURCKh+3M= github.com/go-openapi/jsonpointer v0.18.0/go.mod h1:cOnomiV+CVVwFLk0A/MExoFMjwdsUdVpsRhURCKh+3M= @@ -105,8 +113,9 @@ github.com/go-openapi/jsonreference v0.17.0/go.mod h1:g4xxGn04lDIRh0GJb5QlpE3Hfo github.com/go-openapi/jsonreference v0.18.0/go.mod h1:g4xxGn04lDIRh0GJb5QlpE3HfopLOL6uZrK/VgnsK9I= github.com/go-openapi/jsonreference v0.19.2/go.mod h1:jMjeRr2HHw6nAVajTXJ4eiUwohSTlpa0o73RUL1owJc= github.com/go-openapi/jsonreference v0.19.3/go.mod h1:rjx6GuL8TTa9VaixXglHmQmIL98+wF9xc8zWvFonSJ8= -github.com/go-openapi/jsonreference v0.19.5 h1:1WJP/wi4OjB4iV8KVbH73rQaoialJrqv8gitZLxGLtM= github.com/go-openapi/jsonreference v0.19.5/go.mod h1:RdybgQwPxbL4UEjuAruzK1x3nE69AqPYEJeo/TWfEeg= +github.com/go-openapi/jsonreference v0.19.6 h1:UBIxjkht+AWIgYzCDSv2GN+E/togfwXUJFRTWhl2Jjs= +github.com/go-openapi/jsonreference v0.19.6/go.mod h1:diGHMEHg2IqXZGKxqyvWdfWU/aim5Dprw5bqpKkTvns= github.com/go-openapi/loads v0.17.0/go.mod h1:72tmFy5wsWx89uEVddd0RjRWPZm92WRLhf7AC+0+OOU= github.com/go-openapi/loads v0.18.0/go.mod h1:72tmFy5wsWx89uEVddd0RjRWPZm92WRLhf7AC+0+OOU= github.com/go-openapi/loads v0.19.0/go.mod h1:72tmFy5wsWx89uEVddd0RjRWPZm92WRLhf7AC+0+OOU= @@ -116,16 +125,18 @@ github.com/go-openapi/loads v0.19.4/go.mod h1:zZVHonKd8DXyxyw4yfnVjPzBjIQcLt0CCs github.com/go-openapi/loads v0.19.5/go.mod h1:dswLCAdonkRufe/gSUC3gN8nTSaB9uaS2es0x5/IbjY= github.com/go-openapi/loads v0.19.6/go.mod h1:brCsvE6j8mnbmGBh103PT/QLHfbyDxA4hsKvYBNEGVc= github.com/go-openapi/loads v0.19.7/go.mod h1:brCsvE6j8mnbmGBh103PT/QLHfbyDxA4hsKvYBNEGVc= -github.com/go-openapi/loads v0.20.0 h1:Pymw1O8zDmWeNv4kVsHd0W3cvgdp8juRa4U/U/8D/Pk= github.com/go-openapi/loads v0.20.0/go.mod h1:2LhKquiE513rN5xC6Aan6lYOSddlL8Mp20AW9kpviM4= +github.com/go-openapi/loads v0.21.1 h1:Wb3nVZpdEzDTcly8S4HMkey6fjARRzb7iEaySimlDW0= +github.com/go-openapi/loads v0.21.1/go.mod h1:/DtAMXXneXFjbQMGEtbamCZb+4x7eGwkvZCvBmwUG+g= github.com/go-openapi/runtime v0.0.0-20180920151709-4f900dc2ade9/go.mod h1:6v9a6LTXWQCdL8k1AO3cvqx5OtZY/Y9wKTgaoP6YRfA= github.com/go-openapi/runtime v0.19.0/go.mod h1:OwNfisksmmaZse4+gpV3Ne9AyMOlP1lt4sK4FXt0O64= github.com/go-openapi/runtime v0.19.4/go.mod h1:X277bwSUBxVlCYR3r7xgZZGKVvBd/29gLDlFGtJ8NL4= github.com/go-openapi/runtime v0.19.12/go.mod h1:dhGWCTKRXlAfGnQG0ONViOZpjfg0m2gUt9nTQPQZuoo= github.com/go-openapi/runtime v0.19.15/go.mod h1:dhGWCTKRXlAfGnQG0ONViOZpjfg0m2gUt9nTQPQZuoo= github.com/go-openapi/runtime v0.19.16/go.mod h1:5P9104EJgYcizotuXhEuUrzVc+j1RiSjahULvYmlv98= -github.com/go-openapi/runtime v0.19.24 h1:TqagMVlRAOTwllE/7hNKx6rQ10O6T8ZzeJdMjSTKaD4= github.com/go-openapi/runtime v0.19.24/go.mod h1:Lm9YGCeecBnUUkFTxPC4s1+lwrkJ0pthx8YvyjCfkgk= +github.com/go-openapi/runtime v0.25.0 h1:7yQTCdRbWhX8vnIjdzU8S00tBYf7Sg71EBeorlPHvhc= +github.com/go-openapi/runtime v0.25.0/go.mod h1:Ux6fikcHXyyob6LNWxtE96hWwjBPYF0DXgVFuMTneOs= github.com/go-openapi/spec v0.17.0/go.mod h1:XkF/MOi14NmjsfZ8VtAKf8pIlbZzyoTvZsdfssdxcBI= github.com/go-openapi/spec v0.18.0/go.mod h1:XkF/MOi14NmjsfZ8VtAKf8pIlbZzyoTvZsdfssdxcBI= github.com/go-openapi/spec v0.19.2/go.mod h1:sCxk3jxKgioEJikev4fgkNmwS+3kuYdJtcsZsD5zxMY= @@ -134,8 +145,9 @@ github.com/go-openapi/spec v0.19.6/go.mod h1:Hm2Jr4jv8G1ciIAo+frC/Ft+rR2kQDh8JHK github.com/go-openapi/spec v0.19.7/go.mod h1:Hm2Jr4jv8G1ciIAo+frC/Ft+rR2kQDh8JHKHb3gWUSk= github.com/go-openapi/spec v0.19.8/go.mod h1:Hm2Jr4jv8G1ciIAo+frC/Ft+rR2kQDh8JHKHb3gWUSk= github.com/go-openapi/spec v0.19.15/go.mod h1:+81FIL1JwC5P3/Iuuozq3pPE9dXdIEGxFutcFKaVbmU= -github.com/go-openapi/spec v0.20.0 h1:HGLc8AJ7ynOxwv0Lq4TsnwLsWMawHAYiJIFzbcML86I= github.com/go-openapi/spec v0.20.0/go.mod h1:+81FIL1JwC5P3/Iuuozq3pPE9dXdIEGxFutcFKaVbmU= +github.com/go-openapi/spec v0.20.4 h1:O8hJrt0UMnhHcluhIdUgCLRWyM2x7QkBXRvOs7m+O1M= +github.com/go-openapi/spec v0.20.4/go.mod h1:faYFR1CvsJZ0mNsmsphTMSoRrNV3TEDoAM7FOEWeq8I= github.com/go-openapi/strfmt v0.17.0/go.mod h1:P82hnJI0CXkErkXi8IKjPbNBM6lV6+5pLP5l494TcyU= github.com/go-openapi/strfmt v0.18.0/go.mod h1:P82hnJI0CXkErkXi8IKjPbNBM6lV6+5pLP5l494TcyU= github.com/go-openapi/strfmt v0.19.0/go.mod h1:+uW+93UVvGGq2qGaZxdDeJqSAqBqBdl+ZPMF/cC8nDY= @@ -143,8 +155,11 @@ github.com/go-openapi/strfmt v0.19.2/go.mod h1:0yX7dbo8mKIvc3XSKp7MNfxw4JytCfCD6 github.com/go-openapi/strfmt v0.19.3/go.mod h1:0yX7dbo8mKIvc3XSKp7MNfxw4JytCfCD6+bY1AVL9LU= github.com/go-openapi/strfmt v0.19.4/go.mod h1:eftuHTlB/dI8Uq8JJOyRlieZf+WkkxUuk0dgdHXr2Qk= github.com/go-openapi/strfmt v0.19.5/go.mod h1:eftuHTlB/dI8Uq8JJOyRlieZf+WkkxUuk0dgdHXr2Qk= -github.com/go-openapi/strfmt v0.19.11 h1:0+YvbNh05rmBkgztd6zHp4OCFn7Mtu30bn46NQo2ZRw= github.com/go-openapi/strfmt v0.19.11/go.mod h1:UukAYgTaQfqJuAFlNxxMWNvMYiwiXtLsF2VwmoFtbtc= +github.com/go-openapi/strfmt v0.21.0/go.mod h1:ZRQ409bWMj+SOgXofQAGTIo2Ebu72Gs+WaRADcS5iNg= +github.com/go-openapi/strfmt v0.21.1/go.mod h1:I/XVKeLc5+MM5oPNN7P6urMOpuLXEcNrCX/rPGuWb0k= +github.com/go-openapi/strfmt v0.21.2 h1:5NDNgadiX1Vhemth/TH4gCGopWSTdDjxl60H3B7f+os= +github.com/go-openapi/strfmt v0.21.2/go.mod h1:I/XVKeLc5+MM5oPNN7P6urMOpuLXEcNrCX/rPGuWb0k= github.com/go-openapi/swag v0.17.0/go.mod h1:AByQ+nYG6gQg71GINrmuDXCPWdL640yX49/kXLo40Tg= github.com/go-openapi/swag v0.18.0/go.mod h1:AByQ+nYG6gQg71GINrmuDXCPWdL640yX49/kXLo40Tg= github.com/go-openapi/swag v0.19.2/go.mod h1:POnQmlKehdgb5mhVOsnJFsivZCEZ/vjK9gh66Z9tfKk= @@ -152,8 +167,10 @@ github.com/go-openapi/swag v0.19.5/go.mod h1:POnQmlKehdgb5mhVOsnJFsivZCEZ/vjK9gh github.com/go-openapi/swag v0.19.7/go.mod h1:ao+8BpOPyKdpQz3AOJfbeEVpLmWAvlT1IfTe5McPyhY= github.com/go-openapi/swag v0.19.8/go.mod h1:ao+8BpOPyKdpQz3AOJfbeEVpLmWAvlT1IfTe5McPyhY= github.com/go-openapi/swag v0.19.9/go.mod h1:ao+8BpOPyKdpQz3AOJfbeEVpLmWAvlT1IfTe5McPyhY= -github.com/go-openapi/swag v0.19.12 h1:Bc0bnY2c3AoF7Gc+IMIAQQsD8fLHjHpc19wXvYuayQI= github.com/go-openapi/swag v0.19.12/go.mod h1:eFdyEBkTdoAf/9RXBvj4cr1nH7GD8Kzo5HTt47gr72M= +github.com/go-openapi/swag v0.19.15/go.mod h1:QYRuS/SOXUCsnplDa677K7+DxSOj6IPNl/eQntq43wQ= +github.com/go-openapi/swag v0.21.1 h1:wm0rhTb5z7qpJRHBdPOMuY4QjVUMbF6/kwoYeRAOrKU= +github.com/go-openapi/swag v0.21.1/go.mod h1:QYRuS/SOXUCsnplDa677K7+DxSOj6IPNl/eQntq43wQ= github.com/go-openapi/validate v0.18.0/go.mod h1:Uh4HdOzKt19xGIGm1qHf/ofbX1YQ4Y+MYsct2VUrAJ4= github.com/go-openapi/validate v0.19.2/go.mod h1:1tRCw7m3jtI8eNWEEliiAqUIcBztB2KDnRCRMUi7GTA= github.com/go-openapi/validate v0.19.3/go.mod h1:90Vh6jjkTn+OT1Eefm0ZixWNFjhtOH7vS9k0lo6zwJo= @@ -161,11 +178,13 @@ github.com/go-openapi/validate v0.19.7/go.mod h1:8DJv2CVJQ6kGNpFW6eV9N3JviE1C85n github.com/go-openapi/validate v0.19.10/go.mod h1:RKEZTUWDkxKQxN2jDT7ZnZi2bhZlbNMAuKvKB+IaGx8= github.com/go-openapi/validate v0.19.12/go.mod h1:Rzou8hA/CBw8donlS6WNEUQupNvUZ0waH08tGe6kAQ4= github.com/go-openapi/validate v0.19.15/go.mod h1:tbn/fdOwYHgrhPBzidZfJC2MIVvs9GA7monOmWBbeCI= -github.com/go-openapi/validate v0.20.0 h1:pzutNCCBZGZlE+u8HD3JZyWdc/TVbtVwlWUp8/vgUKk= github.com/go-openapi/validate v0.20.0/go.mod h1:b60iJT+xNNLfaQJUqLI7946tYiFEOuE9E4k54HpKcJ0= +github.com/go-openapi/validate v0.21.0 h1:+Wqk39yKOhfpLqNLEC0/eViCkzM5FVXVqrvt526+wcI= +github.com/go-openapi/validate v0.21.0/go.mod h1:rjnrwK57VJ7A8xqfpAOEKRH8yQSGUriMu5/zuPSQ1hg= github.com/go-sql-driver/mysql v1.5.0/go.mod h1:DCzpHaOWr8IXmIStZouvnhqoel9Qv2LBy8hT2VhHyBg= -github.com/go-stack/stack v1.8.0 h1:5SgMzNM5HxrEjV0ww2lTmX6E2Izsfxas4+YHWRs3Lsk= github.com/go-stack/stack v1.8.0/go.mod h1:v0f6uXyyMGvRgIKkXu+yp6POWl0qKG85gN/melR3HDY= +github.com/go-stack/stack v1.8.1 h1:ntEHSVwIt7PNXNpgPmVfMrNhLtgjlmnZha2kOpuRiDw= +github.com/go-stack/stack v1.8.1/go.mod h1:dcoOX6HbPZSZptuspn9bctJ+N/CnF5gGygcUP3XYfe4= github.com/go-swagger/go-swagger v0.23.0/go.mod h1:5AaV4Dx69cUjpFRTZnSHPr1Y7dKBVk6SvfIvkTEqwJs= github.com/go-swagger/scan-repo-boundary v0.0.0-20180623220736-973b3573c013/go.mod h1:b65mBPzqzZWxOZGxSWrqs4GInLIn+u99Q9q7p+GKni0= github.com/gobuffalo/attrs v0.0.0-20190224210810-a9411de4debd/go.mod h1:4duuawTqi2wkkpB4ePgWMaai6/Kc6WEz83bhFwpHzj0= @@ -206,8 +225,7 @@ github.com/google/go-cmp v0.2.0/go.mod h1:oXzfMopK8JAjlY9xF4vHSVASa0yLyX7SntLO5a github.com/google/go-cmp v0.3.0/go.mod h1:8QqcDgzrUqlUb/G2PQTWiueGozuR1884gddMywk6iLU= github.com/google/go-cmp v0.3.1/go.mod h1:8QqcDgzrUqlUb/G2PQTWiueGozuR1884gddMywk6iLU= github.com/google/go-cmp v0.5.2/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= -github.com/google/go-cmp v0.5.7 h1:81/ik6ipDQS2aGcBfIN5dHDB36BwrStyeAQquSYCV4o= -github.com/google/go-cmp v0.5.7/go.mod h1:n+brtR0CgQNWTVd5ZUFpTBC8YFBDLK/h/bpaJ8/DtOE= +github.com/google/go-cmp v0.5.9 h1:O2Tfq5qg4qc4AmwVlvv0oLiVAGB7enBSJ2x2DqQFi38= github.com/google/uuid v1.0.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo= github.com/google/uuid v1.1.1/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo= github.com/google/uuid v1.3.0 h1:t6JiXgmwXMjEs8VusXIJk2BXHsn+wx8BZdTaoZ5fu7I= @@ -219,6 +237,7 @@ github.com/grpc-ecosystem/go-grpc-middleware v1.0.0/go.mod h1:FiyG127CGDf3tlThmg github.com/grpc-ecosystem/go-grpc-prometheus v1.2.0/go.mod h1:8NvIoxWQoOIhqOTXgfV/d3M/q6VIi02HzZEHgUlZvzk= github.com/grpc-ecosystem/grpc-gateway v1.9.0/go.mod h1:vNeuVxBJEsws4ogUvrchl83t/GYV9WGTSLVdBhOQFDY= github.com/hashicorp/hcl v1.0.0/go.mod h1:E5yfLk+7swimpb2L/Alb/PJmXilQ/rhwaUYs4T20WEQ= +github.com/hexops/gotextdiff v1.0.3 h1:gitA9+qJrrTCsiCl7+kh75nPqQt1cx4ZkudSTLoUqJM= github.com/inconshreveable/mousetrap v1.0.0/go.mod h1:PxqpIevigyE2G7u3NXJIT2ANytuPF1OarO4DADm73n8= github.com/jessevdk/go-flags v1.4.0/go.mod h1:4FA24M0QyGHXBuZZK/XkWh8h0e1EYbRYJSGM75WSRxI= github.com/jmespath/go-jmespath v0.4.0 h1:BEgLn5cpjn8UN1mAw4NjwDrS35OdebyEtFe+9YPoQUg= @@ -237,6 +256,7 @@ github.com/kisielk/errcheck v1.1.0/go.mod h1:EZBBE59ingxPouuu3KfxchcWSUPOHkagtvW github.com/kisielk/errcheck v1.2.0/go.mod h1:/BMXB+zMLi60iA8Vv6Ksmxu/1UDYcXs4uQLJ+jE2L00= github.com/kisielk/gotool v1.0.0/go.mod h1:XhKaO+MFFWcvkIS/tQcRk01m1F5IRFswLeQ+oQHNcck= github.com/klauspost/compress v1.9.5/go.mod h1:RyIbtBH6LamlWaDj8nUwkbUhJ87Yi3uG0guNDohfE1A= +github.com/klauspost/compress v1.13.6/go.mod h1:/3/Vjq9QcHkK5uEr5lBEmyoZ1iFhe47etQ6QUkpK6sk= github.com/konsorten/go-windows-terminal-sequences v1.0.1/go.mod h1:T0+1ngSBFLxvqU3pZ+m/2kptfBszLMUkC4ZK/EgS/cQ= github.com/konsorten/go-windows-terminal-sequences v1.0.2/go.mod h1:T0+1ngSBFLxvqU3pZ+m/2kptfBszLMUkC4ZK/EgS/cQ= github.com/konsorten/go-windows-terminal-sequences v1.0.3/go.mod h1:T0+1ngSBFLxvqU3pZ+m/2kptfBszLMUkC4ZK/EgS/cQ= @@ -257,8 +277,9 @@ github.com/mailru/easyjson v0.0.0-20190614124828-94de47d64c63/go.mod h1:C1wdFJiN github.com/mailru/easyjson v0.0.0-20190626092158-b2ccc519800e/go.mod h1:C1wdFJiN94OJF2b5HbByQZoLdCWB1Yqtg26g4irojpc= github.com/mailru/easyjson v0.7.0/go.mod h1:KAzv3t3aY1NaHWoQz1+4F1ccyAH66Jk7yos7ldAVICs= github.com/mailru/easyjson v0.7.1/go.mod h1:KAzv3t3aY1NaHWoQz1+4F1ccyAH66Jk7yos7ldAVICs= -github.com/mailru/easyjson v0.7.6 h1:8yTIVnZgCoiM1TgqoeTl+LfU5Jg6/xL3QhGQnimLYnA= github.com/mailru/easyjson v0.7.6/go.mod h1:xzfreul335JAWq5oZzymOObrkdz5UnU4kGfJJLY9Nlc= +github.com/mailru/easyjson v0.7.7 h1:UGYAvKxe3sBsEDzO8ZeWOSlIQfWFlxbzLZe7hwFURr0= +github.com/mailru/easyjson v0.7.7/go.mod h1:xzfreul335JAWq5oZzymOObrkdz5UnU4kGfJJLY9Nlc= github.com/markbates/oncer v0.0.0-20181203154359-bf2de49a0be2/go.mod h1:Ld9puTsIW75CHf65OeIOkyKbteujpZVXDpWK6YGZbxE= github.com/markbates/safe v1.0.1/go.mod h1:nAqgmRi7cY2nqMc92/bSEeQA+R4OheNU2T1kNSCBdG0= github.com/mattn/go-isatty v0.0.0-20170925054904-a5cdd64afdee/go.mod h1:M+lRXTBqGeGNdLjl/ufCoiOlB5xdOkqRJdNxMWT7Zi4= @@ -266,8 +287,10 @@ github.com/matttproud/golang_protobuf_extensions v1.0.1/go.mod h1:D8He9yQNgCq6Z5 github.com/mitchellh/mapstructure v1.1.2/go.mod h1:FVVH3fgwuzCH5S8UJGiWEs2h04kUh9fWfEaFds41c1Y= github.com/mitchellh/mapstructure v1.3.2/go.mod h1:bFUtVrKA4DC2yAKiSyO/QUcy7e+RRV2QTWOzhPopBRo= github.com/mitchellh/mapstructure v1.3.3/go.mod h1:bFUtVrKA4DC2yAKiSyO/QUcy7e+RRV2QTWOzhPopBRo= -github.com/mitchellh/mapstructure v1.4.0 h1:7ks8ZkOP5/ujthUsT07rNv+nkLXCQWKNHuwzOAesEks= github.com/mitchellh/mapstructure v1.4.0/go.mod h1:bFUtVrKA4DC2yAKiSyO/QUcy7e+RRV2QTWOzhPopBRo= +github.com/mitchellh/mapstructure v1.4.1/go.mod h1:bFUtVrKA4DC2yAKiSyO/QUcy7e+RRV2QTWOzhPopBRo= +github.com/mitchellh/mapstructure v1.4.3 h1:OVowDSCllw/YjdLkam3/sm7wEtOy59d8ndGgCcyj8cs= +github.com/mitchellh/mapstructure v1.4.3/go.mod h1:bFUtVrKA4DC2yAKiSyO/QUcy7e+RRV2QTWOzhPopBRo= github.com/montanaflynn/stats v0.0.0-20171201202039-1bf9dbcd8cbe/go.mod h1:wL8QJuTMNUDYhXwkmfOly8iTdp5TEcJFWZD2D7SIkUc= github.com/morikuni/aec v0.0.0-20170113033406-39771216ff4c/go.mod h1:BbKIizmSmc5MMPqRYbxO4ZU0S0+P200+tUnFx7PXmsc= github.com/mwitkow/go-conntrack v0.0.0-20161129095857-cc309e4a2223/go.mod h1:qRWi+5nqEBWmkhHvq77mSJWrCKwh8bxhgT7d/eI7P4U= @@ -276,7 +299,10 @@ github.com/netlify/open-api v1.4.0 h1:/P+6sG53/EILEeQkMIi29gjqk8AJZZGtvBMMerWefK github.com/netlify/open-api v1.4.0/go.mod h1:/fPwbOj5ZSaMiTZPzuxf3g4gV/29x344DZyualypq04= github.com/niemeyer/pretty v0.0.0-20200227124842-a10e7caefd8e h1:fD57ERR4JtEqsWbfPhv4DMiApHyliiK5xCTNVSPiaAs= github.com/niemeyer/pretty v0.0.0-20200227124842-a10e7caefd8e/go.mod h1:zD1mROLANZcx1PVRCS0qkT7pwLkGfwJo4zjcN/Tysno= +github.com/oklog/ulid v1.3.1 h1:EGfNDEx6MqHz8B3uNV6QAib1UR2Lm97sHi3ocA6ESJ4= github.com/oklog/ulid v1.3.1/go.mod h1:CirwcVhetQ6Lv90oh/F+FBtV6XMibvdAFo93nm5qn4U= +github.com/opentracing/opentracing-go v1.2.0 h1:uEJPy/1a5RIPAJ0Ov+OIO8OxWu77jEv+1B0VhjKrZUs= +github.com/opentracing/opentracing-go v1.2.0/go.mod h1:GxEUsuufX4nBwe+T+Wl9TAgYrxe9dPLANfrWvHYVTgc= github.com/pborman/uuid v1.2.0/go.mod h1:X/NO0urCmaxf9VXbdlT7C2Yzkj2IKimNn4k+gtPdI/k= github.com/pelletier/go-toml v1.2.0/go.mod h1:5z9KED0ma1S8pY6P1sdut58dfprrGBbd/94hg7ilaic= github.com/pelletier/go-toml v1.4.0/go.mod h1:PN7xzY2wHTK0K9p34ErDQMlFxa51Fk0OUruD3k1mMwo= @@ -334,8 +360,8 @@ github.com/stretchr/testify v1.2.2/go.mod h1:a8OnRcib4nhh0OaRAV+Yts87kKdq0PP7pXf github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI= github.com/stretchr/testify v1.4.0/go.mod h1:j7eGeouHqKxXV5pUuKE4zz7dFj8WfuZ+81PSLYec5m4= github.com/stretchr/testify v1.6.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg= -github.com/stretchr/testify v1.7.2 h1:4jaiDzPyXQvSd7D0EjG45355tLlV3VOECpq10pLC+8s= -github.com/stretchr/testify v1.7.2/go.mod h1:R6va5+xMeoiuVRoj+gSkQ7d3FALtqAAGI1FQKckRals= +github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg= +github.com/stretchr/testify v1.8.0 h1:pSgiaMZlXftHpm5L7V1+rVB+AZJydKsMxsQBIJw4PKk= github.com/subosito/gotenv v1.2.0/go.mod h1:N0PQaV/YGNqwC0u51sEeR/aUtSLEXKX9iv69rRypqCw= github.com/tidwall/pretty v1.0.0 h1:HsD+QiTn7sK6flMKIvNmpqz1qrpP3Ps6jOKIKMooyg4= github.com/tidwall/pretty v1.0.0/go.mod h1:XNkn88O1ChpSDQmQeStsy+sBenx6DDtFZJxhVysOjyk= @@ -345,11 +371,16 @@ github.com/ugorji/go v1.1.4/go.mod h1:uQMGLiO92mf5W77hV/PUCpI3pbzQx3CRekS0kk+RGr github.com/urfave/cli v1.20.0/go.mod h1:70zkFmudgCuE/ngEzBv17Jvp/497gISqfk5gWijbERA= github.com/vektah/gqlparser v1.1.2/go.mod h1:1ycwN7Ij5njmMkPPAOaRFY4rET2Enx7IkVv3vaXspKw= github.com/wacul/ptr v0.0.0-20170209030335-91632201dfc8/go.mod h1:BD0gjsZrCwtoR+yWDB9v2hQ8STlq9tT84qKfa+3txOc= +github.com/xdg-go/pbkdf2 v1.0.0/go.mod h1:jrpuAogTd400dnrH08LKmI/xc1MbPOebTwRqcT5RDeI= +github.com/xdg-go/scram v1.0.2/go.mod h1:1WAq6h33pAW+iRreB34OORO2Nf7qel3VV3fjBj+hCSs= +github.com/xdg-go/stringprep v1.0.2/go.mod h1:8F9zXuvzgwmyT5DUm4GUfZGDdT3W+LCvS6+da4O5kxM= github.com/xdg/scram v0.0.0-20180814205039-7eeb5667e42c/go.mod h1:lB8K/P019DLNhemzwFU4jHLhdvlE6uDZjXFejJXr49I= github.com/xdg/stringprep v0.0.0-20180714160509-73f8eece6fdc/go.mod h1:Jhud4/sHMO4oL310DaZAKk9ZaJ08SJfe+sJh0HrGL1Y= github.com/xiang90/probing v0.0.0-20190116061207-43a291ad63a2/go.mod h1:UETIi67q53MR2AWcXfiuqkDkRtnGDLqkBTpCHuJHxtU= github.com/xordataexchange/crypt v0.0.3-0.20170626215501-b2862e3d0a77/go.mod h1:aYKd//L2LvnjZzWKhF00oedf4jCCReLcmhLdhm1A27Q= +github.com/youmark/pkcs8 v0.0.0-20181117223130-1be2e3e5546d/go.mod h1:rHwXgn7JulP+udvsHwJoVG1YGAP6VLg4y9I5dyZdqmA= github.com/yuin/goldmark v1.1.25/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74= +github.com/yuin/goldmark v1.4.13/go.mod h1:6yULJ656Px+3vBD8DxQVa3kxgyrAnzto9xy5taEt/CY= go.etcd.io/bbolt v1.3.2/go.mod h1:IbVyRI1SCnLcuJnV2u8VeU0CEYM7e686BmAb1XKL+uU= go.mongodb.org/mongo-driver v1.0.3/go.mod h1:u7ryQJ+DOzQmeO7zB6MHyr8jkEQvC8vH7qLUO4lqsUM= go.mongodb.org/mongo-driver v1.1.1/go.mod h1:u7ryQJ+DOzQmeO7zB6MHyr8jkEQvC8vH7qLUO4lqsUM= @@ -358,8 +389,16 @@ go.mongodb.org/mongo-driver v1.3.0/go.mod h1:MSWZXKOynuguX+JSvwP8i+58jYCXxbia8HS go.mongodb.org/mongo-driver v1.3.1/go.mod h1:MSWZXKOynuguX+JSvwP8i+58jYCXxbia8HS3gZBapIE= go.mongodb.org/mongo-driver v1.3.4/go.mod h1:MSWZXKOynuguX+JSvwP8i+58jYCXxbia8HS3gZBapIE= go.mongodb.org/mongo-driver v1.4.3/go.mod h1:WcMNYLx/IlOxLe6JRJiv2uXuCz6zBLndR4SoGjYphSc= -go.mongodb.org/mongo-driver v1.4.4 h1:bsPHfODES+/yx2PCWzUYMH8xj6PVniPI8DQrsJuSXSs= go.mongodb.org/mongo-driver v1.4.4/go.mod h1:WcMNYLx/IlOxLe6JRJiv2uXuCz6zBLndR4SoGjYphSc= +go.mongodb.org/mongo-driver v1.7.3/go.mod h1:NqaYOwnXWr5Pm7AOpO5QFxKJ503nbMse/R79oO62zWg= +go.mongodb.org/mongo-driver v1.7.5/go.mod h1:VXEWRZ6URJIkUq2SCAyapmhH0ZLRBP+FT4xhp5Zvxng= +go.mongodb.org/mongo-driver v1.8.3 h1:TDKlTkGDKm9kkJVUOAXDK5/fkqKHJVwYQSpoRfB43R4= +go.mongodb.org/mongo-driver v1.8.3/go.mod h1:0sQWfOeY63QTntERDJJ/0SuKK0T1uVSgKCuAROlKEPY= +go.opentelemetry.io/otel v1.11.1 h1:4WLLAmcfkmDk2ukNXJyq3/kiz/3UzCaYq6PskJsaou4= +go.opentelemetry.io/otel v1.11.1/go.mod h1:1nNhXBbWSD0nsL38H6btgnFN2k4i0sNLHNNMZMSbUGE= +go.opentelemetry.io/otel/sdk v1.11.1 h1:F7KmQgoHljhUuJyA+9BiU+EkJfyX5nVVF4wyzWZpKxs= +go.opentelemetry.io/otel/trace v1.11.1 h1:ofxdnzsNrGBYXbP7t7zpUK281+go5rF7dvdIZXF8gdQ= +go.opentelemetry.io/otel/trace v1.11.1/go.mod h1:f/Q9G7vzk5u91PhbmKbg1Qn0rzH1LJ4vbPHFGkTPtOk= go.uber.org/atomic v1.4.0/go.mod h1:gD2HeocX3+yG+ygLZcrzQJaqmWj9AIm7n08wl/qW/PE= go.uber.org/multierr v1.1.0/go.mod h1:wR5kodmAFQ0UK8QlbwjlSNy0Z68gJhDJUG5sjR94q/0= go.uber.org/zap v1.10.0/go.mod h1:vwi/ZaCAaUcBkycHslxD9B2zi4UTXhF60s6SWpuDF0Q= @@ -372,11 +411,15 @@ golang.org/x/crypto v0.0.0-20190611184440-5c40567a22f8/go.mod h1:yigFU9vqHzYiE8U golang.org/x/crypto v0.0.0-20190617133340-57b3e21c3d56/go.mod h1:yigFU9vqHzYiE8UmvKecakEJjdnWj3jj499lnFckfCI= golang.org/x/crypto v0.0.0-20191011191535-87dc89f01550/go.mod h1:yigFU9vqHzYiE8UmvKecakEJjdnWj3jj499lnFckfCI= golang.org/x/crypto v0.0.0-20191206172530-e9b2fee46413/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto= +golang.org/x/crypto v0.0.0-20200302210943-78000ba7a073/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto= golang.org/x/crypto v0.0.0-20200311171314-f7b00557c8c4/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto= golang.org/x/crypto v0.0.0-20200622213623-75b288015ac9/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto= +golang.org/x/crypto v0.0.0-20201216223049-8b5274cf687f/go.mod h1:jdWPYTVW3xRLrWPugEBEK3UY2ZEsg3UU495nc5E+M+I= +golang.org/x/crypto v0.0.0-20210921155107-089bfa567519/go.mod h1:GvvjBRRGRdwPK5ydBHafDWAxML/pGHZbMvKqRZ5+Abc= golang.org/x/lint v0.0.0-20181026193005-c67002cb31c3/go.mod h1:UVdnD1Gm6xHRNCYTkRU2/jEulfH38KcIWyp/GAMgvoE= golang.org/x/lint v0.0.0-20190313153728-d0100b6bd8b3/go.mod h1:6SW0HCj/g11FgYtHlgUYUwCkIfeOF89ocIRzGO/8vkc= golang.org/x/mod v0.2.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA= +golang.org/x/mod v0.6.0-dev.0.20220419223038-86c51ed26bb4/go.mod h1:jJ57K6gSWd91VN4djpZkiMVwK6gcyfeH4XE8wZrZaV4= golang.org/x/net v0.0.0-20180404174746-b3c676e531a6/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4= golang.org/x/net v0.0.0-20180724234803-3673e40ba225/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4= golang.org/x/net v0.0.0-20180826012351-8a410e7b638d/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4= @@ -399,8 +442,11 @@ golang.org/x/net v0.0.0-20200602114024-627f9648deb9/go.mod h1:qpuaurCH72eLCgpAm/ golang.org/x/net v0.0.0-20201110031124-69a78807bb2b/go.mod h1:sp8m0HH+o8qH0wwXwYZr8TS3Oi6o0r6Gce1SSxlDquU= golang.org/x/net v0.0.0-20201202161906-c7110b5ffcbb/go.mod h1:sp8m0HH+o8qH0wwXwYZr8TS3Oi6o0r6Gce1SSxlDquU= golang.org/x/net v0.0.0-20201224014010-6772e930b67b/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg= -golang.org/x/net v0.0.0-20220127200216-cd36cc0744dd h1:O7DYs+zxREGLKzKoMQrtrEacpb0ZVXA5rIwylE2Xchk= -golang.org/x/net v0.0.0-20220127200216-cd36cc0744dd/go.mod h1:CfG3xpIq0wQ8r1q4Su4UZFWDARRcnwPjda9FqA0JpMk= +golang.org/x/net v0.0.0-20210226172049-e18ecbb05110/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg= +golang.org/x/net v0.0.0-20210421230115-4e50805a0758/go.mod h1:72T/g9IO56b78aLF+1Kcs5dz7/ng1VjMUvfKvpfy+jM= +golang.org/x/net v0.0.0-20220722155237-a158d28d115b/go.mod h1:XRhObCWvk6IyKnWLug+ECip1KBveYUHfp+8e9klMJ9c= +golang.org/x/net v0.1.0 h1:hZ/3BUoy5aId7sCpA/Tc5lt8DkFgdVS2onTpJsZ/fl0= +golang.org/x/net v0.1.0/go.mod h1:Cx3nUiGt4eDBEyega/BKRp+/AlGL8hYe7U9odMt2Cco= golang.org/x/oauth2 v0.0.0-20180821212333-d2e6202438be/go.mod h1:N/0e6XlmueqKjAGxoOufVs8QHGRruUQn6yWY3a++T0U= golang.org/x/oauth2 v0.0.0-20200107190931-bf48bf16ab8d/go.mod h1:gOpvHmFTYa4IltrdGE7lF6nIHvwfUNPOp7c8zoXwtLw= golang.org/x/sync v0.0.0-20180314180146-1d60e4601c6f/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM= @@ -410,6 +456,7 @@ golang.org/x/sync v0.0.0-20190227155943-e225da77a7e6/go.mod h1:RxMgew5VJxzue5/jJ golang.org/x/sync v0.0.0-20190412183630-56d357773e84/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM= golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM= golang.org/x/sync v0.0.0-20190911185100-cd5d95a43a6e/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM= +golang.org/x/sync v0.0.0-20220722155255-886fb9371eb4/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM= golang.org/x/sys v0.0.0-20170927054621-314a259e304f/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY= golang.org/x/sys v0.0.0-20180830151530-49385e6e1522/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY= golang.org/x/sys v0.0.0-20180905080454-ebe1bf3edb33/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY= @@ -429,18 +476,25 @@ golang.org/x/sys v0.0.0-20200302150141-5c8b2ff67527/go.mod h1:h1NjWce9XRLGQEsW7w golang.org/x/sys v0.0.0-20200323222414-85ca7c5b95cd/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= golang.org/x/sys v0.0.0-20200930185726-fdedc70b468f/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= +golang.org/x/sys v0.0.0-20210420072515-93ed5bcd2bfe/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= golang.org/x/sys v0.0.0-20210615035016-665e8c7367d1/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= -golang.org/x/sys v0.0.0-20211216021012-1d35b9e2eb4e/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= -golang.org/x/sys v0.0.0-20220114195835-da31bd327af9 h1:XfKQ4OlFl8okEOr5UvAqFRVj8pY/4yfcXrddB8qAbU0= -golang.org/x/sys v0.0.0-20220114195835-da31bd327af9/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= +golang.org/x/sys v0.0.0-20220520151302-bc2c85ada10a/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= +golang.org/x/sys v0.0.0-20220722155257-8c9f86f7a55f/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= +golang.org/x/sys v0.1.0 h1:kunALQeHf1/185U1i0GOB/fy1IPRDDpuoOOqRReG57U= +golang.org/x/sys v0.1.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= +golang.org/x/term v0.0.0-20201117132131-f5c789dd3221/go.mod h1:Nr5EML6q2oocZ2LXRh80K7BxOlk5/8JxuGnuhpl+muw= golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo= golang.org/x/term v0.0.0-20210927222741-03fcf44c2211/go.mod h1:jbD1KX2456YbFQfuXm/mYQcufACuNUgVhRMnK/tPxf8= +golang.org/x/term v0.1.0/go.mod h1:jbD1KX2456YbFQfuXm/mYQcufACuNUgVhRMnK/tPxf8= golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ= golang.org/x/text v0.3.2/go.mod h1:bEr9sfX3Q8Zfm5fL9x+3itogRgK3+ptLWKqgva+5dAk= golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ= golang.org/x/text v0.3.4/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ= -golang.org/x/text v0.3.7 h1:olpwvP2KacW1ZWvsR7uQhoyTYvKAupfQrRGBFM352Gk= +golang.org/x/text v0.3.5/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ= +golang.org/x/text v0.3.6/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ= golang.org/x/text v0.3.7/go.mod h1:u+2+/6zg+i71rQMx5EYifcz6MCKuco9NR6JIITiCfzQ= +golang.org/x/text v0.4.0 h1:BrVqGRd7+k1DiOgtnFvAkoQEWQvBc25ouMJM6429SFg= +golang.org/x/text v0.4.0/go.mod h1:mrYo+phRRbMaCq/xk9113O4dZlRixOauAjOtrjsXDZ8= golang.org/x/time v0.0.0-20190308202827-9d24e82272b4/go.mod h1:tRJNPiyCQ0inRvYxbN9jk5I+vvW/OXSQhTDSoE431IQ= golang.org/x/tools v0.0.0-20180221164845-07fd8470d635/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ= golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ= @@ -457,6 +511,7 @@ golang.org/x/tools v0.0.0-20190614205625-5aca471b1d59/go.mod h1:/rFqwRUd4F7ZHNgw golang.org/x/tools v0.0.0-20190617190820-da514acc4774/go.mod h1:/rFqwRUd4F7ZHNgwSSTFct+R/Kf4OFW1sUzUTQQTgfc= golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo= golang.org/x/tools v0.0.0-20200313205530-4303120df7d8/go.mod h1:Sl4aGygMT6LrqrWclx+PTx3U+LnKx/seiNR+3G19Ar8= +golang.org/x/tools v0.1.12/go.mod h1:hNGJHUnrk76NpqgfD5Aqm5Crs+Hm0VOH/i9J2+nxYbc= golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0= golang.org/x/xerrors v0.0.0-20191011141410-1b5146add898/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0= golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0= @@ -487,6 +542,6 @@ gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ= gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= gopkg.in/yaml.v3 v3.0.0-20200605160147-a5ece683394c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= gopkg.in/yaml.v3 v3.0.0-20200615113413-eeeca48fe776/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= +gopkg.in/yaml.v3 v3.0.0-20210107192922-496545a6307b/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA= -gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= honnef.co/go/tools v0.0.0-20190102054323-c2f93a96b099/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4= diff --git a/_scss/_content.scss b/_scss/_content.scss index 225ef9595f..31d4fe889b 100755 --- a/_scss/_content.scss +++ b/_scss/_content.scss @@ -124,3 +124,83 @@ a.glossary { a.accept-eula { font-weight: bold; } + +/* Style the Image Used to Trigger the Modal */ +main img { + border-radius: 5px; + cursor: pointer; + transition: 0.3s; +} + +main img:hover {opacity: 0.7;} + +/* The Modal (background) */ +.modal1 { + display: none; /* Hidden by default */ + position: fixed; /* Stay in place */ + z-index: 1; /* Sit on top */ + padding-top: 100px; /* Location of the box */ + left: 0; + top: 0; + width: 100%; /* Full width */ + height: 100%; /* Full height */ + overflow: auto; /* Enable scroll if needed */ + background-color: rgb(0,0,0); /* Fallback color */ + background-color: rgba(0,0,0,0.9); /* Black w/ opacity */ +} + +/* Modal Content (Image) */ +.modal-content1 { + margin: auto; + display: block; + width: 90%; + top:20px; +} + +/* Caption of Modal Image (Image Text) - Same Width as the Image */ +#img-modal-caption1 { + margin: 15px auto; + display: block; + width: 80%; + max-width: 700px; + text-align: center; + color: #ccc; + padding: 10px 0; + height: 150px; +} + +/* Add Animation - Zoom in the Modal */ +.modal-content1, #img-modal-caption1 { + animation-name: zoom; + animation-duration: 0.6s; +} + +@keyframes zoom { + from {transform:scale(0)} + to {transform:scale(1)} +} + +/* The Close Button */ +#img-modal-close1 { + font-size: 40px; + font-weight: bold; + color: #f1f1f1; + transition: 0.3s; + margin-right: 10px; +} + +#img-modal-close1:hover, +#img-modal-close1:focus { + color: #bbb; + text-decoration: none; + cursor: pointer; +} + +/* 100% Image Width on Smaller Screens */ +@media only screen and (max-width: 700px){ + .modal-content { + width: 100%; + } +} + + diff --git a/assets/images/authentication.svg b/assets/images/authentication.svg new file mode 100644 index 0000000000..5b000f4a6f --- /dev/null +++ b/assets/images/authentication.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/assets/images/compose-cli.svg b/assets/images/compose-cli.svg new file mode 100644 index 0000000000..f31c2423ac --- /dev/null +++ b/assets/images/compose-cli.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/assets/images/data.svg b/assets/images/data.svg new file mode 100644 index 0000000000..49c2ae2476 --- /dev/null +++ b/assets/images/data.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/assets/images/engine-api.svg b/assets/images/engine-api.svg new file mode 100644 index 0000000000..67a9cedd6b --- /dev/null +++ b/assets/images/engine-api.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/assets/images/image.svg b/assets/images/image.svg new file mode 100644 index 0000000000..b6a4658b0d --- /dev/null +++ b/assets/images/image.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/assets/images/manage.svg b/assets/images/manage.svg new file mode 100644 index 0000000000..4aa4b3ba31 --- /dev/null +++ b/assets/images/manage.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/assets/images/storage.svg b/assets/images/storage.svg new file mode 100644 index 0000000000..316a26ffab --- /dev/null +++ b/assets/images/storage.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/assets/images/terminal.svg b/assets/images/terminal.svg new file mode 100644 index 0000000000..b0934ac363 --- /dev/null +++ b/assets/images/terminal.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/assets/js/modal.js b/assets/js/modal.js new file mode 100644 index 0000000000..33afd06066 --- /dev/null +++ b/assets/js/modal.js @@ -0,0 +1,31 @@ +// Get the modal for image 1 +var modal = document.getElementById("img-modal1"); + +// Get the image and insert it inside the modal - use its "alt" text as a caption +const images = document.querySelectorAll("main img"); +var modalImg = document.getElementById("img-modal-img1"); +var captionText = document.getElementById("img-modal-caption1"); +function handleImageClick(event) { + modal.style.display = "block"; + modalImg.src = event.target.src; + modalImg.alt = event.target.alt; + captionText.innerHTML = event.target.alt; + window.addEventListener("keydown", handleModalClose) +} +images.forEach(image => image.addEventListener("click", handleImageClick)) + + +// Get the element that closes the modal +var span = document.getElementById("img-modal-close1"); +function handleModalClose(event) { + if (event.type==="click"||event.key==="Escape"){ + modal.style.display = "none" + window.removeEventListener("keydown", handleModalClose) + } +} +modal.addEventListener("click", handleModalClose) + +// When the user clicks on (x), close the modal +span.onclick = function(){ + modal.style.display = "none"; +} diff --git a/atomist/get-started.md b/atomist/get-started.md index 25f60c9a09..8512376d95 100644 --- a/atomist/get-started.md +++ b/atomist/get-started.md @@ -81,7 +81,7 @@ with the appropriate condition on the IAM role statement. > this stack requires a capability. This stack creates a role that will grant > Atomist read-only access to ECR resources. > - > ![confirm](./images/ecr/capability.png) + > ![Confirm read-only access to ECR resources](./images/ecr/capability.png)
    @@ -185,7 +185,7 @@ with the appropriate condition on the IAM role statement. Atomist tests the connection with your ECR registry. A green check mark displays beside the integration if a successful connection is made. - ![integration list showing a successful ECR integration](./images/ecr/connection-successful.png){: + ![Integration list showing a successful ECR integration](./images/ecr/connection-successful.png){: width="700px"} diff --git a/atomist/integrate/github.md b/atomist/integrate/github.md index d5a3b213d7..34c7a1b680 100644 --- a/atomist/integrate/github.md +++ b/atomist/integrate/github.md @@ -24,7 +24,7 @@ repositories for your Docker images. the [Atomist GitHub App](https://github.com/apps/atomist "Atomist GitHub App"){: target="blank" rel="noopener" class=""}. - ![install the GitHub app](images/gh-install.png){: width="700px" } + ![Install the GitHub app view](images/gh-install.png){: width="700px" } 4. Install the app. @@ -39,7 +39,7 @@ repositories for your Docker images. 5. In the repository selection menu, select what repositories you want Atomist to start watching. - ![activate repositories](images/activate-repos.png){: width="500px" } + ![Activate repositories view](images/activate-repos.png){: width="500px" } If you are just looking to evaluate Atomist, start by selecting a few repositories during evaluation. Once you are comfortable using Atomist, you diff --git a/atomist/try-atomist.md b/atomist/try-atomist.md index d52247255f..4c6982239f 100644 --- a/atomist/try-atomist.md +++ b/atomist/try-atomist.md @@ -77,12 +77,12 @@ rel="noopener" class=""}. target="blank" rel="noopener" class=""}, where you should see the image in the list. - ![indexed image in the image overview list](./images/images-overview.png){: + ![Indexed image in the image overview list](./images/images-overview.png){: width="700px"} 6. Select the image name. This gets you to the list of image tags. - ![list of image tags](./images/tags-list.png){: width="700px"} + ![List of image tags](./images/tags-list.png){: width="700px"} Since this is your first time indexing this image, the list only has one tag for now. When you integrate Atomist with your container registry, images and @@ -90,7 +90,7 @@ rel="noopener" class=""}. 7. Select the tag name. This shows you the insights for this tag. - ![vulnerability breakdown view](./images/vulnerabilities-overview.png){: + ![Vulnerability breakdown view](./images/vulnerabilities-overview.png){: width="700px"} In this view, you can see how many vulnerabilities this image has, their diff --git a/build/attestations/attestation-storage.md b/build/attestations/attestation-storage.md new file mode 100644 index 0000000000..199c61879c --- /dev/null +++ b/build/attestations/attestation-storage.md @@ -0,0 +1,8 @@ +--- +title: Attestation storage +description: "How SBOM and provenance attestations are stored for images." +keywords: build, attestations, sbom, provenance, storage, manifest +fetch_remote: + line_start: 2 + line_end: -1 +--- diff --git a/build/attestations/index.md b/build/attestations/index.md new file mode 100644 index 0000000000..adc34dd7fa --- /dev/null +++ b/build/attestations/index.md @@ -0,0 +1,149 @@ +--- +title: Build attestations +keywords: build, attestations, sbom, provenance +description: > + Introduction to SBOM and provenance attestations with Docker Build; what they + are and why they exist +--- + +{% include build-feature-state.md buildkit_v=">=0.11" buildx_v=">=0.10" %} + +Build attestations describe how an image was built, and what it contains. The +attestations are created at build-time by BuildKit, and become attached to the +final image as metadata. + +The purpose of attestations is to make it possible to inspect an image and see +where it comes from, who created it and how, and what it contains. This enables +you to make informed decisions about how an image impacts the supply chain security +of your application. It also enables the use of policy engines for validating +images based on policy rules you've defined. + +Two types of build annotations are available: + +- Software Bill of Material (SBOM): list of software artifacts that an image + contains, or that were used to build the image. +- Provenance: how an image was built. + +## Purpose of attestations + +The use of open source and third-party packages is more widespread than ever +before. Developers share and reuse code because it helps increase productivity, +allowing teams to create better products, faster. + +Importing and using code created elsewhere without vetting it introduces a +severe security risk. Even if you do review the software that you consume, new +zero-day vulnerabilities are frequently discovered, requiring development teams +take action to remediate them. + +Build attestations make it easier to see the contents of an image, and where it +comes from. Use attestations to analyze and decide whether to use an image, or +to see if images you are already using are exposed to vulnerabilities. + +## Creating attestations + +When you build an image with `docker buildx build`, you can add attestation +records to the resulting image using the `--provenance` and `--sbom` options. +You can opt in to add either the SBOM or provenance attestation type, or both. + +```console +$ docker buildx build --sbom=true --provenance=true . +``` + +BuildKit generates the attestations when building the image. The attestation +records are wrapped in the in-toto JSON format and attached it to the image +index in a manifest for the final image. + +## Storage + + +BuildKit produces attestations in the +[in-toto format](https://github.com/in-toto/attestation){: target="blank" rel="noopener" class="\_" }, +as defined by the +[in-toto framework](https://in-toto.io/){: target="blank" rel="noopener" class="\_" }, +a standard supported by the Linux Foundation. + +Attestations attach to images as a manifest in the image index. The data records +of the attestations are stored as JSON blobs. + +Because attestations attach to images as a manifest, it means that you can +inspect the attestations for any image in a registry without having to pull the +whole image. + +All BuildKit exporters support attestations. The `local` and `tar` can't save +the attestations to an image manifest, since it's outputting a directory of +files or a tarball, not an image. Instead, these exporters write the +attestations to one or more JSON files in the root directory of the export. + +The following example shows a truncated in-toto JSON representation of an SBOM +attestation. + +```json +{ + "_type": "https://in-toto.io/Statement/v0.1", + "predicateType": "https://spdx.dev/Document", + "subject": [ + { + "name": "pkg:docker//@?platform=", + "digest": { + "sha256": "e8275b2b76280af67e26f068e5d585eb905f8dfd2f1918b3229db98133cb4862" + } + } + ], + "predicate": { + "SPDXID": "SPDXRef-DOCUMENT", + "creationInfo": { + "created": "2022-12-15T11:47:54.546747383Z", + "creators": ["Organization: Anchore, Inc", "Tool: syft-v0.60.3"], + "licenseListVersion": "3.18" + }, + "dataLicense": "CC0-1.0", + "documentNamespace": "https://anchore.com/syft/dir/run/src/core-da0f600b-7f0a-4de0-8432-f83703e6bc4f", + "name": "/run/src/core", + // list of files that the image contains, e.g.: + "files": [ + { + "SPDXID": "SPDXRef-1ac501c94e2f9f81", + "comment": "layerID: sha256:9b18e9b68314027565b90ff6189d65942c0f7986da80df008b8431276885218e", + "fileName": "/bin/busybox", + "licenseConcluded": "NOASSERTION" + } + ], + // list of packages that were identified for this image: + "packages": [ + { + "name": "busybox", + "originator": "Person: Sören Tempel ", + "sourceInfo": "acquired package info from APK DB: lib/apk/db/installed", + "versionInfo": "1.35.0-r17", + "SPDXID": "SPDXRef-980737451f148c56", + "description": "Size optimized toolbox of many common UNIX utilities", + "downloadLocation": "https://busybox.net/", + "licenseConcluded": "GPL-2.0-only", + "licenseDeclared": "GPL-2.0-only" + // ... + } + ], + // files-packages relationship + "relationships": [ + { + "relatedSpdxElement": "SPDXRef-1ac501c94e2f9f81", + "relationshipType": "CONTAINS", + "spdxElementId": "SPDXRef-980737451f148c56" + }, + ... + ], + "spdxVersion": "SPDX-2.2" + } +} +``` + + +To deep-dive into the specifics about how attestations are stored, see +[Image Attestation Storage (BuildKit)](https://github.com/moby/buildkit/blob/master/docs/attestation-storage.md){: target="blank" rel="noopener" class="_"}. + +## What's next + +Learn more about the available attestation types and how to use them: + +- [Provenance](slsa-provenance.md) +- [SBOM](sbom.md) diff --git a/build/attestations/sbom.md b/build/attestations/sbom.md new file mode 100644 index 0000000000..187eab0469 --- /dev/null +++ b/build/attestations/sbom.md @@ -0,0 +1,326 @@ +--- +title: SBOM attestations +keywords: build, attestations, sbom +description: SBOM build attestations +--- + +{% include build-feature-state.md buildkit_v=">=0.11" buildx_v=">=0.10" %} + +Software Bill of Materials (SBOM) attestations describe what software artifacts +an image contains, and artifacts used to create the image. Metadata included in +an SBOM for describing software artifacts may include: + +- Name of the artifact +- Version +- License type +- Authors +- Unique package identifier + +There are benefits to indexing contents of an image during the build, as opposed +to scanning a final image. When scanning happens as part of the build, you're +able to detect software you use to build the image, that may not show up in the +final image. + +The SBOMs generated by BuildKit follow the SPDX standard. SBOMs attach to the +final image as a JSON-encoded SPDX document, using the format defined by the +[in-toto SPDX predicate](https://github.com/in-toto/attestation/blob/main/spec/predicates/spdx.md){: +target="blank" rel="noopener" }. + +## Create SBOM attestations + +To create a provenance attestation, pass the `--attest type=sbom` option to the +`docker buildx build` command: + +```console +$ docker buildx build --tag /: \ + --attest type=sbom --push . +``` + +Alternatively, you can use the shorthand `--sbom=true` option instead of `--attest type=sbom`. + +## Verify SBOM attestations + +Always validate the generated SBOM for your image before you push your image to a registry. + +To validate, you can build the image using the `local` exporter. +Building with the `local` exporter saves the build result to your local filesystem instead of creating an image. +Attestations are written to a JSON file in the root directory of your export. + +```console +$ docker buildx build \ + --sbom=true \ + --output type=local,dest=out . +``` + +The SBOM file appears in the root directory of the output, named `sbom.spdx.json`: + +```console +$ ls -1 ./out | grep sbom +sbom.spdx.json +``` + +## Arguments + +By default, BuildKit only scans the final stage of an image. The resulting SBOM +doesn't include build-time dependencies installed in earlier stages, or that +exist in the build context. This may cause you to overlook vulnerabilities in +those dependencies, which could impact the security of your final build +artifacts. + +For instance, you might use [multi-stage builds](../building/multi-stage.md), +with a `FROM scratch` stanza for your final stage to achieve a smaller image size. + +```dockerfile +FROM alpine AS build +# build the software ... + +FROM scratch +COPY --from=build /path/to/bin /bin +ENTRYPOINT [ "/bin" ] +``` + +Scanning the resulting image built using this Dockerfile example would not +reveal build-time dependencies used in the `build` stage. + +To include build-time dependencies from your Dockerfile, you can set the build +arguments `BUILDKIT_SBOM_SCAN_CONTEXT` and `BUILDKIT_SBOM_SCAN_STAGE`. This +expands the scanning scope to include the build context and additional stages. + +You can set the arguments as global arguments (after declaring the Dockerfile +syntax directive, before the first `FROM` command) or individually in each +stage. If set globally, the value propagates to each stage in the Dockerfile. + +The `BUILDKIT_SBOM_SCAN_CONTEXT` and `BUILDKIT_SBOM_SCAN_STAGE` build arguments +are special values. You can't perform variable substitution using these +arguments, and you can't set them using environment variables from within the +Dockerfile. The only way to set these values is using explicit `ARG` command in +the Dockerfile. + +### Scan build context + +To scan the build context, set the `BUILDKIT_SBOM_SCAN_CONTEXT` to `true`. + +```dockerfile +# syntax=docker/dockerfile:1 +ARG BUILDKIT_SBOM_SCAN_CONTEXT=true +FROM alpine AS build +# ... +``` + +You can use the `--build-arg` CLI option to override the value specified in the +Dockerfile. + +```console +$ docker buildx build --tag : \ + --attest type=sbom \ + --build-arg BUILDKIT_SBOM_SCAN_CONTEXT=false . +``` + +Note that passing the option as a CLI argument only, without having declared it +using `ARG` in the Dockerfile, will have no effect. You must specify the `ARG` +in the Dockerfile, whereby you can override the context scanning behavior using +`--build-arg`. + +### Scan stages + +To scan more than just the final stage, set the `BUILDKIT_SBOM_SCAN_STAGE` +argument to true, either globally or in the specific stages that you want to +scan. The following table demonstrates the different possible settings for this +argument. + +| Value | Description | +| ----------------------------------- | ------------------------------------------------------ | +| `BUILDKIT_SBOM_SCAN_STAGE=true` | Enables scanning for the current stage | +| `BUILDKIT_SBOM_SCAN_STAGE=false` | Disables scanning for the current stage | +| `BUILDKIT_SBOM_SCAN_STAGE=base,bin` | Enables scanning for the stages named `base` and `bin` | + +Only stages that are built will be scanned. Stages that aren't dependencies of +the target stage won't be built, or scanned. + +The following Dockerfile example uses multi-stage builds to build a static website with +[Hugo](https://gohugo.io/){: target="blank" rel="noopener" class="_"}. + +```dockerfile +# syntax=docker/dockerfile:1 +FROM alpine as hugo +ARG BUILDKIT_SBOM_SCAN_STAGE=true +WORKDIR /src +COPY </: \ + --format "{{ json .SBOM.SPDX }}" +{ + "SPDXID": "SPDXRef-DOCUMENT", + ... +} +``` +{% endraw %} + +You can also construct more complex expressions using the full functionality +of Go templates. For example, you can list all the installed packages and their +version identifiers: + +{% raw %} +```console +$ docker buildx imagetools inspect /: \ + --format "{{ range .SBOM.SPDX.packages }}{{ .name }}@{{ .versionInfo }}{{ println }}{{ end }}" +adduser@3.118ubuntu2 +apt@2.0.9 +base-files@11ubuntu5.6 +base-passwd@3.5.47 +... +``` +{% endraw %} + +## SBOM generator + +BuildKit generates the SBOM using a scanner plugin. By default, it uses is the +[BuildKit Syft scanner](https://github.com/docker/buildkit-syft-scanner){: target="blank" rel="noopener" } +plugin. This plugin is built on top of +[Anchore's Syft](https://github.com/anchore/syft){: target="blank" rel="noopener" }, +an open source tool for generating an SBOM. + +You can select a different plugin to use with the `generator` option, specifying +an image that implements the +[BuildKit SBOM scanner protocol](https://github.com/moby/buildkit/blob/master/docs/sbom-protocol.md){: target="blank" rel="noopener" }. + +```console +$ docker buildx build --attest type=sbom,generator= . +``` + +## SBOM attestation example + +The following JSON example shows what an SBOM attestation might look like. + +```json +{ + "_type": "https://in-toto.io/Statement/v0.1", + "predicateType": "https://spdx.dev/Document", + "subject": [ + { + "name": "pkg:docker//@?platform=", + "digest": { + "sha256": "e8275b2b76280af67e26f068e5d585eb905f8dfd2f1918b3229db98133cb4862" + } + } + ], + "predicate": { + "SPDXID": "SPDXRef-DOCUMENT", + "creationInfo": { + "created": "2022-12-16T15:27:25.517047753Z", + "creators": ["Organization: Anchore, Inc", "Tool: syft-v0.60.3"], + "licenseListVersion": "3.18" + }, + "dataLicense": "CC0-1.0", + "documentNamespace": "https://anchore.com/syft/dir/run/src/core/sbom-cba61a72-fa95-4b60-b63f-03169eac25ca", + "name": "/run/src/core/sbom", + "packages": [ + { + "SPDXID": "SPDXRef-b074348b8f56ea64", + "downloadLocation": "NOASSERTION", + "externalRefs": [ + { + "referenceCategory": "SECURITY", + "referenceLocator": "cpe:2.3:a:org:repo:\\(devel\\):*:*:*:*:*:*:*", + "referenceType": "cpe23Type" + }, + { + "referenceCategory": "PACKAGE_MANAGER", + "referenceLocator": "pkg:golang/github.com/org/repo@(devel)", + "referenceType": "purl" + } + ], + "filesAnalyzed": false, + "licenseConcluded": "NONE", + "licenseDeclared": "NONE", + "name": "github.com/org/repo", + "sourceInfo": "acquired package info from go module information: bin/server", + "versionInfo": "(devel)" + }, + { + "SPDXID": "SPDXRef-1b96f57f8fed62d8", + "checksums": [ + { + "algorithm": "SHA256", + "checksumValue": "0c13f1f3c1636491f716c2027c301f21f9dbed7c4a2185461ba94e3e58443408" + } + ], + "downloadLocation": "NOASSERTION", + "externalRefs": [ + { + "referenceCategory": "SECURITY", + "referenceLocator": "cpe:2.3:a:go-chi:chi\\/v5:v5.0.0:*:*:*:*:*:*:*", + "referenceType": "cpe23Type" + }, + { + "referenceCategory": "SECURITY", + "referenceLocator": "cpe:2.3:a:go_chi:chi\\/v5:v5.0.0:*:*:*:*:*:*:*", + "referenceType": "cpe23Type" + }, + { + "referenceCategory": "SECURITY", + "referenceLocator": "cpe:2.3:a:go:chi\\/v5:v5.0.0:*:*:*:*:*:*:*", + "referenceType": "cpe23Type" + }, + { + "referenceCategory": "PACKAGE_MANAGER", + "referenceLocator": "pkg:golang/github.com/go-chi/chi/v5@v5.0.0", + "referenceType": "purl" + } + ], + "filesAnalyzed": false, + "licenseConcluded": "NONE", + "licenseDeclared": "NONE", + "name": "github.com/go-chi/chi/v5", + "sourceInfo": "acquired package info from go module information: bin/server", + "versionInfo": "v5.0.0" + } + ], + "relationships": [ + { + "relatedSpdxElement": "SPDXRef-1b96f57f8fed62d8", + "relationshipType": "CONTAINS", + "spdxElementId": "SPDXRef-043f7360d3c66bc31ba45388f16423aa58693289126421b71d884145f8837fe1" + }, + { + "relatedSpdxElement": "SPDXRef-b074348b8f56ea64", + "relationshipType": "CONTAINS", + "spdxElementId": "SPDXRef-043f7360d3c66bc31ba45388f16423aa58693289126421b71d884145f8837fe1" + } + ], + "spdxVersion": "SPDX-2.2" + } +} +``` diff --git a/build/attestations/slsa-definitions.md b/build/attestations/slsa-definitions.md new file mode 100644 index 0000000000..1cdd304d7d --- /dev/null +++ b/build/attestations/slsa-definitions.md @@ -0,0 +1,8 @@ +--- +title: SLSA definitions +description: "How BuildKit populates the fields in the SLSA provenance attestations." +keywords: build, attestations, provenance, slsa, definitions, reference +fetch_remote: + line_start: 2 + line_end: -1 +--- diff --git a/build/attestations/slsa-provenance.md b/build/attestations/slsa-provenance.md new file mode 100644 index 0000000000..ea76c2f4fe --- /dev/null +++ b/build/attestations/slsa-provenance.md @@ -0,0 +1,352 @@ +--- +title: Provenance attestations +keywords: build, attestations, provenance, slsa +description: Provenance build attestations +--- + +{% include build-feature-state.md buildkit_v=">=0.11" buildx_v=">=0.10" %} + +The provenance attestations include facts about the build process, including +details such as: + +- Build timestamps +- Build parameters and environment +- Version control metadata +- Source code details +- Materials (files, scripts) consumed during the build + +Provenance attestations follow the +[SLSA provenance schema, version 0.2](https://slsa.dev/provenance/v0.2#schema). + +For more information about how BuildKit populates these provenance properties, refer to +[SLSA definitions](slsa-definitions.md). + +## Create provenance attestations + +To create a provenance attestation, pass the `--attest type=provenance` option +to the `docker buildx build` command: + +```console +$ docker buildx build --tag /: \ + --attest type=provenance,mode=[min,max] . +``` + +Alternatively, you can use the shorthand `--provenance=true` option instead of `--attest type=provenance`. +To specify the `mode` parameter using the shorthand option, use: `--provenance=mode=max`. + +## Mode + +You can use the `mode` parameter to define the level of detail to be included in +the provenance attestation. Supported values are `mode=min`, and `mode=max` +(default). + +### Min + +In `min` mode, the provenance attestations include a minimal set of information, +such as: + +- Build timestamps +- The frontend used +- Build materials +- Source repository and revision +- Build platform +- Reproducibility + +Values of build arguments, the identities of secrets, and rich layer metadata is +not included `mode=min`. The `min`-level provenance is safe to use for all +builds, as it doesn't leak information from any part of the build environment. + +The following JSON example shows the information included in a provenance +attestations created using the `min` mode: + +```json +{ + "_type": "https://in-toto.io/Statement/v0.1", + "predicateType": "https://slsa.dev/provenance/v0.2", + "subject": [ + { + "name": "pkg:docker//@?platform=", + "digest": { + "sha256": "e8275b2b76280af67e26f068e5d585eb905f8dfd2f1918b3229db98133cb4862" + } + } + ], + "predicate": { + "builder": { "id": "" }, + "buildType": "https://mobyproject.org/buildkit@v1", + "materials": [ + { + "uri": "pkg:docker/docker/dockerfile@1", + "digest": { + "sha256": "9ba7531bd80fb0a858632727cf7a112fbfd19b17e94c4e84ced81e24ef1a0dbc" + } + }, + { + "uri": "pkg:docker/golang@1.19.4-alpine?platform=linux%2Farm64", + "digest": { + "sha256": "a9b24b67dc83b3383d22a14941c2b2b2ca6a103d805cac6820fd1355943beaf1" + } + } + ], + "invocation": { + "configSource": { "entryPoint": "Dockerfile" }, + "parameters": { + "frontend": "gateway.v0", + "args": { + "cmdline": "docker/dockerfile:1", + "source": "docker/dockerfile:1", + "target": "binaries" + }, + "locals": [{ "name": "context" }, { "name": "dockerfile" }] + }, + "environment": { "platform": "linux/arm64" } + }, + "metadata": { + "buildInvocationID": "c4a87v0sxhliuewig10gnsb6v", + "buildStartedOn": "2022-12-16T08:26:28.651359794Z", + "buildFinishedOn": "2022-12-16T08:26:29.625483253Z", + "reproducible": false, + "completeness": { + "parameters": true, + "environment": true, + "materials": false + }, + "https://mobyproject.org/buildkit@v1#metadata": { + "vcs": { + "revision": "a9ba846486420e07d30db1107411ac3697ecab68", + "source": "git@github.com:/.git" + } + } + } + } +} +``` + +### Max + +The `max` mode includes all of the information included in the `min` mode, as +well as: + +- The LLB definition of the build. These show the exact steps taken to produce + the image. +- Information about the Dockerfile, including a full base64-encoded version of + the file. +- Source maps describing the relationship between build steps and image layers. + +When possible, you should prefer `mode=max` as it contains significantly more +detailed information for analysis. However, on some builds it may not be +appropriate, as it includes the values of +[build arguments](../../engine/reference/commandline/buildx_build.md#build-arg) +and metadata about secrets and SSH mounts. If you pass sensitive information +using build arguments, consider refactoring builds to pass secret values using +[build secrets](../../engine/reference/commandline/buildx_build.md#secret), to +prevent leaking of sensitive information. + +## Inspecting Provenance + +To explore created Provenance exported through the `image` exporter, you can +use [`imagetools inspect`](../../engine/reference/commandline/buildx_imagetools_inspect.md). + +Using the `--format` option, you can specify a template for the output. All +provenance-related data is available under the `.Provenance` attribute. For +example, to get the raw contents of the Provenance in the SLSA format: + +{% raw %} +```console +$ docker buildx imagetools inspect /: \ + --format "{{ json .Provenance.SLSA }}" +{ + "buildType": "https://mobyproject.org/buildkit@v1", + ... +} +``` +{% endraw %} + +You can also construct more complex expressions using the full functionality of +Go templates. For example, for provenance generated with `mode=max`, you can +extract the full source code of the Dockerfile used to build the image: + +{% raw %} +```console +$ docker buildx imagetools inspect /: \ + --format '{{ range (index .Provenance.SLSA.metadata "https://mobyproject.org/buildkit@v1#metadata").source.infos }}{{ if eq .filename "Dockerfile" }}{{ .data }}{{ end }}{{ end }}' | base64 -d +FROM ubuntu:20.04 +RUN apt-get update +... +``` +{% endraw %} + +## Provenance attestation example + + + +The following example shows what a JSON representation of a provenance +attestation with `mode=max` looks like: + +```json +{ + "_type": "https://in-toto.io/Statement/v0.1", + "predicateType": "https://slsa.dev/provenance/v0.2", + "subject": [ + { + "name": "pkg:docker//@?platform=", + "digest": { + "sha256": "e8275b2b76280af67e26f068e5d585eb905f8dfd2f1918b3229db98133cb4862" + } + } + ], + "predicate": { + "builder": { "id": "" }, + "buildType": "https://mobyproject.org/buildkit@v1", + "materials": [ + { + "uri": "pkg:docker/docker/dockerfile@1", + "digest": { + "sha256": "9ba7531bd80fb0a858632727cf7a112fbfd19b17e94c4e84ced81e24ef1a0dbc" + } + }, + { + "uri": "pkg:docker/golang@1.19.4-alpine?platform=linux%2Farm64", + "digest": { + "sha256": "a9b24b67dc83b3383d22a14941c2b2b2ca6a103d805cac6820fd1355943beaf1" + } + } + ], + "buildConfig": { + "llbDefinition": [ + { + "id": "step4", + "op": { + "Op": { + "exec": { + "meta": { + "args": ["/bin/sh", "-c", "go mod download -x"], + "env": [ + "PATH=/go/bin:/usr/local/go/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin", + "GOLANG_VERSION=1.19.4", + "GOPATH=/go", + "CGO_ENABLED=0" + ], + "cwd": "/src" + }, + "mounts": [ + { "input": 0, "dest": "/", "output": 0 }, + { + "input": -1, + "dest": "/go/pkg/mod", + "output": -1, + "mountType": 3, + "cacheOpt": { "ID": "//go/pkg/mod" } + }, + { + "input": 1, + "selector": "/go.mod", + "dest": "/src/go.mod", + "output": -1, + "readonly": true + }, + { + "input": 1, + "selector": "/go.sum", + "dest": "/src/go.sum", + "output": -1, + "readonly": true + } + ] + } + }, + "platform": { "Architecture": "arm64", "OS": "linux" }, + "constraints": {} + }, + "inputs": ["step3:0", "step1:0"] + } + ] + }, + "metadata": { + "buildInvocationID": "edf52vxjyf9b6o5qd7vgx0gru", + "buildStartedOn": "2022-12-15T15:38:13.391980297Z", + "buildFinishedOn": "2022-12-15T15:38:14.274565297Z", + "reproducible": false, + "completeness": { + "parameters": true, + "environment": true, + "materials": false + }, + "https://mobyproject.org/buildkit@v1#metadata": { + "vcs": { + "revision": "a9ba846486420e07d30db1107411ac3697ecab68-dirty", + "source": "git@github.com:/.git" + }, + "source": { + "locations": { + "step4": { + "locations": [ + { + "ranges": [ + { "start": { "line": 5 }, "end": { "line": 5 } }, + { "start": { "line": 6 }, "end": { "line": 6 } }, + { "start": { "line": 7 }, "end": { "line": 7 } }, + { "start": { "line": 8 }, "end": { "line": 8 } } + ] + } + ] + } + }, + "infos": [ + { + "filename": "Dockerfile", + "data": "RlJPTSBhbHBpbmU6bGF0ZXN0Cg==", + "llbDefinition": [ + { + "id": "step0", + "op": { + "Op": { + "source": { + "identifier": "local://dockerfile", + "attrs": { + "local.differ": "none", + "local.followpaths": "[\"Dockerfile\",\"Dockerfile.dockerignore\",\"dockerfile\"]", + "local.session": "s4j58ngehdal1b5hn7msiqaqe", + "local.sharedkeyhint": "dockerfile" + } + } + }, + "constraints": {} + } + }, + { "id": "step1", "op": { "Op": null }, "inputs": ["step0:0"] } + ] + } + ] + }, + "layers": { + "step2:0": [ + [ + { + "mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip", + "digest": "sha256:261da4162673b93e5c0e7700a3718d40bcc086dbf24b1ec9b54bca0b82300626", + "size": 3259190 + }, + { + "mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip", + "digest": "sha256:bc729abf26b5aade3c4426d388b5ea6907fe357dec915ac323bb2fa592d6288f", + "size": 286218 + }, + { + "mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip", + "digest": "sha256:7f1d6579712341e8062db43195deb2d84f63b0f2d1ed7c3d2074891085ea1b56", + "size": 116878653 + }, + { + "mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip", + "digest": "sha256:652874aefa1343799c619d092ab9280b25f96d97939d5d796437e7288f5599c9", + "size": 156 + } + ] + ] + } + } + } + } +} +``` diff --git a/build/bake/compose-file.md b/build/bake/compose-file.md index 5d78765f71..b220d8e943 100644 --- a/build/bake/compose-file.md +++ b/build/bake/compose-file.md @@ -40,6 +40,7 @@ services: ```console $ docker buildx bake --print ``` + ```json { "group": { @@ -124,6 +125,7 @@ TAG=v1.1.0 ```console $ docker buildx bake --print ``` + ```json { "group": { @@ -200,6 +202,7 @@ services: ```console $ docker buildx bake --print ``` + ```json { "group": { diff --git a/build/bake/configuring-build.md b/build/bake/configuring-build.md index 9c267861a0..4222936004 100644 --- a/build/bake/configuring-build.md +++ b/build/bake/configuring-build.md @@ -5,8 +5,8 @@ redirect_from: - /build/customize/bake/configuring-build/ --- -Bake supports loading build definition from files, but sometimes you need even -more flexibility to configure this definition. +Bake supports loading build definitions from files, but sometimes you need even +more flexibility to configure these definitions. For this use case, you can define variables inside the bake files that can be set by the user with environment variables or by [attribute definitions](#global-scope-attributes) @@ -38,6 +38,7 @@ You can use this file directly: ```console $ docker buildx bake --print app ``` + ```json { "group": { @@ -72,6 +73,7 @@ And invoke bake together with both of the files: ```console $ docker buildx bake -f docker-bake.hcl -f env.hcl --print app ``` + ```json { "group": { @@ -93,6 +95,56 @@ $ docker buildx bake -f docker-bake.hcl -f env.hcl --print app } ``` +You can also refer to attributes defined as part of other targets, to help +reduce duplication between targets. + +```hcl +# docker-bake.hcl +target "foo" { + dockerfile = "${target.foo.name}.Dockerfile" + tags = [target.foo.name] +} +target "bar" { + dockerfile = "${target.foo.name}.Dockerfile" + tags = [target.bar.name] +} +``` + +You can use this file directly: + +```console +$ docker buildx bake --print foo bar +``` + +```json +{ + "group": { + "default": { + "targets": [ + "foo", + "bar" + ] + } + }, + "target": { + "foo": { + "context": ".", + "dockerfile": "foo.Dockerfile", + "tags": [ + "foo" + ] + }, + "bar": { + "context": ".", + "dockerfile": "foo.Dockerfile", + "tags": [ + "bar" + ] + } + } +} +``` + ## From command line You can also override target configurations from the command line with the @@ -110,6 +162,7 @@ target "app" { ```console $ docker buildx bake --set app.args.mybuildarg=bar --set app.platform=linux/arm64 app --print ``` + ```json { "group": { @@ -198,6 +251,7 @@ target "app" { ```console $ docker buildx bake -f docker-bake1.hcl -f docker-bake2.hcl --print app ``` + ```json { "group": { diff --git a/build/bake/file-definition.md b/build/bake/file-definition.md index 75b39c5481..c4e5b53e83 100644 --- a/build/bake/file-definition.md +++ b/build/bake/file-definition.md @@ -2,7 +2,7 @@ title: "Bake file definition" keywords: build, buildx, bake, buildkit, hcl, json, compose redirect_from: -- /build/customize/bake/file-definition/ + - /build/customize/bake/file-definition/ --- `buildx bake` supports HCL, JSON and Compose file format for defining build @@ -10,12 +10,12 @@ redirect_from: [functions](#functions). It looks for build definition files in the current directory in the following order: -* `docker-compose.yml` -* `docker-compose.yaml` -* `docker-bake.json` -* `docker-bake.override.json` -* `docker-bake.hcl` -* `docker-bake.override.hcl` +- `docker-compose.yml` +- `docker-compose.yaml` +- `docker-bake.json` +- `docker-bake.override.json` +- `docker-bake.hcl` +- `docker-bake.override.hcl` ## Specification @@ -24,7 +24,7 @@ project specific reusable build flows. ### Target -A target reflects a single docker build invocation with the same options that +A target reflects a single `docker build` invocation with the same options that you would specify for `docker build`: ```hcl @@ -34,6 +34,7 @@ target "webapp-dev" { tags = ["docker.io/username/webapp:latest"] } ``` + ```console $ docker buildx bake webapp-dev ``` @@ -46,26 +47,27 @@ $ docker buildx bake webapp-dev Complete list of valid target fields available for [HCL](#hcl-definition) and [JSON](#json-definition) definitions: -| Name | Type | Description | -|---------------------|--------|---------------------------------------------------------------------------------------------------------------------------------| -| `inherits` | List | [Inherit build options](#merging-and-inheritance) from other targets | -| `args` | Map | Set build-time variables (same as [`--build-arg` flag](../../engine/reference/commandline/buildx_build.md)) | -| `cache-from` | List | External cache sources (same as [`--cache-from` flag](../../engine/reference/commandline/buildx_build.md)) | -| `cache-to` | List | Cache export destinations (same as [`--cache-to` flag](../../engine/reference/commandline/buildx_build.md)) | -| `context` | String | Set of files located in the specified path or URL | -| `contexts` | Map | Additional build contexts (same as [`--build-context` flag](../../engine/reference/commandline/buildx_build.md)) | -| `dockerfile` | String | Name of the Dockerfile (same as [`--file` flag](../../engine/reference/commandline/buildx_build.md)) | -| `dockerfile-inline` | String | Inline Dockerfile content | -| `labels` | Map | Set metadata for an image (same as [`--label` flag](../../engine/reference/commandline/buildx_build.md)) | -| `no-cache` | Bool | Do not use cache when building the image (same as [`--no-cache` flag](../../engine/reference/commandline/buildx_build.md)) | -| `no-cache-filter` | List | Do not cache specified stages (same as [`--no-cache-filter` flag](../../engine/reference/commandline/buildx_build.md)) | -| `output` | List | Output destination (same as [`--output` flag](../../engine/reference/commandline/buildx_build.md)) | -| `platforms` | List | Set target platforms for build (same as [`--platform` flag](../../engine/reference/commandline/buildx_build.md)) | -| `pull` | Bool | Always attempt to pull all referenced images (same as [`--pull` flag](../../engine/reference/commandline/buildx_build.md)) | -| `secret` | List | Secret to expose to the build (same as [`--secret` flag](../../engine/reference/commandline/buildx_build.md)) | -| `ssh` | List | SSH agent socket or keys to expose to the build (same as [`--ssh` flag](../../engine/reference/commandline/buildx_build.md)) | -| `tags` | List | Name and optionally a tag in the format `name:tag` (same as [`--tag` flag](../../engine/reference/commandline/buildx_build.md)) | -| `target` | String | Set the target build stage to build (same as [`--target` flag](../../engine/reference/commandline/buildx_build.md)) | +| Name | Type | Description | +| ------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `args` | Map | Set build-time variables (same as [`--build-arg` flag](../../engine/reference/commandline/buildx_build.md)) | +| `attest` | List | Define attestations that should be applied to the image, see [SBOM attestations](../attestations/sbom.md) and [Provenance attestations](../attestations/slsa-provenance.md) | +| `cache-from` | List | External cache sources (same as [`--cache-from` flag](../../engine/reference/commandline/buildx_build.md)) | +| `cache-to` | List | Cache export destinations (same as [`--cache-to` flag](../../engine/reference/commandline/buildx_build.md)) | +| `context` | String | Set of files located in the specified path or URL | +| `contexts` | Map | Additional build contexts (same as [`--build-context` flag](../../engine/reference/commandline/buildx_build.md)) | +| `dockerfile-inline` | String | Inline Dockerfile content | +| `dockerfile` | String | Name of the Dockerfile (same as [`--file` flag](../../engine/reference/commandline/buildx_build.md)) | +| `inherits` | List | [Inherit build options](#merging-and-inheritance) from other targets | +| `labels` | Map | Set metadata for an image (same as [`--label` flag](../../engine/reference/commandline/buildx_build.md)) | +| `no-cache-filter` | List | Do not cache specified stages (same as [`--no-cache-filter` flag](../../engine/reference/commandline/buildx_build.md)) | +| `no-cache` | Bool | Do not use cache when building the image (same as [`--no-cache` flag](../../engine/reference/commandline/buildx_build.md)) | +| `output` | List | Output destination (same as [`--output` flag](../../engine/reference/commandline/buildx_build.md)) | +| `platforms` | List | Set target platforms for build (same as [`--platform` flag](../../engine/reference/commandline/buildx_build.md)) | +| `pull` | Bool | Always attempt to pull all referenced images (same as [`--pull` flag](../../engine/reference/commandline/buildx_build.md)) | +| `secret` | List | Secret to expose to the build (same as [`--secret` flag](../../engine/reference/commandline/buildx_build.md)) | +| `ssh` | List | SSH agent socket or keys to expose to the build (same as [`--ssh` flag](../../engine/reference/commandline/buildx_build.md)) | +| `tags` | List | Name and optionally a tag in the format `name:tag` (same as [`--tag` flag](../../engine/reference/commandline/buildx_build.md)) | +| `target` | String | Set the target build stage to build (same as [`--target` flag](../../engine/reference/commandline/buildx_build.md)) | ### Group @@ -87,6 +89,7 @@ target "db" { tags = ["docker.io/username/db"] } ``` + ```console $ docker buildx bake build ``` @@ -109,6 +112,7 @@ target "webapp-dev" { tags = ["docker.io/username/webapp:${TAG}"] } ``` + ```console $ docker buildx bake webapp-dev # will use the default value "latest" $ TAG=dev docker buildx bake webapp-dev # will use the TAG environment variable value @@ -118,6 +122,61 @@ $ TAG=dev docker buildx bake webapp-dev # will use the TAG environment variable > > See also the [Configuring builds](configuring-build.md) page for advanced usage. +### Null values + +Null values for `args` and `labels` are supported, so default sets in your +Dockerfile will be used: + +```hcl +# docker-bake.hcl +variable "GO_VERSION" { + default = null +} +target "default" { + args = { + GO_VERSION = GO_VERSION + } +} +``` + +```dockerfile +ARG GO_VERSION="1.18" +FROM golang:${GO_VERSION} +``` + +```console +$ docker buildx bake --print +``` + +```json +{ + "target": { + "default": { + "context": ".", + "dockerfile": "Dockerfile" + } + } +} +``` + +```console +$ GO_VERSION=1.19 docker buildx bake --print +``` + +```json +{ + "target": { + "default": { + "context": ".", + "dockerfile": "Dockerfile", + "args": { + "GO_VERSION": "1.19" + } + } + } +} +``` + ### Functions A [set of generally useful functions](https://github.com/docker/buildx/blob/master/bake/hclparser/stdlib.go){:target="blank" rel="noopener" class=""} @@ -160,9 +219,9 @@ target "webapp-dev" { ## Built-in variables -* `BAKE_CMD_CONTEXT` can be used to access the main `context` for bake command +- `BAKE_CMD_CONTEXT` can be used to access the main `context` for bake command from a bake file that has been [imported remotely](file-definition.md#remote-definition). -* `BAKE_LOCAL_PLATFORM` returns the current platform's default platform +- `BAKE_LOCAL_PLATFORM` returns the current platform's default platform specification (e.g. `linux/amd64`). ## Merging and inheritance @@ -177,12 +236,14 @@ target "webapp-dev" { tags = ["docker.io/username/webapp:latest"] } ``` + ```hcl # docker-bake2.hcl target "webapp-dev" { tags = ["docker.io/username/webapp:dev"] } ``` + ```console $ docker buildx bake -f docker-bake.hcl -f docker-bake2.hcl webapp-dev ``` @@ -216,6 +277,7 @@ target "default" { tags = ["docker.io/username/webapp:latest"] } ``` + ```console $ docker buildx bake ``` @@ -264,33 +326,21 @@ target "db" { }, "group": { "default": { - "targets": [ - "db", - "webapp-dev" - ] + "targets": ["db", "webapp-dev"] } }, "target": { "webapp-dev": { "dockerfile": "Dockerfile.webapp", - "tags": [ - "docker.io/username/webapp:${TAG}" - ] + "tags": ["docker.io/username/webapp:${TAG}"] }, "webapp-release": { - "inherits": [ - "webapp-dev" - ], - "platforms": [ - "linux/amd64", - "linux/arm64" - ] + "inherits": ["webapp-dev"], + "platforms": ["linux/amd64", "linux/arm64"] }, "db": { "dockerfile": "Dockerfile.db", - "tags": [ - "docker.io/username/db" - ] + "tags": ["docker.io/username/db"] } } } @@ -328,6 +378,7 @@ $ docker buildx bake "https://github.com/docker/cli.git#v20.10.11" --print #1 2.022 * [new tag] v20.10.11 -> v20.10.11 #1 DONE 2.9s ``` + ```json { "group": { @@ -368,6 +419,7 @@ that has been imported remotely, you can use the [`BAKE_CMD_CONTEXT` built-in va ```console $ cat https://raw.githubusercontent.com/tonistiigi/buildx/remote-test/docker-bake.hcl ``` + ```hcl target "default" { context = BAKE_CMD_CONTEXT @@ -383,6 +435,7 @@ EOT ```console $ docker buildx bake "https://github.com/tonistiigi/buildx.git#remote-test" --print ``` + ```json { "target": { @@ -399,6 +452,7 @@ $ docker buildx bake "https://github.com/tonistiigi/buildx.git#remote-test" --pr $ touch foo bar $ docker buildx bake "https://github.com/tonistiigi/buildx.git#remote-test" ``` + ```text ... > [4/4] RUN ls -l && stop: @@ -414,6 +468,7 @@ $ docker buildx bake "https://github.com/tonistiigi/buildx.git#remote-test" "htt #1 0.429 577303add004dd7efeb13434d69ea030d35f7888 refs/heads/remote-test #1 CACHED ``` + ```json { "target": { @@ -429,6 +484,7 @@ $ docker buildx bake "https://github.com/tonistiigi/buildx.git#remote-test" "htt ```console $ docker buildx bake "https://github.com/tonistiigi/buildx.git#remote-test" "https://github.com/docker/cli.git#v20.10.11" ``` + ```text ... > [4/4] RUN ls -l && stop: diff --git a/build/bake/hcl-funcs.md b/build/bake/hcl-funcs.md index 36ce8f63ba..3176bbd784 100644 --- a/build/bake/hcl-funcs.md +++ b/build/bake/hcl-funcs.md @@ -51,6 +51,7 @@ alternatively, in json format: ```console $ docker buildx bake --print webapp ``` + ```json { "group": { @@ -75,6 +76,7 @@ $ docker buildx bake --print webapp ```console $ TAG=$(git rev-parse --short HEAD) docker buildx bake --print webapp ``` + ```json { "group": { @@ -121,6 +123,7 @@ target "webapp" { ```console $ docker buildx bake --print webapp ``` + ```json { "group": { @@ -168,6 +171,7 @@ target "webapp" { ```console $ docker buildx bake --print webapp ``` + ```json { "group": { @@ -217,6 +221,7 @@ target "webapp" { ```console $ docker buildx bake --print webapp ``` + ```json { "group": { @@ -262,6 +267,7 @@ target "webapp" { ```console $ docker buildx bake --print webapp ``` + ```json { "group": { @@ -309,6 +315,7 @@ target "app" { ```console $ docker buildx bake --print app ``` + ```json { "group": { diff --git a/build/building/packaging.md b/build/building/packaging.md index d118524e16..e39cbc19b5 100644 --- a/build/building/packaging.md +++ b/build/building/packaging.md @@ -36,7 +36,7 @@ without having to specify additional command flags. Some projects may need distinct Dockerfiles for specific purposes. A common convention is to name these `.Dockerfile`. Such Dockerfiles can then be used through the `--file` (or `-f` shorthand) option on the `docker build` command. -Refer to the ["Specify a Dockerfile" section](../../engine/reference/commandline/build.md#specify-a-dockerfile--f) +Refer to the ["Specify a Dockerfile" section](../../engine/reference/commandline/build.md#file) in the `docker build` reference to learn about the `--file` option. > **Note** diff --git a/build/cache/index.md b/build/cache/index.md index 64dfe20507..0cd5a99482 100644 --- a/build/cache/index.md +++ b/build/cache/index.md @@ -98,7 +98,7 @@ RUN npm build # Run build ``` This Dockerfile is rather inefficient. Updating any file causes a reinstall of -all dependencies every time you build the Docker image &emdash; even if the +all dependencies every time you build the Docker image even if the dependencies didn't change since last time! Instead, the `COPY` command can be split in two. First, copy over the package @@ -264,7 +264,7 @@ RUN echo "the second command" ``` It's possible to run both of these commands inside a single `RUN`, which means -that they will share the same cache! This can is achievable using the `&&` shell +that they will share the same cache! This is achievable using the `&&` shell operator to run one command after another: ```dockerfile diff --git a/compose/cli-command-compatibility.md b/compose/cli-command-compatibility.md deleted file mode 100644 index 6c93617f32..0000000000 --- a/compose/cli-command-compatibility.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -description: Compose command compatibility with docker-compose -keywords: documentation, docs, docker, compose, containers -title: Compose command compatibility with docker-compose ---- - -The `compose` command in the Docker CLI supports most of the `docker-compose` commands and flags. It is expected to be a drop-in replacement for `docker-compose`. - -If you see any Compose functionality that is not available in the `compose` command, create an issue in the [Compose](https://github.com/docker/compose/issues){:target="_blank" rel="noopener" class="_"} GitHub repository, so we can prioritize it. - -## Commands or flags not yet implemented - -The following commands have not been implemented yet, and may be implemented at a later time. -Let us know if these commands are a higher priority for your use cases. - -`compose build --memory`: This option is not yet supported by BuildKit. The flag is currently supported, but is hidden to avoid breaking existing Compose usage. It does not have any effect. - -## Flags that will not be implemented - -The list below includes the flags that we are not planning to support in Compose in the Docker CLI, -either because they are already deprecated in `docker-compose`, or because they are not relevant for Compose in the Docker CLI. - -* `compose ps --filter KEY-VALUE` Not relevant due to its complicated usage with the `service` command and also because it is not documented properly in `docker-compose`. -* `compose rm --all` Deprecated in docker-compose. -* `compose scale` Deprecated in docker-compose (use `compose up --scale` instead) - -Global flags: - -* `--compatibility` has been resignified Docker Compose V2. This now means that in the command running V2 will behave as V1 used to do. - * One difference is in the word separator on container names. V1 used to use `_` as separator while V2 uses `-` to keep the names more hostname friendly. So when using `--compatibility` Docker - Compose should use `_` again. Just make sure to stick to one of them otherwise Docker Compose will not be able to recognize the container as an instance of the service. - -## Config command - -The config command is intended to show the configuration used by Docker Compose to run the actual project. -As we know, at some parts of the Compose file have a short and a long format. For example, the `ports` entry. -In the example below we can see the config command expanding the `ports` section: - -docker-compose.yml: -``` -services: - web: - image: nginx - ports: - - 80:80 -``` -With `$ docker compose config` the output turns into: -``` -services: - web: - image: nginx - networks: - default: null - ports: - - mode: ingress - target: 80 - published: 80 - protocol: tcp -networks: - default: - name: workspace_default -``` - -The result above is a full size configuration of what will be used by Docker Compose to run the project. - -## New commands introduced in Compose v2 - -### Copy - -The `cp` command is intended to copy files or folders between service containers and the local filesystem. -This command is a bidirectional command, we can copy **from** or **to** the service containers. - -Copy a file from a service container to the local filesystem: - -```console -$ docker compose cp my-service:~/path/to/myfile ~/local/path/to/copied/file -``` - -We can also copy from the local filesystem to all the running containers of a service: - -```console -$ docker compose cp --all ~/local/path/to/source/file my-service:~/path/to/copied/file -``` - - -### List - -The ls command is intended to list the Compose projects. By default, the command only lists the running projects, -we can use flags to display the stopped projects, to filter by conditions and change the output to `json` format for example. - -```console -$ docker compose ls --all --format json -[{"Name":"dockergithubio","Status":"exited(1)","ConfigFiles":"/path/to/docs/docker-compose.yml"}] -``` - -## Use `--project-name` with Compose commands - -With the GA version of Compose, you can run some commands: -- outside of directory containing the project compose file -- or without specifying the path of the Compose with the `--file` flag -- or without specifying the project directory with the `--project-directory` flag - -When a compose project has been loaded once, we can just use the `-p` or `--project-name` to reference it: - -```console -$ docker compose -p my-loaded-project restart my-service -``` - -This option works with the `start`, `stop`, `restart` and `down` commands. \ No newline at end of file diff --git a/compose/compose-file/compose-file-v2.md b/compose/compose-file/compose-file-v2.md index 2c526f8caa..ae883826d4 100644 --- a/compose/compose-file/compose-file-v2.md +++ b/compose/compose-file/compose-file-v2.md @@ -271,7 +271,7 @@ An entry with the ip address and hostname is created in `/etc/hosts` inside cont Specify a build’s container isolation technology. On Linux, the only supported value is `default`. On Windows, acceptable values are `default`, `process` and `hyperv`. Refer to the -[Docker Engine docs](../../engine/reference/commandline/run.md#specify-isolation-technology-for-container---isolation) +[Docker Engine docs](../../engine/reference/commandline/run.md#isolation) for details. If unspecified, Compose will use the `isolation` value found in the service's definition @@ -898,7 +898,7 @@ services: Specify a container’s isolation technology. On Linux, the only supported value is `default`. On Windows, acceptable values are `default`, `process` and `hyperv`. Refer to the -[Docker Engine docs](../../engine/reference/commandline/run.md#specify-isolation-technology-for-container---isolation) +[Docker Engine docs](../../engine/reference/commandline/run.md#isolation) for details. ### labels @@ -942,7 +942,7 @@ the alias, or the service name if no alias was specified. Links are not required to enable services to communicate - by default, any service can reach any other service at that service’s name. (See also, the -[Links topic in Networking in Compose](../networking.md#links).) +[Links topic in Networking in Compose](../networking.md#link-containers).) Links also express dependency between services in the same way as [depends_on](#depends_on), so they determine the order of service startup. diff --git a/compose/compose-file/compose-file-v3.md b/compose/compose-file/compose-file-v3.md index 0d780c34bc..fae833f574 100644 --- a/compose/compose-file/compose-file-v3.md +++ b/compose/compose-file/compose-file-v3.md @@ -792,9 +792,9 @@ services: Specify placement of constraints and preferences. See the docker service create documentation for a full description of the syntax and available types of -[constraints](../../engine/reference/commandline/service_create.md#specify-service-constraints---constraint), -[preferences](../../engine/reference/commandline/service_create.md#specify-service-placement-preferences---placement-pref), -and [specifying the maximum replicas per node](../../engine/reference/commandline/service_create.md#specify-maximum-replicas-per-node---replicas-max-per-node) +[constraints](../../engine/reference/commandline/service_create.md#constraint), +[preferences](../../engine/reference/commandline/service_create.md#placement-pref), +and [specifying the maximum replicas per node](../../engine/reference/commandline/service_create.md#replicas-max-per-node) ```yaml version: "{{ site.compose_file_v3 }}" @@ -814,7 +814,7 @@ services: > Added in [version 3.8](compose-versioning.md#version-38) file format. -If the service is `replicated` (which is the default), [limit the number of replicas](../../engine/reference/commandline/service_create.md#specify-maximum-replicas-per-node---replicas-max-per-node) +If the service is `replicated` (which is the default), [limit the number of replicas](../../engine/reference/commandline/service_create.md#replicas-max-per-node) that can run on a node at any time. When there are more tasks requested than running nodes, an error @@ -1343,7 +1343,7 @@ services: Specify a container’s isolation technology. On Linux, the only supported value is `default`. On Windows, acceptable values are `default`, `process` and `hyperv`. Refer to the -[Docker Engine docs](../../engine/reference/commandline/run.md#specify-isolation-technology-for-container---isolation) +[Docker Engine docs](../../engine/reference/commandline/run.md#isolation) for details. ### labels @@ -1397,7 +1397,7 @@ the alias, or the service name if no alias was specified. Links are not required to enable services to communicate - by default, any service can reach any other service at that service’s name. (See also, the -[Links topic in Networking in Compose](../networking.md#links).) +[Link containers section in Networking in Compose](../networking.md#link-containers).) Links also express dependency between services in the same way as [depends_on](#depends_on), so they determine the order of service startup. @@ -1908,7 +1908,7 @@ sysctls: You can only use sysctls that are namespaced in the kernel. Docker does not support changing sysctls inside a container that also modify the host system. For an overview of supported sysctls, refer to -[configure namespaced kernel parameters (sysctls) at runtime](../../engine/reference/commandline/run.md#configure-namespaced-kernel-parameters-sysctls-at-runtime). +[configure namespaced kernel parameters (sysctls) at runtime](../../engine/reference/commandline/run.md#sysctl). > Note when using docker stack deploy > diff --git a/compose/compose-file/index.md b/compose/compose-file/index.md index 3930870bd1..a0b217c8b8 100644 --- a/compose/compose-file/index.md +++ b/compose/compose-file/index.md @@ -1756,7 +1756,7 @@ sysctls: You can only use sysctls that are namespaced in the kernel. Docker does not support changing sysctls inside a container that also modify the host system. For an overview of supported sysctls, refer to [configure namespaced kernel -parameters (sysctls) at runtime](/engine/reference/commandline/run/#configure-namespaced-kernel-parameters-sysctls-at-runtime). +parameters (sysctls) at runtime](/engine/reference/commandline/run/#sysctl). ### tmpfs diff --git a/compose/compose-v2/index.md b/compose/compose-v2/index.md index 3ad58d43e9..4894d5605b 100644 --- a/compose/compose-v2/index.md +++ b/compose/compose-v2/index.md @@ -1,45 +1,164 @@ --- description: Key features and use cases of Docker Compose keywords: documentation, docs, docker, compose, orchestration, containers, uses, features -title: Compose V2 Overview +title: Evolution of Compose +redirect_from: + - /compose/cli-command-compatibility/ --- -## Compose V2 and the new `docker compose` command +This page provides information on the history of Compose and explains the key differences between Compose V1 and Compose V2. -> Important -> -> The new Compose V2, which supports the `compose` command as part of the Docker -> CLI, is now available. -> -> Compose V2 integrates compose functions into the Docker platform, continuing -> to support most of the previous `docker-compose` features and flags. You can -> run Compose V2 by replacing the hyphen (`-`) with a space, using `docker compose`, -> instead of `docker-compose`. -{: .important} +## History -If you rely on using Docker Compose as `docker-compose` (with a hyphen), you can -set up Compose V2 to act as a drop-in replacement of the previous `docker-compose`. -Refer to the [Installing Compose](../install/index.md) section for detailed instructions. +The first release of Compose, written in Python, happened at the end of 2014. +Between 2014 and 2017 two other noticeable versions of Compose, which introduced new file format versions, were released: -## Context of Docker Compose evolution +- [Compose 1.6.0 with file format V2](../compose-file/compose-file-v2/) +- [Compose 1.10.0 with file format V3](../compose-file/compose-file-v3/) -Introduction of the [Compose specification](https://github.com/compose-spec/compose-spec){:target="_blank" rel="noopener" class="_"} -makes a clean distinction between the Compose YAML file model and the `docker-compose` +These three key file format versions and releases prior to v1.29.2 are collectively referred to as Compose V1. + +In mid-2020 Compose V2 was released. It merged Compose file format V2 and V3 and was written in Go. The file format is defined by the [Compose specification](https://github.com/compose-spec/compose-spec){:target="_blank" rel="noopener" class="_"}. Compose V2 is the latest and recommended version of Compose. It provides improved integration with other Docker command-line features, and simplified installation on macOS, Windows, and Linux. + +It makes a clean distinction between the Compose YAML file model and the `docker-compose` implementation. Making this change has enabled a number of enhancements, including adding the `compose` command directly into the Docker CLI, being able to "up" a Compose application on cloud platforms by simply switching the Docker context, and launching of [Amazon ECS](../../cloud/ecs-integration.md) and [Microsoft ACI](../../cloud/aci-integration.md). As the Compose specification evolves, new features land faster in the Docker CLI. +> **A note about version numbers** +> +>In addition to Compose file format versions described above, the Compose binary itself is on a release schedule, as shown in [Compose releases](https://github.com/docker/compose/releases/). File format versions do not necessarily increment with each release. For example, Compose file format V3 was first introduced in Compose release 1.10.0, and versioned gradually in subsequent releases. +> +>The latest Compose file format, defined by the Compose Specification, was implemented by Docker Compose 1.27.0+. + +## Differences between Compose V1 and Compose V2 + +Compose V2 integrates compose functions into the Docker platform, continuing to support most of the previous `docker-compose` features and flags. You can run Compose V2 by replacing the hyphen (`-`) with a space, using `docker compose`, instead of `docker-compose`. + +The `compose` command in the Docker CLI supports most of the `docker-compose` commands and flags. It is expected to be a drop-in replacement for `docker-compose`. + +If you see any Compose functionality that is not available in the `compose` command, create an issue in the [Compose](https://github.com/docker/compose/issues){:target="_blank" rel="noopener" class="_"} GitHub repository, so we can prioritize it. + Compose V2 relies directly on the compose-go bindings which are maintained as part of the specification. This allows us to include community proposals, experimental implementations by the Docker CLI and/or Engine, and deliver features faster to -users. Compose V2 also supports some of the newer additions to the specification, -such as [profiles](../profiles.md) and [GPU](../gpu-support.md) devices. +users. -Compose V2 has been re-written in [Go](https://go.dev), which improves integration -with other Docker command-line features, and allows it to run natively on -[macOS on Apple silicon](../../desktop/install/mac-install.md), Windows, and Linux, -without dependencies such as Python. + +
    +
    -For more information about compatibility with the compose v1 command-line, see the [docker-compose compatibility list](../cli-command-compatibility.md). \ No newline at end of file +The following commands have not been implemented yet, and may be implemented at a later time. +Let us know if these commands are a higher priority for your use cases. + +`compose build --memory`: This option is not yet supported by BuildKit. The flag is currently supported, but is hidden to avoid breaking existing Compose usage. It does not have any effect. + +
    +
    +
    + +The list below includes the flags that we are not planning to support in Compose in the Docker CLI, +either because they are already deprecated in `docker-compose`, or because they are not relevant for Compose in the Docker CLI. + +* `compose ps --filter KEY-VALUE` Not relevant due to its complicated usage with the `service` command and also because it is not documented properly in `docker-compose`. +* `compose rm --all` Deprecated in docker-compose. +* `compose scale` Deprecated in docker-compose (use `compose up --scale` instead) + +Global flags: + +* `--compatibility` has been resignified Docker Compose V2. This now means that in the command running V2 will behave as V1 used to do. + * One difference is in the word separator on container names. V1 used to use `_` as separator while V2 uses `-` to keep the names more hostname friendly. So when using `--compatibility` Docker + Compose should use `_` again. Just make sure to stick to one of them otherwise Docker Compose will not be able to recognize the container as an instance of the service. +
    +
    +
    + +#### Copy + +The `cp` command is intended to copy files or folders between service containers and the local filesystem. +This command is a bidirectional command, we can copy **from** or **to** the service containers. + +Copy a file from a service container to the local filesystem: + +```console +$ docker compose cp my-service:~/path/to/myfile ~/local/path/to/copied/file +``` + +We can also copy from the local filesystem to all the running containers of a service: + +```console +$ docker compose cp --all ~/local/path/to/source/file my-service:~/path/to/copied/file +``` + + +#### List + +The ls command is intended to list the Compose projects. By default, the command only lists the running projects, +we can use flags to display the stopped projects, to filter by conditions and change the output to `json` format for example. + +```console +$ docker compose ls --all --format json +[{"Name":"dockergithubio","Status":"exited(1)","ConfigFiles":"/path/to/docs/docker-compose.yml"}] +``` + +### Use `--project-name` with Compose commands + +With the GA version of Compose, you can run some commands: +- outside of directory containing the project compose file +- or without specifying the path of the Compose with the `--file` flag +- or without specifying the project directory with the `--project-directory` flag + +When a compose project has been loaded once, we can just use the `-p` or `--project-name` to reference it: + +```console +$ docker compose -p my-loaded-project restart my-service +``` + +This option works with the `start`, `stop`, `restart` and `down` commands. + +### Config command + +The config command is intended to show the configuration used by Docker Compose to run the actual project after normalization and templating. The resulting output might contain superficial differences in formattting and style. +For example, some fields in the Compose Specification support both short and a long format so the output structure might not match the input structure but is guaranteed to be semantically equivalent. + +Similarly, comments in the source file are not preserved. + +In the example below we can see the config command expanding the `ports` section: + +docker-compose.yml: +```yaml +services: + web: + # default to latest but allow overriding the tag + image: nginx:${TAG-latest} + ports: + - 80:80 +``` +With `$ docker compose config` the output turns into: +```yaml +name: docs-example +services: + web: + image: nginx:stable-alpine + networks: + default: null + ports: + - mode: ingress + target: 80 + published: "80" + protocol: tcp +networks: + default: + name: basic_default +``` + +The result above is a full size configuration of what will be used by Docker Compose to run the project. +
    +
    +
    diff --git a/compose/extends.md b/compose/extends.md index 509bc40764..92e37169c7 100644 --- a/compose/extends.md +++ b/compose/extends.md @@ -6,14 +6,14 @@ title: Share Compose configurations between files and projects Compose supports two methods of sharing common configuration: -1. Extending an entire Compose file by +1. Extend an entire Compose file by [using multiple Compose files](extends.md#multiple-compose-files) -2. Extending individual services with [the `extends` field](extends.md#extending-services) (for Compose file versions up to 2.1) +2. Extend individual services with [the `extends` field](extends.md#extending-services) ## Multiple Compose files -Using multiple Compose files enables you to customize a Compose application +Using multiple Compose files lets you to customize a Compose application for different environments or different workflows. ### Understanding multiple Compose files @@ -171,17 +171,6 @@ $ docker compose -f docker-compose.yml -f docker-compose.admin.yml \ ## Extending services -> **Note** -> -> The `extends` keyword is supported in earlier Compose file formats up to Compose -> file version 2.1 (see [extends in v2](compose-file/compose-file-v2.md#extends)), but is -> not supported in Compose version 3.x. See the [Version 3 summary](compose-file/compose-versioning.md#version-3) -> of keys added and removed, along with information on [how to upgrade](compose-file/compose-versioning.md#upgrading). -> See [moby/moby#31101](https://github.com/moby/moby/issues/31101) to follow the -> discussion thread on the possibility of adding support for `extends` in some form in -> future versions. The `extends` keyword has been included in docker-compose versions 1.27 -> and higher. - Docker Compose's `extends` keyword enables the sharing of common configurations among different files, or even different projects entirely. Extending services is useful if you have several services that reuse a common set of configuration @@ -454,11 +443,6 @@ services: ``` -## Compose documentation +## Reference information -- [User guide](index.md) -- [Installing Compose](install/index.md) -- [Getting Started](gettingstarted.md) -- [Command line reference](reference/index.md) -- [Compose file reference](compose-file/index.md) -- [Sample apps with Compose](samples-for-compose.md) +[`extends`](compose-file/index.md#extends) \ No newline at end of file diff --git a/compose/faq.md b/compose/faq.md index eeef5795d9..909fd6615f 100644 --- a/compose/faq.md +++ b/compose/faq.md @@ -4,26 +4,53 @@ keywords: documentation, docs, docker, compose, faq title: Frequently asked questions --- -If you don’t see your question here, feel free to drop by -[#docker-compose](https://dockercommunity.slack.com/archives/C2X82D9PA) on the -[Docker Community Slack](https://dockr.ly/slack). +## How do I get help? +Docker Compose is under active development. If you need help, would like to +contribute, or simply want to talk about the project with like-minded +individuals, we have a number of open channels for communication. -## Can I control service startup order? +* To report bugs or file feature requests, use the [issue tracker on Github](https://github.com/docker/compose/issues){: target="blank" rel="noopener" class="_" }. -Yes - see [Controlling startup order](startup-order.md). +* To talk about the project with people in real time, join the + `#docker-compose` channel on the [Docker Community Slack](https://dockr.ly/slack){: target="blank" rel="noopener" class="_" }. +* To contribute code submit a [pull request on Github](https://github.com/docker/compose/pulls){: target="blank" rel="noopener" class="_" }. + +## Where can I find example Compose files? + +There are [many examples of Compose files on GitHub](https://github.com/docker/awesome-compose){: target="blank" rel="noopener" class="_" }. + +## What's the difference between `up`, `run`, and `start`? + +Typically, you want `docker compose up`. Use `up` to start or restart all the +services defined in a `docker-compose.yml`. In the default "attached" +mode, you see all the logs from all the containers. In "detached" mode (`-d`), +Compose exits after starting the containers, but the containers continue to run +in the background. + +The `docker compose run` command is for running "one-off" or "adhoc" tasks. It +requires the service name you want to run and only starts containers for services +that the running service depends on. Use `run` to run tests or perform +an administrative task such as removing or adding data to a data volume +container. The `run` command acts like `docker run -ti` in that it opens an +interactive terminal to the container and returns an exit status matching the +exit status of the process in the container. + +The `docker compose start` command is useful only to restart containers +that were previously created, but were stopped. It never creates new +containers. ## Why do my services take 10 seconds to recreate or stop? -Compose stop attempts to stop a container by sending a `SIGTERM`. It then waits +The `docker compose stop` command attempts to stop a container by sending a `SIGTERM`. It then waits for a [default timeout of 10 seconds](../engine/reference/commandline/compose_stop.md). After the timeout, a `SIGKILL` is sent to the container to forcefully kill it. If you are waiting for this timeout, it means that your containers aren't shutting down when they receive the `SIGTERM` signal. There has already been a lot written about this problem of -[processes handling signals](https://medium.com/@gchudnov/trapping-signals-in-docker-containers-7a57fdda7d86) +[processes handling signals](https://medium.com/@gchudnov/trapping-signals-in-docker-containers-7a57fdda7d86){: target="blank" rel="noopener" class="_" } in containers. To fix this problem, try the following: @@ -49,11 +76,15 @@ services: ``` * If you can't modify the application, wrap the application in a lightweight init -system (like [s6](https://skarnet.org/software/s6/)) or a signal proxy (like -[dumb-init](https://github.com/Yelp/dumb-init) or -[tini](https://github.com/krallin/tini)). Either of these wrappers takes care of +system (like [s6](https://skarnet.org/software/s6/){: target="blank" rel="noopener" class="_" }) or a signal proxy (like +[dumb-init](https://github.com/Yelp/dumb-init){: target="blank" rel="noopener" class="_" } or +[tini](https://github.com/krallin/tini){: target="blank" rel="noopener" class="_" }). Either of these wrappers takes care of handling `SIGTERM` properly. +## Can I control service startup order? + +Yes, see [Controlling startup order](startup-order.md). + ## How do I run multiple copies of a Compose file on the same host? Compose uses the project name to create unique identifiers for all of a @@ -61,29 +92,9 @@ project's containers and other resources. To run multiple copies of a project, set a custom project name using the [`-p` command line option](reference/index.md) or the [`COMPOSE_PROJECT_NAME` environment variable](reference/envvars.md#compose_project_name). -## What's the difference between `up`, `run`, and `start`? - -Typically, you want `docker compose up`. Use `up` to start or restart all the -services defined in a `docker-compose.yml`. In the default "attached" -mode, you see all the logs from all the containers. In "detached" mode (`-d`), -Compose exits after starting the containers, but the containers continue to run -in the background. - -The `docker compose run` command is for running "one-off" or "adhoc" tasks. It -requires the service name you want to run and only starts containers for services -that the running service depends on. Use `run` to run tests or perform -an administrative task such as removing or adding data to a data volume -container. The `run` command acts like `docker run -ti` in that it opens an -interactive terminal to the container and returns an exit status matching the -exit status of the process in the container. - -The `docker compose start` command is useful only to restart containers -that were previously created, but were stopped. It never creates new -containers. - ## Can I use JSON instead of YAML for my Compose file? -Yes. [YAML is a superset of JSON](https://stackoverflow.com/a/1729545/444646) so +Yes. [YAML is a superset of JSON](https://stackoverflow.com/a/1729545/444646){: target="blank" rel="noopener" class="_" } so any JSON file should be valid YAML. To use a JSON file with Compose, specify the filename to use, for example: @@ -107,25 +118,6 @@ include the code using a `COPY`, and use a `volume` in your Compose file to include the code from the host during development. The volume overrides the directory contents of the image. -## Where can I find example compose files? - -There are [many examples of Compose files on -GitHub](https://github.com/search?q=in%3Apath+docker-compose.yml+extension%3Ayml&type=Code). - -## Getting help - -Docker Compose is under active development. If you need help, would like to -contribute, or simply want to talk about the project with like-minded -individuals, we have a number of open channels for communication. - -* To report bugs or file feature requests: use the [issue tracker on Github](https://github.com/docker/compose/issues). - -* To talk about the project with people in real time: join the - `#docker-compose` channel on the Docker Community Slack. - -* To contribute code or documentation changes: submit a [pull request on Github](https://github.com/docker/compose/pulls). - - ## Compose documentation - [User guide](index.md) diff --git a/compose/features-uses.md b/compose/features-uses.md index 76e06eafac..c612773b24 100644 --- a/compose/features-uses.md +++ b/compose/features-uses.md @@ -12,7 +12,7 @@ anywhere. 2. Define the services that make up your app in `docker-compose.yml` so they can be run together in an isolated environment. -3. Run `docker compose up` and the [Docker compose command](compose-v2/index.md#compose-v2-and-the-new-docker-compose-command) starts and runs your entire app. You can alternatively run `docker-compose up` using Compose standalone(`docker-compose` binary). +3. Run `docker compose up` and the Docker compose command starts and runs your entire app. You can alternatively run `docker-compose up` using Compose standalone(`docker-compose` binary). A `docker-compose.yml` looks like this: diff --git a/compose/gettingstarted.md b/compose/gettingstarted.md index 9d936790a8..d879c60aa5 100644 --- a/compose/gettingstarted.md +++ b/compose/gettingstarted.md @@ -228,7 +228,7 @@ services: volumes: - .:/code environment: - FLASK_DEBUG: True + FLASK_DEBUG: "true" redis: image: "redis:alpine" ``` diff --git a/compose/gpu-support.md b/compose/gpu-support.md index 0ff1f13521..efb4f33334 100644 --- a/compose/gpu-support.md +++ b/compose/gpu-support.md @@ -4,46 +4,35 @@ keywords: documentation, docs, docker, compose, GPU access, NVIDIA, samples title: Enabling GPU access with Compose --- -Compose services can define GPU device reservations if the Docker host contains such devices and the Docker Daemon is set accordingly. For this, make sure to install the [prerequisites](../config/containers/resource_constraints.md#gpu) if you have not already done so. +Compose services can define GPU device reservations if the Docker host contains such devices and the Docker Daemon is set accordingly. For this, make sure you install the [prerequisites](../config/containers/resource_constraints.md#gpu){: target="_blank" rel="noopener" class="_" } if you have not already done so. The examples in the following sections focus specifically on providing service containers access to GPU devices with Docker Compose. -You can use either `docker-compose` or `docker compose` commands. -See also, [Compose command compatibility with docker-compose](cli-command-compatibility.md). - -### Use of service `runtime` property from Compose v2.3 format (legacy) - -Docker Compose v1.27.0+ switched to using the Compose Specification schema which is a combination of all properties from 2.x and 3.x versions. This re-enabled the use of service properties as [runtime](/compose-file/compose-file-v2.md#runtime) to provide GPU access to service containers. However, this does not allow to have control over specific properties of the GPU devices. - -```yaml -services: - test: - image: nvidia/cuda:10.2-base - command: nvidia-smi - runtime: nvidia - -``` +You can use either `docker-compose` or `docker compose` commands. For more information, see [Evolution of Compose](compose-v2/index.md){: target="_blank" rel="noopener" class="_" }. ### Enabling GPU access to service containers -Docker Compose v1.28.0+ allows to define GPU reservations using the [device](https://github.com/compose-spec/compose-spec/blob/master/deploy.md#devices) structure defined in the Compose Specification. This provides more granular control over a GPU reservation as custom values can be set for the following device properties: +GPUs are referenced in a `docker-compose.yml` file using the [device](compose-file/deploy.md#devices){:target="_blank" rel="noopener" class="_"} structure, within your services that need them. -- [capabilities](https://github.com/compose-spec/compose-spec/blob/master/deploy.md#capabilities){:target="_blank" rel="noopener" class="_"} - value specifies as a list of strings (eg. `capabilities: [gpu]`). You must set this field in the Compose file. Otherwise, it returns an error on service deployment. -- [count](https://github.com/compose-spec/compose-spec/blob/master/deploy.md#count){:target="_blank" rel="noopener" class="_"} - value specified as an int or the value `all` representing the number of GPU devices that should be reserved ( providing the host holds that number of GPUs). -- [device_ids](https://github.com/compose-spec/compose-spec/blob/master/deploy.md#device_ids){:target="_blank" rel="noopener" class="_"} - value specified as a list of strings representing GPU device IDs from the host. You can find the device ID in the output of `nvidia-smi` on the host. -- [driver](https://github.com/compose-spec/compose-spec/blob/master/deploy.md#driver){:target="_blank" rel="noopener" class="_"} - value specified as a string (eg. `driver: 'nvidia'`) -- [options](https://github.com/compose-spec/compose-spec/blob/master/deploy.md#options){:target="_blank" rel="noopener" class="_"} - key-value pairs representing driver specific options. +This provides more granular control over a GPU reservation as custom values can be set for the following device properties: + +- `capabilities`. This value specifies as a list of strings (eg. `capabilities: [gpu]`). You must set this field in the Compose file. Otherwise, it returns an error on service deployment. +- `count`. This value specified as an integer or the value `all` representing the number of GPU devices that should be reserved (providing the host holds that number of GPUs). If no `count` is set, all GPUs available on the host are used by default. +- `device_ids`. This value specified as a list of strings representing GPU device IDs from the host. You can find the device ID in the output of `nvidia-smi` on the host. If no `device_ids` are set, all GPUs available on the host used by default. +- `driver`. This value is specified as a string, for example `driver: 'nvidia'` +- `options`. Key-value pairs representing driver specific options. -> **Note** +> **Important** > > You must set the `capabilities` field. Otherwise, it returns an error on service deployment. > > `count` and `device_ids` are mutually exclusive. You must only define one field at a time. +{: .important} -For more information on these properties, see the `deploy` section in the [Compose Specification](https://github.com/compose-spec/compose-spec/blob/master/deploy.md#devices){:target="_blank" rel="noopener" class="_"}. +For more information on these properties, see the `deploy` section in the [Compose Specification](compose-file/deploy.md#devices){:target="_blank" rel="noopener" class="_"}. -Example of a Compose file for running a service with access to 1 GPU device: +#### Example of a Compose file for running a service with access to 1 GPU device: ```yaml services: @@ -89,34 +78,9 @@ gpu_test_1 exited with code 0 ``` -If no `count` or `device_ids` are set, all GPUs available on the host are going to be used by default. +On machines hosting multiple GPUs, `device_ids` field can be set to target specific GPU devices and `count` can be used to limit the number of GPU devices assigned to a service container. -```yaml -services: - test: - image: tensorflow/tensorflow:latest-gpu - command: python -c "import tensorflow as tf;tf.test.gpu_device_name()" - deploy: - resources: - reservations: - devices: - - capabilities: [gpu] -``` - -```console -$ docker compose up -Creating network "gpu_default" with the default driver -Creating gpu_test_1 ... done -Attaching to gpu_test_1 -test_1 | I tensorflow/stream_executor/platform/default/dso_loader.cc:48] Successfully opened dynamic library libcudart.so.10.1 -..... -test_1 | I tensorflow/core/common_runtime/gpu/gpu_device.cc:1402] -Created TensorFlow device (/device:GPU:0 with 13970 MB memory) -> physical GPU (device: 0, name: Tesla T4, pci bus id: 0000:00:1e.0, compute capability: 7.5) -test_1 | /device:GPU:0 -gpu_test_1 exited with code 0 -``` - -On machines hosting multiple GPUs, `device_ids` field can be set to target specific GPU devices and `count` can be used to limit the number of GPU devices assigned to a service container. If `count` exceeds the number of available GPUs on the host, the deployment will error out. +You can use `count` or `device_ids` in each of your service definitions. An error is returned if you try to combine both, specify an invalid device ID, or use a value of count that’s higher than the number of GPUs in your system. ```console $ nvidia-smi @@ -145,6 +109,8 @@ $ nvidia-smi +-------------------------------+----------------------+----------------------+ ``` +### Access specific devices + To enable access only to GPU-0 and GPU-3 devices: ```yaml @@ -161,13 +127,3 @@ services: capabilities: [gpu] ``` - -```sh -$ docker compose up -... -Created TensorFlow device (/device:GPU:0 with 13970 MB memory -> physical GPU (device: 0, name: Tesla T4, pci bus id: 0000:00:1b.0, compute capability: 7.5) -... -Created TensorFlow device (/device:GPU:1 with 13970 MB memory) -> physical GPU (device: 1, name: Tesla T4, pci bus id: 0000:00:1e.0, compute capability: 7.5) -... -gpu_test_1 exited with code 0 -``` diff --git a/compose/networking.md b/compose/networking.md index 7555bfaea6..5b8675a59c 100644 --- a/compose/networking.md +++ b/compose/networking.md @@ -4,25 +4,22 @@ keywords: documentation, docs, docker, compose, orchestration, containers, netwo title: Networking in Compose --- -> This page applies to Compose file formats [version 2](compose-file/compose-file-v2.md) and [higher](compose-file/index.md). Networking features are not supported for Compose file version 1 (deprecated). - By default Compose sets up a single -[network](../engine/reference/commandline/network_create.md) for your app. Each -container for a service joins the default network and is both *reachable* by -other containers on that network, and *discoverable* by them at a hostname +[network](../engine/reference/commandline/network_create.md){: target="_blank" rel="noopener" class="_" } for your app. Each +container for a service joins the default network and is both reachable by +other containers on that network, and discoverable by them at a hostname identical to the container name. > **Note** > > Your app's network is given a name based on the "project name", > which is based on the name of the directory it lives in. You can override the -> project name with either the [`--project-name` flag](reference/index.md) -> or the [`COMPOSE_PROJECT_NAME` environment variable](reference/envvars.md#compose_project_name). +> project name with either the [`--project-name` flag](reference/index.md){: target="_blank" rel="noopener" class="_" } +> or the [`COMPOSE_PROJECT_NAME` environment variable](reference/envvars.md#compose_project_name){: target="_blank" rel="noopener" class="_" }. For example, suppose your app is in a directory called `myapp`, and your `docker-compose.yml` looks like this: ```yaml -version: "{{ site.compose_file_v3 }}" services: web: build: . @@ -42,14 +39,6 @@ When you run `docker compose up`, the following happens: 3. A container is created using `db`'s configuration. It joins the network `myapp_default` under the name `db`. -> **In v2.1+, overlay networks are always `attachable`** -> -> Starting in Compose file format 2.1, overlay networks are always created as -> `attachable`, and this is not configurable. This means that standalone -> containers can connect to overlay networks. -> -> In Compose file format 3.x, you can optionally set the `attachable` property -> to `false`. Each container can now look up the hostname `web` or `db` and get back the appropriate container's IP address. For example, `web`'s @@ -66,18 +55,22 @@ Within the `web` container, your connection string to `db` would look like `postgres://db:5432`, and from the host machine, the connection string would look like `postgres://{DOCKER_IP}:8001`. -## Update containers +## Update containers on the network If you make a configuration change to a service and run `docker compose up` to update it, the old container is removed and the new one joins the network under a different IP address but the same name. Running containers can look up that name and connect to the new address, but the old address stops working. If any containers have connections open to the old container, they are closed. It is a container's responsibility to detect this condition, look up the name again and reconnect. -## Links +> **Tip** +> +> Reference containers by name, not IP, whenever possible. Otherwise you’ll need to constantly update the IP address you use. +{: .tip } -Links allow you to define extra aliases by which a service is reachable from another service. They are not required to enable services to communicate - by default, any service can reach any other service at that service's name. In the following example, `db` is reachable from `web` at the hostnames `db` and `database`: +## Link containers + +Links allow you to define extra aliases by which a service is reachable from another service. They are not required to enable services to communicate. By default, any service can reach any other service at that service's name. In the following example, `db` is reachable from `web` at the hostnames `db` and `database`: ```yaml -version: "{{ site.compose_file_v3 }}" services: web: @@ -88,13 +81,15 @@ services: image: postgres ``` -See the [links reference](compose-file/compose-file-v2.md#links) for more information. +See the [links reference](compose-file/index.md#links) for more information. ## Multi-host networking When deploying a Compose application on a Docker Engine with [Swarm mode enabled](../engine/swarm/index.md), you can make use of the built-in `overlay` driver to enable multi-host communication. +Overlay networks are always created as `attachable`. You can optionally set the [`attachable`](compose-file/index.md#attachable) property to `false`. + Consult the [Swarm mode section](../engine/swarm/index.md), to see how to set up a Swarm cluster, and the [Getting started with multi-host networking](../network/network-tutorial-overlay.md) to learn about multi-host overlay networks. @@ -103,13 +98,11 @@ to learn about multi-host overlay networks. Instead of just using the default app network, you can specify your own networks with the top-level `networks` key. This lets you create more complex topologies and specify [custom network drivers](/engine/extend/plugins_network/) and options. You can also use it to connect services to externally-created networks which aren't managed by Compose. -Each service can specify what networks to connect to with the *service-level* `networks` key, which is a list of names referencing entries under the *top-level* `networks` key. +Each service can specify what networks to connect to with the service-level `networks` key, which is a list of names referencing entries under the top-level `networks` key. -Here's an example Compose file defining two custom networks. The `proxy` service is isolated from the `db` service, because they do not share a network in common - only `app` can talk to both. +The following example shows a Compose file which defines two custom networks. The `proxy` service is isolated from the `db` service, because they do not share a network in common. Only `app` can talk to both. ```yaml -version: "{{ site.compose_file_v3 }}" - services: proxy: build: ./proxy @@ -137,12 +130,11 @@ networks: bar: "2" ``` -Networks can be configured with static IP addresses by setting the [ipv4_address and/or ipv6_address](compose-file/compose-file-v2.md#ipv4_address-ipv6_address) for each attached network. +Networks can be configured with static IP addresses by setting the [ipv4_address and/or ipv6_address](compose-file/index.md#ipv4_address-ipv6_address) for each attached network. -Networks can also be given a [custom name](compose-file/compose-file-v3.md#network-configuration-reference) (since version 3.5): +Networks can also be given a [custom name](compose-file/index.md#name): ```yaml -version: "{{ site.compose_file_v3 }}" services: # ... networks: @@ -151,17 +143,11 @@ networks: driver: custom-driver-1 ``` -For full details of the network configuration options available, see the following references: - -- [Top-level `networks` key](compose-file/compose-file-v2.md#network-configuration-reference) -- [Service-level `networks` key](compose-file/compose-file-v2.md#networks) - ## Configure the default network -Instead of (or as well as) specifying your own networks, you can also change the settings of the app-wide default network by defining an entry under `networks` named `default`: +Instead of, or as well as, specifying your own networks, you can also change the settings of the app-wide default network by defining an entry under `networks` named `default`: ```yaml -version: "{{ site.compose_file_v3 }}" services: web: build: . @@ -178,15 +164,21 @@ networks: ## Use a pre-existing network -If you want your containers to join a pre-existing network, use the [`external` option](compose-file/compose-file-v2.md#network-configuration-reference): - +If you want your containers to join a pre-existing network, use the [`external` option](compose-file/index.md#external) ```yaml services: # ... networks: - default: + network1: name: my-pre-existing-network external: true ``` -Instead of attempting to create a network called `[projectname]_default`, Compose looks for a network called `my-pre-existing-network` and connect your app's containers to it. +Instead of attempting to create a network called `[projectname]_default`, Compose looks for a network called `my-pre-existing-network` and connects your app's containers to it. + +## Further reference information + +For full details of the network configuration options available, see the following references: + +- [Top-level `networks` key](compose-file/index.md#networks-top-level-element) +- [Service-level `networks` key](compose-file/index.md#networks) diff --git a/compose/production.md b/compose/production.md index a9d4601f24..f9de696919 100644 --- a/compose/production.md +++ b/compose/production.md @@ -14,24 +14,23 @@ up your application, you can run Compose apps on a Swarm cluster. ### Modify your Compose file for production -You probably need to make changes to your app configuration to make it ready for -production. These changes may include: +You may need to make changes to your app configuration to make it ready for +production. These changes might include: - Removing any volume bindings for application code, so that code stays inside the container and can't be changed from outside - Binding to different ports on the host - Setting environment variables differently, such as reducing the verbosity of logging, or to specify settings for external services such as an email server -- Specifying a restart policy like `restart: always` to avoid downtime +- Specifying a restart policy like [`restart: always`](compose-file/index.md#restart){: target="_blank" rel="noopener" class="_" } to avoid downtime - Adding extra services such as a log aggregator For this reason, consider defining an additional Compose file, say `production.yml`, which specifies production-appropriate -configuration. This configuration file only needs to include the changes you'd -like to make from the original Compose file. The additional Compose file -can be applied over the original `docker-compose.yml` to create a new configuration. +configuration. This configuration file only needs to include the changes you want to make from the original Compose file. The additional Compose file +is then applied over the original `docker-compose.yml` to create a new configuration. -Once you've got a second configuration file, tell Compose to use it with the +Once you have a second configuration file, you can use it with the `-f` option: ```console @@ -52,24 +51,21 @@ $ docker compose build web $ docker compose up --no-deps -d web ``` -This first rebuilds the image for `web` and then stop, destroy, and recreate -*just* the `web` service. The `--no-deps` flag prevents Compose from also +This first command rebuilds the image for `web` and then stops, destroys, and recreates +just the `web` service. The `--no-deps` flag prevents Compose from also recreating any services which `web` depends on. ### Running Compose on a single server You can use Compose to deploy an app to a remote Docker host by setting the `DOCKER_HOST`, `DOCKER_TLS_VERIFY`, and `DOCKER_CERT_PATH` environment variables -appropriately. See also [Compose CLI environment variables](../compose/reference/envvars.md). +appropriately. See also [Compose CLI environment variables](reference/envvars.md). Once you've set up your environment variables, all the normal `docker compose` commands work with no further configuration. -## Compose documentation +## What's new? -- [User guide](index.md) -- [Installing Compose](install/index.md) -- [Getting Started](gettingstarted.md) - [Command line reference](reference/index.md) - [Compose file reference](compose-file/index.md) - [Sample apps with Compose](samples-for-compose.md) diff --git a/compose/profiles.md b/compose/profiles.md index 1429445934..f8c3cacfd3 100644 --- a/compose/profiles.md +++ b/compose/profiles.md @@ -4,20 +4,20 @@ desription: Using profiles with Compose keywords: cli, compose, profile, profiles reference --- -Profiles allow adjusting the Compose application model for various usages and +Profiles help you adjust the Compose application model for various uses and environments by selectively enabling services. This is achieved by assigning each service to zero or more profiles. If -unassigned, the service is _always_ started but if assigned, it is only started +unassigned, the service is always started but if assigned, it is only started if the profile is activated. -This allows one to define additional services in a single `docker-compose.yml` file -that should only be started in specific scenarios, e.g. for debugging or +This allows you to define additional services in a single `docker-compose.yml` file +that should only be started in specific scenarios, for example for debugging or development tasks. ## Assigning profiles to services Services are associated with profiles through the -[`profiles` attribute](compose-file/compose-file-v3.md#profiles) which takes an +[`profiles` attribute](compose-file/index.md#profiles) which takes an array of profile names: ```yaml @@ -45,44 +45,52 @@ Here the services `frontend` and `phpmyadmin` are assigned to the profiles `frontend` and `debug` respectively and as such are only started when their respective profiles are enabled. -Services without a `profiles` attribute will _always_ be enabled, i.e. in this +Services without a `profiles` attribute are always enabled. In this case running `docker compose up` would only start `backend` and `db`. -Valid profile names follow the regex format of `[a-zA-Z0-9][a-zA-Z0-9_.-]+`. +Valid profiles names follow the regex format of `[a-zA-Z0-9][a-zA-Z0-9_.-]+`. -> **Note** +> **Tip** > -> The core services of your application should not be assigned `profiles` so -> they will always be enabled and automatically started. +> The core services of your application shouldn't be assigned `profiles` so +> they are always enabled and automatically started. +{: .tip} -## Enabling profiles +## Enable profiles -To enable a profile supply the `--profile` [command-line option](reference/index.md) or +To enable profiles supply the `--profile` [command-line option](reference/index.md) or use the [`COMPOSE_PROFILES` environment variable](reference/envvars.md#compose_profiles): -```sh +```console $ docker compose --profile debug up +``` +```console $ COMPOSE_PROFILES=debug docker compose up ``` -The above command would both start your application with the `debug` profile enabled. -Using the `docker-compose.yml` file above, this would start the services `backend`, +The above commands would both start your application with the `debug` profile enabled. +In the example, `docker-compose.yml` file above, this starts the services `backend`, `db` and `phpmyadmin`. +### Enable multiple profiles + Multiple profiles can be specified by passing multiple `--profile` flags or a comma-separated list for the `COMPOSE_PROFILES` environment variable: -```sh +```console $ docker compose --profile frontend --profile debug up +``` + +```console $ COMPOSE_PROFILES=frontend,debug docker compose up ``` ## Auto-enabling profiles and dependency resolution When a service with assigned `profiles` is explicitly targeted on the command -line its profiles will be enabled automatically so you don't need to enable them +line its profiles are enabled automatically so you don't need to enable them manually. This can be used for one-off services and debugging tools. -As an example consider this configuration: +As an example consider the folowing configuration: ```yaml version: "{{ site.compose_file_v3 }}" @@ -103,19 +111,20 @@ services: ``` ```sh -# will only start backend and db +# Only start backend and db $ docker compose up -d -# this will run db-migrations (and - if necessary - start db) -# by implicitly enabling profile `tools` +# This runs db-migrations (and,if necessary, start db) +# by implicitly enabling the profiles `tools` $ docker compose run db-migrations ``` -But keep in mind that `docker compose` will only automatically enable the -profiles of the services on the command line and not of any dependencies. This -means that all services the targeted service `depends_on` must have a common -profile with it, be always enabled (by omitting `profiles`) or have a matching -profile enabled explicitly: +But keep in mind that `docker compose` only automatically enables the +profiles of the services on the command line and not of any dependencies. + +This means that any other services the targeted service `depends_on` should either: +- Share a common profile +- Always be enabled, by omitting `profiles` or having a matching profile enabled explicitly ```yaml version: "{{ site.compose_file_v3 }}" @@ -141,20 +150,20 @@ services: ``` ```sh -# will only start "web" +# Only start "web" $ docker compose up -d -# this will start mock-backend (and - if necessary - db) -# by implicitly enabling profile `dev` +# Start mock-backend (and, if necessary, db) +# by implicitly enabling profiles `dev` $ docker compose up -d mock-backend -# this will fail because profile "dev" is disabled +# This fails because profiles "dev" is disabled $ docker compose up phpmyadmin ``` -Although targeting `phpmyadmin` will automatically enable its profiles - i.e. -`debug` - it will not automatically enable the profile(s) required by `db` - -i.e. `dev`. To fix this you either have to add the `debug` profile to the `db` service: +Although targeting `phpmyadmin` automatically enables the profiles `debug`, it doesn't automatically enable the profiles required by `db` which is `dev`. + +To fix this you either have to add the `debug` profile to the `db` service: ```yaml db: @@ -164,18 +173,13 @@ db: or enable a profile of `db` explicitly: -```sh -# profile "debug" is enabled automatically by targeting phpmyadmin +```console +# Profiles "debug" is enabled automatically by targeting phpmyadmin $ docker compose --profile dev up phpmyadmin $ COMPOSE_PROFILES=dev docker compose up phpmyadmin ``` -## Compose documentation +## Reference information -- [User guide](index.md) -- [Installing Compose](install/index.md) -- [Getting Started](gettingstarted.md) -- [Command line reference](reference/index.md) -- [Compose file reference](compose-file/index.md) -- [Sample apps with Compose](samples-for-compose.md) +[`profiles`](compose-file/index.md#profiles) diff --git a/compose/release-notes.md b/compose/release-notes.md index 8a0ade5204..9f3f88446c 100644 --- a/compose/release-notes.md +++ b/compose/release-notes.md @@ -6,6 +6,53 @@ toc_max: 2 redirect_from: - /release-notes/docker-compose/ --- +## 2.15.1 +{% include release-date.html date="2023-01-09" %} +### Update +- Dependencies upgrade to fix Golan CVE-2022-27664 and CVE-2022-32149 + +### Bug fixes and enhancements +* Added support for UTS namespace. Fixed [compose#8408](https://github.com/docker/compose/issues/8408){: + target="_blank" rel="noopener" class="_"} +* Fixed filtering issue when no filter set. Fixed [roadmap#418](https://github.com/docker/roadmap/issues/418){: + target="_blank" rel="noopener" class="_"} +* Fixed concurrent map writes issue during build step. Pull Request [compose#10151](https://github.com/docker/compose/pull/10151){: + target="_blank" rel="noopener" class="_"} +* Fixed issue when stdin is not a terminal. Fixed [compose#9739](https://github.com/docker/compose/issues/9739){: + target="_blank" rel="noopener" class="_"} + +## 2.15.0 +{% include release-date.html date="2023-01-05" %} +### Update +- Dependencies upgrade: bump compose-go to v1.8.1 +- Dependencies upgrade: bump cli-docs-tool to 0.5.1 + +### Bug fixes and enhancements +* Added support of the `privileged` attribute in the `service.build` section. Pull Request [compose#10112](https://github.com/docker/compose/pull/10112){: + target="_blank" rel="noopener" class="_"} +* Introduced `--ignore-buildable` to ignore buildable images on pull. Fixed [compose#8805](https://github.com/docker/compose/issues/8805){: + target="_blank" rel="noopener" class="_"} +* Introduceed `--no-attach` to ignore some service outputs. Fixed [compose#8546](https://github.com/docker/compose/issues/8546){: + target="_blank" rel="noopener" class="_"} +* Fixed issue with `logs` when `driver:none` is set. Fixed [compose#9030](https://github.com/docker/compose/issues/9030){: + target="_blank" rel="noopener" class="_"} +* Compose now relies on dockerCLI.streams. Pull Request [compose#10082](https://github.com/docker/compose/pull/10082){: + target="_blank" rel="noopener" class="_"} +* Fixed issue with service hash that MUST exclude replicas. Fixed [compose#10077](https://github.com/docker/compose/issues/10077){: + target="_blank" rel="noopener" class="_"} +* Compose now checks service names based on project, not running containers. Fixed [compose#9951](https://github.com/docker/compose/issues/9951){: + target="_blank" rel="noopener" class="_"} +* Fixed security opts support (seccomp and unconfined). Fixed [compose#9505](https://github.com/docker/compose/issues/9505){: + target="_blank" rel="noopener" class="_"} +* Fixed empty file when using compose config in case of smaller source files. Fixed [compose#10121](https://github.com/docker/compose/issues/10121){: + target="_blank" rel="noopener" class="_"} +* Fixed issue with `--pull` not applied on `compose up`. Fixed [compose#10125](https://github.com/docker/compose/issues/10125){: + target="_blank" rel="noopener" class="_"} +* Compose should ignore not only auto-removed containers but also "removal in progress" for orphan containers. Pull Request [compose#10136](https://github.com/docker/compose/pull/10136){: + target="_blank" rel="noopener" class="_"} +* Compose limits build concurrency according to `--parallel`. Fixed [compose#9091](https://github.com/docker/compose/issues/9091){: + target="_blank" rel="noopener" class="_"} + ## 2.14.2 {% include release-date.html date="2022-12-20" %} ### Update diff --git a/compose/startup-order.md b/compose/startup-order.md index 8684e9f679..10e9dd08a0 100644 --- a/compose/startup-order.md +++ b/compose/startup-order.md @@ -6,102 +6,24 @@ notoc: true --- You can control the order of service startup and shutdown with the -[depends_on](compose-file/compose-file-v3.md#depends_on) option. Compose always starts and stops +[depends_on](compose-file/index.md#depends_on) option. Compose always starts and stops containers in dependency order, where dependencies are determined by `depends_on`, `links`, `volumes_from`, and `network_mode: "service:..."`. -However, for startup Compose does not wait until a container is "ready" (whatever that means -for your particular application) - only until it's running. There's a good -reason for this. +A good example of when you might use this is an application which needs to access a database. If both services are started with `docker compose up`, there is a chance this will fail since the application service might start before the database service and won't find a database able to handle its SQL statements. -The problem of waiting for a database (for example) to be ready is really just -a subset of a much larger problem of distributed systems. In production, your -database could become unavailable or move hosts at any time. Your application -needs to be resilient to these types of failures. +## Control startup -To handle this, design your application to attempt to re-establish a connection to -the database after a failure. If the application retries the connection, -it can eventually connect to the database. +On startup, Compose does not wait until a container is "ready", only until it's running. This can cause issues if, for example you have a relational database system that needs to start its own services before being able to handle incoming connections. -The best solution is to perform this check in your application code, both at -startup and whenever a connection is lost for any reason. However, if you don't -need this level of resilience, you can work around the problem with a wrapper -script: +The solution for detecting the ready state of a service is to use the `condition` attribute with one of the following options: -- Use a tool such as [wait-for-it](https://github.com/vishnubob/wait-for-it), - [dockerize](https://github.com/powerman/dockerize), [Wait4X](https://github.com/atkrad/wait4x), sh-compatible - [wait-for](https://github.com/Eficode/wait-for), or [RelayAndContainers](https://github.com/jasonsychau/RelayAndContainers) template. These are small - wrapper scripts which you can include in your application's image to - poll a given host and port until it's accepting TCP connections. +- `service_started` +- `service_healthy`. This specifies that a dependency is expected to be “healthy”, which is defined with `healthcheck`, before starting a dependent service. +- `service_completed_successfully`. This specifies that a dependency is expected to run to successful completion before starting a dependent service. - For example, to use `wait-for-it.sh` or `wait-for` to wrap your service's command: +## Reference information - ```yaml - version: "2" - services: - web: - build: . - ports: - - "80:8000" - depends_on: - - "db" - command: ["./wait-for-it.sh", "db:5432", "--", "python", "app.py"] - db: - image: postgres - ``` +- [`depends_on`](compose-file/index.md#depends_on) +- [`healthcheck`](compose-file/index.md#healthcheck) - > **Tip** - > - > There are limitations to this first solution. For example, it doesn't verify - > when a specific service is really ready. If you add more arguments to the - > command, use the `bash shift` command with a loop, as shown in the next - > example. - -- Alternatively, write your own wrapper script to perform a more application-specific - health check. For example, you might want to wait until Postgres is ready to - accept commands: - - ```bash - #!/bin/sh - # wait-for-postgres.sh - - set -e - - host="$1" - # Shift arguments with mapping: - # - $0 => $0 - # - $1 => - # - $2 => $1 - # - $3 => $2 - # - ... - # This is done for `exec "$@"` below to work correctly - shift - - # Login for user (`-U`) and once logged in execute quit ( `-c \q` ) - # If we can not login sleep for 1 sec - until PGPASSWORD=$POSTGRES_PASSWORD psql -h "$host" -U "postgres" -c '\q'; do - >&2 echo "Postgres is unavailable - sleeping" - sleep 1 - done - - >&2 echo "Postgres is up - executing command" - # Print and execute all other arguments starting with `$1` - # So `exec "$1" "$2" "$3" ...` - exec "$@" - ``` - - You can use this as a wrapper script as in the previous example, by setting: - - ```yaml - command: ["./wait-for-postgres.sh", "db", "python", "app.py"] - ``` - - -## Compose documentation - -- [User guide](index.md) -- [Installing Compose](install/index.md) -- [Getting Started](gettingstarted.md) -- [Command line reference](reference/index.md) -- [Compose file reference](compose-file/index.md) -- [Sample apps with Compose](samples-for-compose.md) diff --git a/config/containers/container-networking.md b/config/containers/container-networking.md index a7283e7317..0872275b25 100644 --- a/config/containers/container-networking.md +++ b/config/containers/container-networking.md @@ -3,75 +3,77 @@ title: Container networking description: How networking works from the container's point of view keywords: networking, container, standalone redirect_from: -- /engine/userguide/networking/configure-dns/ -- /engine/userguide/networking/default_network/configure-dns/ -- /engine/userguide/networking/default_network/binding/ -- /engine/userguide/networking/default_network/container-communication/ + - /engine/userguide/networking/configure-dns/ + - /engine/userguide/networking/default_network/configure-dns/ + - /engine/userguide/networking/default_network/binding/ + - /engine/userguide/networking/default_network/container-communication/ --- -The type of network a container uses, whether it is a [bridge](../../network/bridge.md), an -[overlay](../../network/overlay.md), a [macvlan network](../../network/macvlan.md), or a custom network -plugin, is transparent from within the container. From the container's point of -view, it has a network interface with an IP address, a gateway, a routing table, -DNS services, and other networking details (assuming the container is not using -the `none` network driver). This topic is about networking concerns from the -point of view of the container. +A container has no information about what kind of network it's attached to, +whether it's a [bridge](../../network/bridge.md), an [overlay](../../network/overlay.md), +a [macvlan network](../../network/macvlan.md), or a custom network plugin. +A container only sees a network interface with an IP address, +a gateway, a routing table, DNS services, and other networking details. +That is, unless the container uses the `none` network driver. +This page describes networking from the point of view of the container. ## Published ports By default, when you create or run a container using `docker create` or `docker run`, -it does not publish any of its ports to the outside world. To make a port available -to services outside of Docker, or to Docker containers which are not connected to -the container's network, use the `--publish` or `-p` flag. This creates a firewall -rule which maps a container port to a port on the Docker host to the outside world. -Here are some examples. +the container doesn't expose any of it's ports to the outside world. +To make a port available to services outside of Docker, +or to Docker containers running on a different network, +use the `--publish` or `-p` flag. +This creates a firewall rule in the container, +mapping a container port to a port on the Docker host to the outside world. +Here are some examples: -| Flag value | Description | -|---------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------| -| `-p 8080:80` | Map TCP port 80 in the container to port 8080 on the Docker host. | -| `-p 192.168.1.100:8080:80` | Map TCP port 80 in the container to port 8080 on the Docker host for connections to host IP 192.168.1.100. | -| `-p 8080:80/udp` | Map UDP port 80 in the container to port 8080 on the Docker host. | -| `-p 8080:80/tcp -p 8080:80/udp` | Map TCP port 80 in the container to TCP port 8080 on the Docker host, and map UDP port 80 in the container to UDP port 8080 on the Docker host. | +| Flag value | Description | +| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| `-p 8080:80` | Map TCP port 80 in the container to port `8080` on the Docker host. | +| `-p 192.168.1.100:8080:80` | Map TCP port 80 in the container to port `8080` on the Docker host for connections to host IP `192.168.1.100`. | +| `-p 8080:80/udp` | Map UDP port 80 in the container to port `8080` on the Docker host. | +| `-p 8080:80/tcp -p 8080:80/udp` | Map TCP port 80 in the container to TCP port `8080` on the Docker host, and map UDP port `80` in the container to UDP port `8080` on the Docker host. | ## IP address and hostname -By default, the container is assigned an IP address for every Docker network it -connects to. The IP address is assigned from the pool assigned to -the network, so the Docker daemon effectively acts as a DHCP server for each -container. Each network also has a default subnet mask and gateway. +By default, the container gets an IP address for every Docker network it attaches to. +A container receives an IP address out of the IP pool of the network it attaches to. +The Docker daemon effectively acts as a DHCP server for each container. +Each network also has a default subnet mask and gateway. -When the container starts, it can only be connected to a single network, using -`--network`. However, you can connect a running container to multiple -networks using `docker network connect`. When you start a container using the -`--network` flag, you can specify the IP address assigned to the container on -that network using the `--ip` or `--ip6` flags. +When a container starts, it can only attach to a single network, using the `--network` flag. +You can connect a running container to multiple networks using the `docker network connect` command. +When you start a container using the `--network` flag, +you can specify the IP address for the container on that network using the `--ip` or `--ip6` flags. -When you connect an existing container to a different network using -`docker network connect`, you can use the `--ip` or `--ip6` flags on that -command to specify the container's IP address on the additional network. +When you connect an existing container to a different network using `docker network connect`, +you can use the `--ip` or `--ip6` flags on that command +to specify the container's IP address on the additional network. -In the same way, a container's hostname defaults to be the container's ID in -Docker. You can override the hostname using `--hostname`. When connecting to an -existing network using `docker network connect`, you can use the `--alias` -flag to specify an additional network alias for the container on that network. +In the same way, a container's hostname defaults to be the container's ID in Docker. +You can override the hostname using `--hostname`. +When connecting to an existing network using `docker network connect`, +you can use the `--alias` flag to specify an additional network alias for the container on that network. ## DNS services -By default, a container inherits the DNS settings of the host, as defined in the -`/etc/resolv.conf` configuration file. Containers that use the default `bridge` -network get a copy of this file, whereas containers that use a +By default, containers inherit the DNS settings of the host, as defined in the `/etc/resolv.conf` configuration file. +Containers that attach to the default `bridge` network receive a copy of this file. +Containers that attach to a [custom network](../../network/network-tutorial-standalone.md#use-user-defined-bridge-networks) -use Docker's embedded DNS server, which forwards external DNS lookups to the DNS -servers configured on the host. +use Docker's embedded DNS server. +The embedded DNS server forwards external DNS lookups to the DNS servers configured on the host. -Custom hosts defined in `/etc/hosts` are not inherited. To pass additional hosts -into your container, refer to [add entries to container hosts file](../../engine/reference/commandline/run.md#add-entries-to-container-hosts-file---add-host) -in the `docker run` reference documentation. You can override these settings on -a per-container basis. +Custom hosts, defined in `/etc/hosts` on the host machine, aren't inherited by containers. +To pass additional hosts into container, refer to +[add entries to container hosts file](../../engine/reference/commandline/run.md#add-host) +in the `docker run` reference documentation. +You can override these settings on a per-container basis. | Flag | Description | -|----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `--dns` | The IP address of a DNS server. To specify multiple DNS servers, use multiple `--dns` flags. If the container cannot reach any of the IP addresses you specify, Google's public DNS server `8.8.8.8` is added, so that your container can resolve internet domains. | +| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `--dns` | The IP address of a DNS server. To specify multiple DNS servers, use multiple `--dns` flags. If the container can't reach any of the IP addresses you specify, it uses Google's public DNS server at `8.8.8.8`. This allows containers to resolve internet domains. | | `--dns-search` | A DNS search domain to search non-fully-qualified hostnames. To specify multiple DNS search prefixes, use multiple `--dns-search` flags. | | `--dns-opt` | A key-value pair representing a DNS option and its value. See your operating system's documentation for `resolv.conf` for valid options. | | `--hostname` | The hostname a container uses for itself. Defaults to the container's ID if not specified. | diff --git a/config/containers/logging/splunk.md b/config/containers/logging/splunk.md index 6ffba4f4cf..9391796aa1 100644 --- a/config/containers/logging/splunk.md +++ b/config/containers/logging/splunk.md @@ -131,6 +131,7 @@ For example: "line": "my message" } ``` + ```json { "attrs": { @@ -161,6 +162,7 @@ object. If it cannot parse the message, it is sent `inline`. For example: "line": "my message" } ``` + ```json { "attrs": { diff --git a/config/daemon/logs.md b/config/daemon/logs.md index 2a6c590e82..fef7efe254 100644 --- a/config/daemon/logs.md +++ b/config/daemon/logs.md @@ -118,7 +118,6 @@ Look in the Docker logs for a message like the following: ```none ...goroutine stacks written to /var/run/docker/goroutine-stacks-2017-06-02T193336z.log -...daemon datastructure dump written to /var/run/docker/daemon-data-2017-06-02T193336z.log ``` The locations where Docker saves these stack traces and dumps depends on your diff --git a/config/daemon/prometheus.md b/config/daemon/prometheus.md index 8371571bac..fb1b34d047 100644 --- a/config/daemon/prometheus.md +++ b/config/daemon/prometheus.md @@ -36,7 +36,7 @@ exist, create it. - **Linux**: `/etc/docker/daemon.json` - **Windows Server**: `C:\ProgramData\docker\config\daemon.json` - **Docker Desktop for Mac / Docker Desktop for Windows**: Click the Docker icon in the toolbar, - select **Preferences**, then select **Daemon**. Click **Advanced**. + select **Settings**, then select **Daemon**. Click **Advanced**. If the file is currently empty, paste the following: diff --git a/config/labels-custom-metadata.md b/config/labels-custom-metadata.md index b5f293b801..b527a694e5 100644 --- a/config/labels-custom-metadata.md +++ b/config/labels-custom-metadata.md @@ -79,10 +79,10 @@ Labels on swarm nodes and services can be updated dynamically. - Images and containers - [Adding labels to images](../engine/reference/builder.md#label) - - [Overriding a container's labels at runtime](../engine/reference/commandline/run.md#set-metadata-on-container--l---label---label-file) + - [Overriding a container's labels at runtime](../engine/reference/commandline/run.md#label) - [Inspecting labels on images or containers](../engine/reference/commandline/inspect.md) - - [Filtering images by label](../engine/reference/commandline/images.md#filtering) - - [Filtering containers by label](../engine/reference/commandline/ps.md#filtering) + - [Filtering images by label](../engine/reference/commandline/images.md#filter) + - [Filtering containers by label](../engine/reference/commandline/ps.md#filter) - Local Docker daemons - [Adding labels to a Docker daemon at runtime](../engine/reference/commandline/dockerd.md) @@ -91,20 +91,20 @@ Labels on swarm nodes and services can be updated dynamically. - Volumes - [Adding labels to volumes](../engine/reference/commandline/volume_create.md) - [Inspecting a volume's labels](../engine/reference/commandline/volume_inspect.md) - - [Filtering volumes by label](../engine/reference/commandline/volume_ls.md#filtering) + - [Filtering volumes by label](../engine/reference/commandline/volume_ls.md#filter) - Networks - [Adding labels to a network](../engine/reference/commandline/network_create.md) - [Inspecting a network's labels](../engine/reference/commandline/network_inspect.md) - - [Filtering networks by label](../engine/reference/commandline/network_ls.md#filtering) + - [Filtering networks by label](../engine/reference/commandline/network_ls.md#filter) - Swarm nodes - - [Adding or updating a swarm node's labels](../engine/reference/commandline/node_update.md#add-label-metadata-to-a-node) + - [Adding or updating a swarm node's labels](../engine/reference/commandline/node_update.md#label-add) - [Inspecting a swarm node's labels](../engine/reference/commandline/node_inspect.md) - - [Filtering swarm nodes by label](../engine/reference/commandline/node_ls.md#filtering) + - [Filtering swarm nodes by label](../engine/reference/commandline/node_ls.md#filter) - Swarm services - - [Adding labels when creating a swarm service](../engine/reference/commandline/service_create.md#set-metadata-on-a-service--l---label) + - [Adding labels when creating a swarm service](../engine/reference/commandline/service_create.md#label) - [Updating a swarm service's labels](../engine/reference/commandline/service_update.md) - [Inspecting a swarm service's labels](../engine/reference/commandline/service_inspect.md) - - [Filtering swarm services by label](../engine/reference/commandline/service_ls.md#filtering) + - [Filtering swarm services by label](../engine/reference/commandline/service_ls.md#filter) diff --git a/contribute/overview.md b/contribute/overview.md index 09c7725da2..eebbaa579c 100644 --- a/contribute/overview.md +++ b/contribute/overview.md @@ -15,7 +15,7 @@ as possible for you to work in this repository. The following sections guide you
    - Docker Desktop for Mac + Docker Desktop for Mac

    Contribution guidelines

    Learn about the process of contributing to our docs.

    @@ -24,7 +24,7 @@ as possible for you to work in this repository. The following sections guide you
    - Docker Desktop for Mac + Docker Desktop for Mac

    Grammar and style

    Explore Docker's grammar and style guide.

    @@ -33,7 +33,7 @@ as possible for you to work in this repository. The following sections guide you
    - Docker for Linux + Docker for Linux

    Formatting

    Format your content to match the rest of our documentation.

    @@ -45,7 +45,7 @@ as possible for you to work in this repository. The following sections guide you
    - Docker Desktop for Mac + Docker Desktop for Mac

    Recommended word list

    Choose the right words for you content.

    @@ -54,7 +54,7 @@ as possible for you to work in this repository. The following sections guide you
    - Docker Desktop for Mac + Docker Desktop for Mac

    Source file conventions

    Guidelines for creating a new page.

    @@ -63,7 +63,7 @@ as possible for you to work in this repository. The following sections guide you
    - Docker Desktop for Windows + Docker Desktop for Windows

    Docker terminology

    Explore commonly used Docker terms.

    diff --git a/desktop/containerd/index.md b/desktop/containerd/index.md index 9afcc48f99..d885fb4fb3 100644 --- a/desktop/containerd/index.md +++ b/desktop/containerd/index.md @@ -22,7 +22,7 @@ The containerd image store beta feature is off by default. To start using the feature: -1. Navigate to **Settings**, or **Preferences** if you’re a Mac user. +1. Navigate to **Settings**. 2. Select the **Experimental** features tab. 3. Next to **Use containerd for pulling and storing images**, select the checkbox. @@ -145,7 +145,7 @@ CONTAINER ID IMAGE COMMAND CREATED STATUS You can also check from the browser that Nginx is running: -![containerd_feature_nginx](../images/containerd_feature_nginx.png){:width="750px"} +![Containerd setting in Docker Desktop](../images/containerd_feature_nginx.png){:width="750px"} ## Building multi-platform images diff --git a/desktop/dev-environments/create-dev-env.md b/desktop/dev-environments/create-dev-env.md index 6fbf7d4fed..54f7d4b757 100644 --- a/desktop/dev-environments/create-dev-env.md +++ b/desktop/dev-environments/create-dev-env.md @@ -5,6 +5,7 @@ title: Launch a dev environment redirect_from: - /desktop/dev-environments/create-compose-dev-env/ --- +{% include dev-envs-changing.md %} You can launch a dev environment from a: - Git repository @@ -31,9 +32,7 @@ To get started with Dev Environments, you must also install the following tools - [Visual Studio Code](https://code.visualstudio.com/){:target="_blank" rel="noopener" class="_"} - [Visual Studio Code Remote Containers Extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers){:target="_blank" rel="noopener" class="_"} -> **Note** -> -> After Git is installed, restart Docker Desktop. Select **Quit Docker Desktop**, and then start it again. + After Git is installed, restart Docker Desktop. Select **Quit Docker Desktop**, and then start it again. ## Launch a dev environment from a Git repository diff --git a/desktop/dev-environments/dev-cli.md b/desktop/dev-environments/dev-cli.md index f2b53cace0..ae984a8c10 100644 --- a/desktop/dev-environments/dev-cli.md +++ b/desktop/dev-environments/dev-cli.md @@ -3,6 +3,7 @@ description: Set up a dev Environments keywords: Dev Environments, share, docker dev, Docker Desktop title: Use the docker dev CLI plugin --- +{% include dev-envs-changing.md %} Use the new `docker dev` CLI plugin to get the full Dev Environments experience from the terminal in addition to the Dashboard. diff --git a/desktop/dev-environments/index.md b/desktop/dev-environments/index.md index a04c374b0d..c583385b68 100644 --- a/desktop/dev-environments/index.md +++ b/desktop/dev-environments/index.md @@ -3,6 +3,8 @@ description: Dev Environments keywords: Dev Environments, share, local, Compose title: Overview --- +{% include dev-envs-changing.md %} + > **Beta** > > The Dev Environments feature is currently in [Beta](../../release-lifecycle.md#beta). We recommend that you do not use this in production environments. @@ -13,14 +15,13 @@ It uses tools built into code editors that allows Docker to access code mounted You can use Dev Environments through the intuitive GUI in Docker Dashboard or straight from you terminal with the new [`docker dev` CLI plugin](dev-cli.md). -![Dev environment intro](../images/dev-env.PNG){:width="700px"} +![Dev environments tab in Docker Desktop](../images/dev-env.PNG){:width="700px"} ## How does it work? >**Changes to Dev Environments with Docker Desktop 4.13** > >Docker has simplified how you configure your dev environment project. All you need to get started is a `compose-dev.yaml` file. If you have an existing project with a `.docker/` folder this is automatically migrated the next time you launch. -{: .important} Dev Environments is powered by [Docker Compose](/compose/). This allows Dev Environments to take advantage of all the benefits and features of Compose whilst adding an intuitive GUI where you can launch environments with the click of a button. diff --git a/desktop/dev-environments/set-up.md b/desktop/dev-environments/set-up.md index 6218a20af4..49f4151c5d 100644 --- a/desktop/dev-environments/set-up.md +++ b/desktop/dev-environments/set-up.md @@ -3,6 +3,7 @@ description: Set up a dev Environments keywords: Dev Environments, share, set up, Compose, Docker Desktop title: Set up a dev environment --- +{% include dev-envs-changing.md %} >**Changes to Dev Environments with Docker Desktop 4.13** > @@ -10,7 +11,7 @@ title: Set up a dev environment > > If you are using `.docker/docker-compose.yaml`, we move it to `../compose-dev.yaml`. >If you are using `.docker/config.json`, we create a `../compose-dev.yaml` file with a single service named "app”. It is configured to use the image or Dockerfile referenced in the JSON as a starting point. -{: .important} + To set up a dev environment, there are additional configuration steps to tell Docker Desktop how to build, start, and use the right image for your services. Dev Environments use an `compose-dev.yaml` file located at the root of your project. This file allows you to define the image required for a dedicated service, the ports you'd like to expose, along with additional configuration options. diff --git a/desktop/dev-environments/share.md b/desktop/dev-environments/share.md index b04b423c00..2419615753 100644 --- a/desktop/dev-environments/share.md +++ b/desktop/dev-environments/share.md @@ -3,6 +3,7 @@ description: Dev Environments keywords: Dev Environments, share, Docker Desktop title: Distribute your dev environment --- +{% include dev-envs-changing.md %} The `compose-dev.yaml` config file makes distributing your dev environment easy so everyone can access the same code and any dependencies. diff --git a/desktop/extensions-sdk/architecture/index.md b/desktop/extensions-sdk/architecture/index.md index d8f7e1df30..d4c36ce618 100644 --- a/desktop/extensions-sdk/architecture/index.md +++ b/desktop/extensions-sdk/architecture/index.md @@ -5,7 +5,7 @@ keywords: Docker, extensions, sdk, metadata --- Extensions are applications that run inside the Docker Desktop. They're packaged as Docker images, distributed -through Docker Hub, and installed by users either through the Marketplace within Docker Desktop Dashboard or the +through Docker Hub, and installed by users either through the Marketplace within Docker Dashboard or the Docker Extensions CLI. Extensions can be composed of 3 (optional) components: @@ -13,7 +13,7 @@ Extensions can be composed of 3 (optional) components: - a backend: one or many containerised services running in the Docker Desktop VM - executables: shell scripts or binaries that Docker Desktop copies on the host when installing the extension -![Overview](./images/overview.svg) +![Overview of the three components of an extension](./images/overview.svg) An extension doesn't necessarily need to have all these components, but at least one of them depending on the extension features. To configure and run those components, Docker Desktop uses a `metadata.json` file. See the @@ -21,7 +21,7 @@ To configure and run those components, Docker Desktop uses a `metadata.json` fil ## The frontend -The frontend, is basically a web application made from HTML, Javascript, and CSS. It can be built with a simple HTML +The frontend is basically a web application made from HTML, Javascript, and CSS. It can be built with a simple HTML file, some vanilla Javascript or any frontend framework, such as React or Vue.js. When Docker Desktop installs the extension, it extracts the UI folder from the extension image, as defined by the @@ -43,13 +43,13 @@ Learn more about [building a frontend](../build/frontend-extension-tutorial.md) ## The backend -Alongside a frontend application, extensions can also contain one or many backend services. In many cases, the Extension does not need a backend, and features can be implemented just by invoking docker commands through the SDK. However, there are some cases when an extension requires a backend +Alongside a frontend application, extensions can also contain one or many backend services. In most cases, the Extension does not need a backend, and features can be implemented just by invoking docker commands through the SDK. However, there are some cases when an extension requires a backend service, for example: -- run long-running processes that must outlive the frontend -- store data in a local database and serve them back with a REST API -- store the extension state, like when a button starts a long-running process, so that if you navigate away +- To run long-running processes that must outlive the frontend +- To store data in a local database and serve them back with a REST API +- To store the extension state, like when a button starts a long-running process, so that if you navigate away from the extension and come back, the frontend can pick up where it left off -- accessing specific resources in the Docker Desktop VM, for example by mounting folders in the compose +- To access specific resources in the Docker Desktop VM, for example by mounting folders in the compose file > **Tip** @@ -71,7 +71,7 @@ Note that, if the Compose file defines many services, the SDK can only contact t > **Note** > > In some cases, it is useful to also interact with the Docker engine from the backend. -> See [how to use the Docker socket](../guides/use-docker-socket-from-backend.md) from the backend. +> See [How to use the Docker socket](../guides/use-docker-socket-from-backend.md) from the backend. To communicate with the backend, the Extension SDK provides [functions](../dev/api/backend.md#get) to make `GET`, `POST`, `PUT`, `HEAD`, and `DELETE` requests from the frontend. Under the hood, the communication is done through a socket diff --git a/desktop/extensions-sdk/architecture/metadata.md b/desktop/extensions-sdk/architecture/metadata.md index b7cfb3e4e5..9fc5397b51 100644 --- a/desktop/extensions-sdk/architecture/metadata.md +++ b/desktop/extensions-sdk/architecture/metadata.md @@ -40,7 +40,7 @@ The `ui` section defines a new tab that's added to the dashboard in Docker Deskt } ``` -`root` specifies the folder where the ui code **is within the extension image filesystem**. +`root` specifies the folder where the UI code is within the extension image filesystem. `src` specifies the entrypoint that should be loaded in the extension tab. Other UI extension points will be available in the future. diff --git a/desktop/extensions-sdk/build/backend-extension-tutorial.md b/desktop/extensions-sdk/build/backend-extension-tutorial.md index 196dae85d0..8a577af167 100644 --- a/desktop/extensions-sdk/build/backend-extension-tutorial.md +++ b/desktop/extensions-sdk/build/backend-extension-tutorial.md @@ -8,16 +8,13 @@ redirect_from: - /desktop/extensions-sdk/build/set-up/backend-extension-tutorial/ --- -Your extension can ship a backend part with which the frontend can interact with. This page provides information on -why and how to add a backend. +Your extension can ship a backend part with which the frontend can interact with. This page provides information on why and how to add a backend. + +Before you start, make sure you have installed the latest version of [Docker Desktop](https://www.docker.com/products/docker-desktop/). > Note > -> Before you start, make sure you have installed the latest version of [Docker Desktop](https://www.docker.com/products/docker-desktop/). - -> Note -> -> If you want to start a codebase for your new extension, our [Quickstart guide](../quickstart.md) and `docker extension init ` provides a better base for your extension as it is more up-to-date and related to your install of Docker Desktop. +> Check the [Quickstart guide](../quickstart.md) and `docker extension init `. They provide a better base for your extension as it's more up-to-date and related to your install of Docker Desktop. ## Why add a backend? @@ -27,15 +24,13 @@ directly from [the frontend](./frontend-extension-tutorial.md#use-the-extension- Nonetheless, there are some cases where you might need to add a backend to your extension. So far, extension builders have used the backend to: - Store data in a local database and serve them back with a REST API. -- Store the extension state, like when a button starts a long-running process, so that if you navigate away - from the extension user interface and come back, the frontend can pick up where it left off. +- Store the extension state, for example when a button starts a long-running process, so that if you navigate away from the extension user interface and comes back, the frontend can pick up where it left off. -Learn more about extension backend in the [architecture](../architecture/index.md#the-backend) section. +For more information about extension backends, see [Architecture](../architecture/index.md#the-backend). ## Add a backend to the extension -If you created your extension using the `docker extension init` command, you already have a backend setup. If it is -not the case, then you have to first create a `vm` directory that will contain the code and update the Dockerfile to +If you created your extension using the `docker extension init` command, you already have a backend setup. Otherwise, you have to first create a `vm` directory that contains the code and updates the Dockerfile to containerize it. Here is the extension folder structure with a backend: @@ -53,7 +48,7 @@ Here is the extension folder structure with a backend: ``` 1. Contains everything required to build the backend and copy it in the extension's container filesystem. -2. The source folder that contains the backend code of the extension +2. The source folder that contains the backend code of the extension. Although you can start from an empty directory or from the `vm-ui extension` [sample](https://github.com/docker/extensions-sdk/tree/main/samples){:target="_blank" rel="noopener" class="_"}, it is highly recommended that you start from the `docker extension init` command and change it to suit your needs. @@ -64,7 +59,7 @@ it is highly recommended that you start from the `docker extension init` command > your own extension and use any other language like Node.js, Python, Java, .Net, or any other language and framework. {: .tip } -On this tutorial, the backend service simply exposes one route that returns a JSON payload that says "Hello". +In this tutorial, the backend service simply exposes one route that returns a JSON payload that says "Hello". ```json { "Message": "Hello" } @@ -72,10 +67,10 @@ On this tutorial, the backend service simply exposes one route that returns a JS > **Important** > -> We recommend that, the frontend and the backend communicate through sockets (and named pipes on Windows) instead of -> HTTP. On one hand, because it will prevent port collision with any other running application or container running -> on the host. On the other hand, because some Docker Desktop users are running in constrained environments where they -> can't open ports on their machines. So, when choosing the language and framework for your backend, make sure it +> We recommend that, the frontend and the backend communicate through sockets, and named pipes on Windows, instead of +> HTTP. This prevents port collision with any other running application or container running +> on the host. Also, some Docker Desktop users are running in constrained environments where they +> can't open ports on their machines. When choosing the language and framework for your backend, make sure it > supports sockets connection. {: .important} @@ -149,7 +144,7 @@ type HTTPMessageBody struct { > **Important** > > We don't have a working example for Node yet. [Fill out the form](https://docs.google.com/forms/d/e/1FAIpQLSdxJDGFJl5oJ06rG7uqtw1rsSBZpUhv_s9HHtw80cytkh2X-Q/viewform?usp=pp_url&entry.25798127=Node){: target="_blank" rel="noopener" class="_"} -> and let us know you'd like a sample for Node. +> and let us know if you'd like a sample for Node. {: .important }
    @@ -160,7 +155,7 @@ type HTTPMessageBody struct { > **Important** > > We don't have a working example for Python yet. [Fill out the form](https://docs.google.com/forms/d/e/1FAIpQLSdxJDGFJl5oJ06rG7uqtw1rsSBZpUhv_s9HHtw80cytkh2X-Q/viewform?usp=pp_url&entry.25798127=Python){: target="_blank" rel="noopener" class="_"} -> and let us know you'd like a sample for Python. +> and let us know if you'd like a sample for Python. {: .important }
    @@ -171,7 +166,7 @@ type HTTPMessageBody struct { > **Important** > > We don't have a working example for Java yet. [Fill out the form](https://docs.google.com/forms/d/e/1FAIpQLSdxJDGFJl5oJ06rG7uqtw1rsSBZpUhv_s9HHtw80cytkh2X-Q/viewform?usp=pp_url&entry.25798127=Java){: target="_blank" rel="noopener" class="_"} -> and let us know you'd like a sample for Java. +> and let us know if you'd like a sample for Java. {: .important }
    @@ -182,7 +177,7 @@ type HTTPMessageBody struct { > **Important** > > We don't have a working example for .Net. [Fill out the form](https://docs.google.com/forms/d/e/1FAIpQLSdxJDGFJl5oJ06rG7uqtw1rsSBZpUhv_s9HHtw80cytkh2X-Q/viewform?usp=pp_url&entry.25798127=.Net){: target="_blank" rel="noopener" class="_"} -> and let us know you'd like a sample for .Net. +> and let us know if you'd like a sample for .Net. {: .important }
    @@ -251,7 +246,7 @@ CMD /service -socket /run/guest-services/extension-allthethings-extension.sock > **Important** > > We don't have a working Dockerfile for Node yet. [Fill out the form](https://docs.google.com/forms/d/e/1FAIpQLSdxJDGFJl5oJ06rG7uqtw1rsSBZpUhv_s9HHtw80cytkh2X-Q/viewform?usp=pp_url&entry.25798127=Node){: target="_blank" rel="noopener" class="_"} -> and let us know you'd like a Dockerfile for Node. +> and let us know if you'd like a Dockerfile for Node. {: .important }
    @@ -262,7 +257,7 @@ CMD /service -socket /run/guest-services/extension-allthethings-extension.sock > **Important** > > We don't have a working Dockerfile for Python yet. [Fill out the form](https://docs.google.com/forms/d/e/1FAIpQLSdxJDGFJl5oJ06rG7uqtw1rsSBZpUhv_s9HHtw80cytkh2X-Q/viewform?usp=pp_url&entry.25798127=Python){: target="_blank" rel="noopener" class="_"} -> and let us know you'd like a Dockerfile for Python. +> and let us know if you'd like a Dockerfile for Python. {: .important }
    @@ -273,7 +268,7 @@ CMD /service -socket /run/guest-services/extension-allthethings-extension.sock > **Important** > > We don't have a working Dockerfile for Java yet. [Fill out the form](https://docs.google.com/forms/d/e/1FAIpQLSdxJDGFJl5oJ06rG7uqtw1rsSBZpUhv_s9HHtw80cytkh2X-Q/viewform?usp=pp_url&entry.25798127=Java){: target="_blank" rel="noopener" class="_"} -> and let us know you'd like a Dockerfile for Java. +> and let us know if you'd like a Dockerfile for Java. {: .important }
    @@ -284,7 +279,7 @@ CMD /service -socket /run/guest-services/extension-allthethings-extension.sock > **Important** > > We don't have a working Dockerfile for .Net. [Fill out the form](https://docs.google.com/forms/d/e/1FAIpQLSdxJDGFJl5oJ06rG7uqtw1rsSBZpUhv_s9HHtw80cytkh2X-Q/viewform?usp=pp_url&entry.25798127=.Net){: target="_blank" rel="noopener" class="_"} -> and let us know you'd like a Dockerfile for .Net. +> and let us know if you'd like a Dockerfile for .Net. {: .important }
    @@ -369,7 +364,7 @@ export function App() { > **Important** > > We don't have an example for Vue yet. [Fill out the form](https://docs.google.com/forms/d/e/1FAIpQLSdxJDGFJl5oJ06rG7uqtw1rsSBZpUhv_s9HHtw80cytkh2X-Q/viewform?usp=pp_url&entry.1333218187=Vue){: target="_blank" rel="noopener" class="_"} -> and let us know you'd like a sample with Vue. +> and let us know if you'd like a sample with Vue. {: .important }
    @@ -380,7 +375,7 @@ export function App() { > **Important** > > We don't have an example for Angular yet. [Fill out the form](https://docs.google.com/forms/d/e/1FAIpQLSdxJDGFJl5oJ06rG7uqtw1rsSBZpUhv_s9HHtw80cytkh2X-Q/viewform?usp=pp_url&entry.1333218187=Angular){: target="_blank" rel="noopener" class="_"} -> and let us know you'd like a sample with Angular. +> and let us know if you'd like a sample with Angular. {: .important }
    @@ -391,7 +386,7 @@ export function App() { > **Important** > > We don't have an example for Svelte yet. [Fill out the form](https://docs.google.com/forms/d/e/1FAIpQLSdxJDGFJl5oJ06rG7uqtw1rsSBZpUhv_s9HHtw80cytkh2X-Q/viewform?usp=pp_url&entry.1333218187=Svelte){: target="_blank" rel="noopener" class="_"} -> and let us know you'd like a sample with Svelte. +> and let us know if you'd like a sample with Svelte. {: .important }
    @@ -399,30 +394,27 @@ export function App() { ## Re-build the extension and update it -Since you have modified the configuration of the extension and added a stage in the Dockerfile, you must build again -the extension. +Since you have modified the configuration of the extension and added a stage in the Dockerfile, you must re-build the extension. ```bash docker build --tag= awesome-inc/my-extension:latest . ``` -Once built, you need to update it (or install it if you haven't done it yet). +Once built, you need to update it, or install it if you haven't already done so. ```bash docker extension update awesome-inc/my-extension:latest ``` -Now you can see the backend service running in the containers tab of the Docker Desktop Dashboard and watch the logs -when you need to debug it. +Now you can see the backend service running in the **Containers8* tab of the Docker Dashboard and watch the logs when you need to debug it. > **Tip** > -> You may need to enable the "Show system containers" option in Docker Desktop to see the backend container running -> under the extension compose project in the containers tab of the dashboard. -> See [how to show extension containers](../dev/test-debug.md#show-the-extension-containers) for more information. +> You may need to enable the **Show system containers** option in **Settings** to see the backend container running. +> See [Show extension containers](../dev/test-debug.md#show-the-extension-containers) for more information. {: .tip } -Open Docker Desktop Dashboard and click on the containers tab. You should see the response from the backend service +Open Docker Dashboard and select the **Containers** tab. You should see the response from the backend service call displayed. ## What's next? diff --git a/desktop/extensions-sdk/build/frontend-extension-tutorial.md b/desktop/extensions-sdk/build/frontend-extension-tutorial.md index 6cdfaf4dc2..491dedaa67 100644 --- a/desktop/extensions-sdk/build/frontend-extension-tutorial.md +++ b/desktop/extensions-sdk/build/frontend-extension-tutorial.md @@ -1,5 +1,5 @@ --- -title: Set up an advanced frontend extension +title: Create an advanced frontend extension description: Advanced frontend extension tutorial keywords: Docker, extensions, sdk, build redirect_from: @@ -9,16 +9,14 @@ redirect_from: - /desktop/extensions-sdk/build/set-up/frontend-extension-tutorial/ --- -To start creating your extension, you first need a directory with files which range from the extension’s source code to the required extension-specific files. This page provides information on how to set up a simple Docker extension that contains only a UI part. +To start creating your extension, you first need a directory with files which range from the extension’s source code to the required extension-specific files. This page provides information on how to set up an extension with a more advanced frontend. -> Note -> -> Before you start, make sure you have installed the latest version of [Docker Desktop](https://www.docker.com/products/docker-desktop/). +Before you start, make sure you have installed the latest version of [Docker Desktop](../../release-notes.md). ## Extension folder structure The quickest way to create a new extension is to run `docker extension init my-extension` as in the -[Quickstart](../quickstart.md). This will create a new directory `my-extension` that contains a fully functional extension. +[Quickstart](../quickstart.md). This creates a new directory `my-extension` that contains a fully functional extension. > **Tip** > @@ -92,7 +90,7 @@ FROM alpine LABEL org.opencontainers.image.title="My extension" \ org.opencontainers.image.description="Your Desktop Extension Description" \ org.opencontainers.image.vendor="Awesome Inc." \ - com.docker.desktop.extension.api.version="0.3.0" \ + com.docker.desktop.extension.api.version="0.3.3" \ com.docker.desktop.extension.icon="https://www.docker.com/wp-content/uploads/2022/03/Moby-logo.png" \ com.docker.extension.screenshots="" \ com.docker.extension.detailed-description="" \ @@ -105,6 +103,10 @@ COPY docker.svg . COPY --from=client-builder /ui/build ui ``` +> Note +> +> In the example Dockerfile, you can see that the image label `com.docker.desktop.extension.icon` is set to an icon URL. The Extensions Marketplace displays this icon without installing the extension. The Dockerfile also includes `COPY docker.svg .` to copy an icon file inside the image. This second icon file is used to display the extension UI in the Dashboard, once the extension is installed. +
    @@ -114,7 +116,7 @@ COPY --from=client-builder /ui/build ui > **Important** > > We don't have a working Dockerfile for Vue yet. [Fill out the form](https://docs.google.com/forms/d/e/1FAIpQLSdxJDGFJl5oJ06rG7uqtw1rsSBZpUhv_s9HHtw80cytkh2X-Q/viewform?usp=pp_url&entry.1333218187=Vue){: target="_blank" rel="noopener" class="_"} -> and let us know you'd like a Dockerfile for Vue. +> and let us know if you'd like a Dockerfile for Vue. {: .important }
    @@ -125,7 +127,7 @@ COPY --from=client-builder /ui/build ui > **Important** > > We don't have a working Dockerfile for Angular yet. [Fill out the form](https://docs.google.com/forms/d/e/1FAIpQLSdxJDGFJl5oJ06rG7uqtw1rsSBZpUhv_s9HHtw80cytkh2X-Q/viewform?usp=pp_url&entry.1333218187=Angular){: target="_blank" rel="noopener" class="_"} -> and let us know you'd like a Dockerfile for Angular. +> and let us know if you'd like a Dockerfile for Angular. {: .important } @@ -136,12 +138,14 @@ COPY --from=client-builder /ui/build ui > **Important** > > We don't have a working Dockerfile for Svelte yet. [Fill out the form](https://docs.google.com/forms/d/e/1FAIpQLSdxJDGFJl5oJ06rG7uqtw1rsSBZpUhv_s9HHtw80cytkh2X-Q/viewform?usp=pp_url&entry.1333218187=Svelte){: target="_blank" rel="noopener" class="_"} -> and let us know you'd like a Dockerfile for Svelte. +> and let us know if you'd like a Dockerfile for Svelte. {: .important } + + ## Configure the metadata file In order to add a tab in Docker Desktop for your extension, you have to configure it in the `metadata.json` @@ -209,7 +213,7 @@ provide you with type definitions for the extension APIs and auto-completion in npm install @docker/extension-api-client-types --save-dev ``` -![types auto complete](images/types-autocomplete.png) +![Auto completion in an IDE](images/types-autocomplete.png) For example, you can use the `docker.cli.exec` function to get the list of all the containers via the `docker ps --all` command and display the result in a table. @@ -302,6 +306,7 @@ export function App() { } {% endraw %} ``` +![Screenshot of the container list.](images/react-extension.png)
    @@ -311,7 +316,7 @@ export function App() { > **Important** > > We don't have an example for Vue yet. [Fill out the form](https://docs.google.com/forms/d/e/1FAIpQLSdxJDGFJl5oJ06rG7uqtw1rsSBZpUhv_s9HHtw80cytkh2X-Q/viewform?usp=pp_url&entry.1333218187=Vue){: target="_blank" rel="noopener" class="_"} -> and let us know you'd like a sample with Vue. +> and let us know if you'd like a sample with Vue. {: .important }
    @@ -322,7 +327,7 @@ export function App() { > **Important** > > We don't have an example for Angular yet. [Fill out the form](https://docs.google.com/forms/d/e/1FAIpQLSdxJDGFJl5oJ06rG7uqtw1rsSBZpUhv_s9HHtw80cytkh2X-Q/viewform?usp=pp_url&entry.1333218187=Angular){: target="_blank" rel="noopener" class="_"} -> and let us know you'd like a sample with Angular. +> and let us know if you'd like a sample with Angular. {: .important } @@ -333,13 +338,27 @@ export function App() { > **Important** > > We don't have an example for Svelte yet. [Fill out the form](https://docs.google.com/forms/d/e/1FAIpQLSdxJDGFJl5oJ06rG7uqtw1rsSBZpUhv_s9HHtw80cytkh2X-Q/viewform?usp=pp_url&entry.1333218187=Svelte){: target="_blank" rel="noopener" class="_"} -> and let us know you'd like a sample with Svelte. +> and let us know if you'd like a sample with Svelte. {: .important } -![Screenshot of the container list.](images/react-extension.png) + +## Policies enforced for the front-end code + +Extension UI code is rendered in a separate electron session and doesn't have a node.js environment initialized, nor direct access to the electron APIs. + +This is to limit the possible unexpected side effects to the overall Docker Dashboard. + +The extension UI code can't perform privileged tasks, such as making changes to the system, or spawning sub-processes, except by using the SDK APIs provided with the extension framework. +The Extension UI code can also perform interactions with Docker Desktop, such as navigating to various places in the Dashboard, only through the extension SDK APIs. + +Extensions UI parts are isolated from each other and extension UI code is running in its own session for each extension. Extensions can't access other extensions’ session data. + +`localStorage` is one of the mechanisms of a browser’s web storage. It allows users to save data as key-value pairs in the browser for later use. `localStorage` doesn't clear data when the browser (the extension pane) closes. This makes it ideal for persisting data when navigating out of the extension to other parts of Docker Desktop. + +If your extension uses `localStorage` to store data, other extensions running in Docker Desktop can't access the local storage of your extension. The extension’s local storage is persisted even after Docker Desktop is stopped or restarted. When an extension is upgraded, its local storage is persisted, whereas when it is uninstalled, its local storage is completely removed. ## Re-build the extension and update it diff --git a/desktop/extensions-sdk/build/minimal-frontend-extension.md b/desktop/extensions-sdk/build/minimal-frontend-extension.md index 6eb9639d67..b916636bb7 100644 --- a/desktop/extensions-sdk/build/minimal-frontend-extension.md +++ b/desktop/extensions-sdk/build/minimal-frontend-extension.md @@ -1,5 +1,5 @@ --- -title: Set up a minimal frontend extension +title: Create a simple extension description: Minimal frontend extension tutorial keywords: Docker, extensions, sdk, build redirect_from: @@ -9,13 +9,11 @@ redirect_from: To start creating your extension, you first need a directory with files which range from the extension’s source code to the required extension-specific files. This page provides information on how to set up a minimal frontend extension based on plain HTML. -> Note -> -> Before you start, make sure you have installed the latest version of [Docker Desktop](https://www.docker.com/products/docker-desktop/). +Before you start, make sure you have installed the latest version of [Docker Desktop](../../release-notes.md). > Note > -> If you want to start a codebase for your new extension, our [Quickstart guide](../quickstart.md) and `docker extension init ` will provide a better base for your extension, more up-to-date and related to your install of Docker Desktop. +> If you want to start a codebase for your new extension, our [Quickstart guide](../quickstart.md) and `docker extension init ` provides a better base for your extension. ## Extension folder structure @@ -40,7 +38,7 @@ Although you can start from an empty directory, it is highly recommended that yo At a minimum, your Dockerfile needs: -- Labels which provide extra information about the extension. +- [Labels](../extensions/labels.md) which provide extra information about the extension, icon and screenshots. - The source code which in this case is an `index.html` that sits within the `ui` folder. - The `metadata.json` file. @@ -51,7 +49,7 @@ FROM scratch LABEL org.opencontainers.image.title="Minimal frontend" \ org.opencontainers.image.description="A sample extension to show how easy it's to get started with Desktop Extensions." \ org.opencontainers.image.vendor="Awesome Inc." \ - com.docker.desktop.extension.api.version="1.0.0-beta.1" \ + com.docker.desktop.extension.api.version="0.3.3" \ com.docker.desktop.extension.icon="https://www.docker.com/wp-content/uploads/2022/03/Moby-logo.png" COPY ui ./ui @@ -85,8 +83,7 @@ install it. $ docker build --tag= awesome-inc/my-extension:latest . ``` -This built an image tagged `awesome-inc/my-extension:latest`, you can run `docker inspect -awesome-inc/my-extension:latest` to see more details about it. +This built an image tagged `awesome-inc/my-extension:latest`, you can run `docker inspect awesome-inc/my-extension:latest` to see more details about it. Finally, you can install the extension and see it appearing in the Docker Desktop Dashboard. @@ -100,7 +97,7 @@ To preview the extension in Docker Desktop, close and open Docker Dashboard once The left-hand menu displays a new tab with the name of your extension. -![minimal-frontend-extension](images/ui-minimal-extension.png) +![Minimal frontend extension](images/ui-minimal-extension.png) ## What's next? diff --git a/desktop/extensions-sdk/design/design-guidelines.md b/desktop/extensions-sdk/design/design-guidelines.md index 010da7c7c1..bb4c8f063f 100644 --- a/desktop/extensions-sdk/design/design-guidelines.md +++ b/desktop/extensions-sdk/design/design-guidelines.md @@ -18,39 +18,39 @@ Use the [Docker Material UI Theme](https://www.npmjs.com/package/@docker/docker- - Ensure the extension has both a light and dark theme. Using the components and styles as per the Docker style guide ensures that your extension meets the [level AA accessibility standard.](https://www.w3.org/WAI/WCAG2AA-Conformance){:target="_blank" rel="noopener" class="_"}. -![light and dark mode](images/light_dark_mode.png) + ![Light and dark mode](images/light_dark_mode.png) - Ensure that your extension icon is visible both in light and dark mode. -![icon colors](images/icon_colors.png) + ![Icon colors in light and dark mode](images/icon_colors.png) - Ensure that the navigational behavior is consistent with the rest of Docker Desktop. Add a header to set the context for the extension. -![header](images/header.png) + ![Header that sets the context](images/header.png) - Avoid embedding terminal windows. The advantage we have with Docker Desktop over the CLI is that we have the opportunity to provide rich information to users. Make use of this interface as much as possible. -![terminal window dont](images/terminal_window_dont.png){:height="=50%" width="50%"} + ![Terminal window used incorrectly](images/terminal_window_dont.png){:height="=50%" width="50%"} -![terminal window do](images/terminal_window_do.png) + ![Terminal window used correctly](images/terminal_window_do.png) ## Build Features Natively - In order not to disrupt the flow of users, avoid scenarios where the user has to navigate outside Docker Desktop, to the CLI or a webpage for example, in order to carry out certain functionalities. Instead, build features that are native to Docker Desktop. -![switch context dont](images/switch_context_dont.png){:height="=50%" width="50%"} + ![Incorrect way to switch context](images/switch_context_dont.png){:height="=50%" width="50%"} -![switch context do](images/switch_context_do.png) + ![Correct way to switch context](images/switch_context_do.png) ## Break Down Complicated User Flows - If a flow is too complicated or the concept is abstract, break down the flow into multiple steps with one simple call-to-action in each step. This helps when onboarding novice users to your extension -![complicated flow](images/complicated_flows.png) + ![A complicated flow](images/complicated_flows.png) - Where there are multiple call-to-actions, ensure you use the primary (filled button style) and secondary buttons (outline button style) to convey the importance of each action. -![call to action](images/cta.png) + ![Call to action](images/cta.png) ## Onboarding New Users @@ -62,7 +62,7 @@ When building your extension, ensure that first time users of the extension and - Link to necessary resources such as documentation. - If your extension has particularly complex functionality, add a demo or video to the start page. This helps onboard a first time user quickly. -![start page](images/start_page.png){:height="50%" width="50%"} + ![start page](images/start_page.png){:height="50%" width="50%"} ## What's next? diff --git a/desktop/extensions-sdk/dev/api/reference/README.md b/desktop/extensions-sdk/dev/api/reference/README.md index 485104e698..47f6adc4b8 100644 --- a/desktop/extensions-sdk/dev/api/reference/README.md +++ b/desktop/extensions-sdk/dev/api/reference/README.md @@ -21,6 +21,8 @@ skip_read_time: true - [Dialog](interfaces/Dialog.md) - [Docker](interfaces/Docker.md) - [DockerCommand](interfaces/DockerCommand.md) +- [ExecOptions](interfaces/ExecOptions.md) +- [SpawnOptions](interfaces/SpawnOptions.md) - [Exec](interfaces/Exec.md) - [ExecProcess](interfaces/ExecProcess.md) - [ExecStreamOptions](interfaces/ExecStreamOptions.md) diff --git a/desktop/extensions-sdk/dev/api/reference/interfaces/BackendV0.md b/desktop/extensions-sdk/dev/api/reference/interfaces/BackendV0.md index 5a0143dfe5..10afaa3048 100644 --- a/desktop/extensions-sdk/dev/api/reference/interfaces/BackendV0.md +++ b/desktop/extensions-sdk/dev/api/reference/interfaces/BackendV0.md @@ -20,7 +20,9 @@ const output = await window.ddClient.backend.execInContainer(container, cmd); console.log(output); ``` -**`deprecated`** :warning: It will be removed in a future version. +**`Deprecated`** + +:warning: It will be removed in a future version. #### Parameters @@ -49,7 +51,9 @@ window.ddClient.backend .then((value: any) => console.log(value)); ``` -**`deprecated`** :warning: It will be removed in a future version. Use [HttpService.get](HttpService.md#get) instead. +**`Deprecated`** + +:warning: It will be removed in a future version. Use [get](HttpService.md#get) instead. #### Parameters @@ -75,7 +79,9 @@ window.ddClient.backend .then((value: any) => console.log(value)); ``` -**`deprecated`** :warning: It will be removed in a future version. Use [HttpService.post](HttpService.md#post) instead. +**`Deprecated`** + +:warning: It will be removed in a future version. Use [post](HttpService.md#post) instead. #### Parameters @@ -102,7 +108,9 @@ window.ddClient.backend .then((value: any) => console.log(value)); ``` -**`deprecated`** :warning: It will be removed in a future version. Use [HttpService.put](HttpService.md#put) instead. +**`Deprecated`** + +:warning: It will be removed in a future version. Use [put](HttpService.md#put) instead. #### Parameters @@ -129,7 +137,9 @@ window.ddClient.backend .then((value: any) => console.log(value)); ``` -**`deprecated`** :warning: It will be removed in a future version. Use [HttpService.patch](HttpService.md#patch) instead. +**`Deprecated`** + +:warning: It will be removed in a future version. Use [patch](HttpService.md#patch) instead. #### Parameters @@ -156,7 +166,9 @@ window.ddClient.backend .then((value: any) => console.log(value)); ``` -**`deprecated`** :warning: It will be removed in a future version. Use [HttpService.delete](HttpService.md#delete) instead. +**`Deprecated`** + +:warning: It will be removed in a future version. Use [delete](HttpService.md#delete) instead. #### Parameters @@ -182,7 +194,9 @@ window.ddClient.backend .then((value: any) => console.log(value)); ``` -**`deprecated`** :warning: It will be removed in a future version. Use [HttpService.head](HttpService.md#head) instead. +**`Deprecated`** + +:warning: It will be removed in a future version. Use [head](HttpService.md#head) instead. #### Parameters @@ -208,7 +222,9 @@ window.ddClient.backend .then((value: any) => console.log(value)); ``` -**`deprecated`** :warning: It will be removed in a future version. Use [HttpService.request](HttpService.md#request) instead. +**`Deprecated`** + +:warning: It will be removed in a future version. Use [request](HttpService.md#request) instead. #### Parameters @@ -239,7 +255,9 @@ const output = await window.ddClient.backend.execInVMExtension( console.log(output); ``` -**`deprecated`** :warning: It will be removed in a future version. Use [ExtensionCli.exec](ExtensionCli.md#exec) instead. +**`Deprecated`** + +:warning: It will be removed in a future version. Use [exec](ExtensionCli.md#exec) instead. #### Parameters @@ -273,7 +291,9 @@ window.ddClient.spawnInVMExtension( ); ``` -**`deprecated`** :warning: It will be removed in a future version. Use {@link ExtensionCli.spawn} instead. +**`Deprecated`** + +:warning: It will be removed in a future version. #### Parameters diff --git a/desktop/extensions-sdk/dev/api/reference/interfaces/DesktopUI.md b/desktop/extensions-sdk/dev/api/reference/interfaces/DesktopUI.md index 34b9b4b667..97c18433db 100644 --- a/desktop/extensions-sdk/dev/api/reference/interfaces/DesktopUI.md +++ b/desktop/extensions-sdk/dev/api/reference/interfaces/DesktopUI.md @@ -6,7 +6,9 @@ skip_read_time: true # Interface: DesktopUI -**`since`** 0.2.0 +**`Since`** + +0.2.0 ## Properties diff --git a/desktop/extensions-sdk/dev/api/reference/interfaces/Dialog.md b/desktop/extensions-sdk/dev/api/reference/interfaces/Dialog.md index 90c4990dc7..365e290f61 100644 --- a/desktop/extensions-sdk/dev/api/reference/interfaces/Dialog.md +++ b/desktop/extensions-sdk/dev/api/reference/interfaces/Dialog.md @@ -8,7 +8,9 @@ skip_read_time: true Allows opening native dialog boxes. -**`since`** 0.2.3 +**`Since`** + +0.2.3 ## Methods diff --git a/desktop/extensions-sdk/dev/api/reference/interfaces/Docker.md b/desktop/extensions-sdk/dev/api/reference/interfaces/Docker.md index b717789217..3055e12337 100644 --- a/desktop/extensions-sdk/dev/api/reference/interfaces/Docker.md +++ b/desktop/extensions-sdk/dev/api/reference/interfaces/Docker.md @@ -6,7 +6,9 @@ skip_read_time: true # Interface: Docker -**`since`** 0.2.0 +**`Since`** + +0.2.0 ## Properties @@ -81,9 +83,9 @@ const containers = await ddClient.docker.listContainers(); #### Parameters -| Name | Type | Description | -|:-----------|:------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `options?` | `any` | (Optional). A JSON like `{ "all": true, "limit": 10, "size": true, "filters": JSON.stringify({ status: ["exited"] }), }` For more information about the different properties see [the Docker API endpoint documentation](../../../../../../engine/api/v1.37.md#operation/ContainerList). | +| Name | Type | Description | +| :------ | :------ | :------ | +| `options?` | `any` | (Optional). A JSON like `{ "all": true, "limit": 10, "size": true, "filters": JSON.stringify({ status: ["exited"] }), }` For more information about the different properties see [the Docker API endpoint documentation](https://docs.docker.com/engine/api/v1.41/#operation/ContainerList). | #### Returns @@ -103,9 +105,9 @@ const images = await ddClient.docker.listImages(); #### Parameters -| Name | Type | Description | -|:-----------|:------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `options?` | `any` | (Optional). A JSON like `{ "all": true, "filters": JSON.stringify({ dangling: ["true"] }), "digests": true }` For more information about the different properties see [the Docker API endpoint documentation](../../../../../../engine/api/v1.37.md#tag/Image). | +| Name | Type | Description | +| :------ | :------ | :------ | +| `options?` | `any` | (Optional). A JSON like `{ "all": true, "filters": JSON.stringify({ dangling: ["true"] }), "digests": true * }` * * For more information about the different properties see [the Docker API endpoint documentation](https://docs.docker.com/engine/api/v1.41/#tag/Image). | #### Returns diff --git a/desktop/extensions-sdk/dev/api/reference/interfaces/DockerCommand.md b/desktop/extensions-sdk/dev/api/reference/interfaces/DockerCommand.md index 8e7d9a520a..b48bf3c794 100644 --- a/desktop/extensions-sdk/dev/api/reference/interfaces/DockerCommand.md +++ b/desktop/extensions-sdk/dev/api/reference/interfaces/DockerCommand.md @@ -6,7 +6,9 @@ skip_read_time: true # Interface: DockerCommand -**`since`** 0.2.0 +**`Since`** + +0.2.0 ## Properties diff --git a/desktop/extensions-sdk/dev/api/reference/interfaces/DockerDesktopClient.md b/desktop/extensions-sdk/dev/api/reference/interfaces/DockerDesktopClient.md index 4b0e5b749a..6290e74b98 100644 --- a/desktop/extensions-sdk/dev/api/reference/interfaces/DockerDesktopClient.md +++ b/desktop/extensions-sdk/dev/api/reference/interfaces/DockerDesktopClient.md @@ -20,7 +20,9 @@ The `window.ddClient.backend` object can be used to communicate with the backend the extension metadata. The client is already connected to the backend. -**`deprecated`** :warning: It will be removed in a future version. Use [DockerDesktopClient.extension](DockerDesktopClient.md#extension) instead. +**`Deprecated`** + +:warning: It will be removed in a future version. Use [extension](DockerDesktopClient.md#extension) instead. #### Inherited from @@ -85,13 +87,15 @@ You can use the option `{"all": true}` to list all the running and stopped conta const containers = await window.ddClient.listContainers(); ``` -**`deprecated`** :warning: It will be removed in a future version. Use [Docker.listContainers](Docker.md#listcontainers) instead. +**`Deprecated`** + +:warning: It will be removed in a future version. Use [listContainers](Docker.md#listcontainers) instead. #### Parameters -| Name | Type | Description | -|:----------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `options` | `never` | (Optional). A JSON like `{ "all": true, "limit": 10, "size": true, "filters": JSON.stringify({ status: ["exited"] }), }` For more information about the different properties see [the Docker API endpoint documentation](../../../../../../engine/api/v1.37.md#operation/ContainerList). | +| Name | Type | Description | +| :------ | :------ | :------ | +| `options` | `never` | (Optional). A JSON like `{ "all": true, "limit": 10, "size": true, "filters": JSON.stringify({ status: ["exited"] }), }` For more information about the different properties see [the Docker API endpoint documentation](https://docs.docker.com/engine/api/v1.41/#operation/ContainerList). | #### Returns @@ -115,13 +119,15 @@ Get the list of images const images = await window.ddClient.listImages(); ``` -**`deprecated`** :warning: It will be removed in a future version. Use [Docker.listImages](Docker.md#listimages) instead. +**`Deprecated`** + +:warning: It will be removed in a future version. Use [listImages](Docker.md#listimages) instead. #### Parameters -| Name | Type | Description | -|:----------|:--------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `options` | `never` | (Optional). A JSON like `{ "all": true, "filters": JSON.stringify({ dangling: ["true"] }), "digests": true }` For more information about the different properties see [the Docker API endpoint documentation](../../../../../../engine/api/v1.37.md#tag/Image). | +| Name | Type | Description | +| :------ | :------ | :------ | +| `options` | `never` | (Optional). A JSON like `{ "all": true, "filters": JSON.stringify({ dangling: ["true"] }), "digests": true }` For more information about the different properties see [the Docker API endpoint documentation](https://docs.docker.com/engine/api/v1.41/#tag/Image). | #### Returns @@ -144,7 +150,9 @@ Navigate to the containers window in Docker Desktop. window.ddClient.navigateToContainers(); ``` -**`deprecated`** :warning: It will be removed in a future version. Use [NavigationIntents.viewContainers](NavigationIntents.md#viewcontainers) instead. +**`Deprecated`** + +:warning: It will be removed in a future version. Use [viewContainers](NavigationIntents.md#viewcontainers) instead. #### Returns @@ -165,7 +173,9 @@ Navigate to the container window in Docker Desktop. await window.ddClient.navigateToContainer(id); ``` -**`deprecated`** :warning: It will be removed in a future version. Use [NavigationIntents.viewContainer](NavigationIntents.md#viewcontainer) instead. +**`Deprecated`** + +:warning: It will be removed in a future version. #### Parameters @@ -194,7 +204,9 @@ Navigate to the container logs window in Docker Desktop. await window.ddClient.navigateToContainerLogs(id); ``` -**`deprecated`** :warning: It will be removed in a future version. Use {@link DockerDesktopClient.viewContainerLogs} instead. +**`Deprecated`** + +:warning: It will be removed in a future version. #### Parameters @@ -223,7 +235,9 @@ Navigate to the container inspect window in Docker Desktop. await window.ddClient.navigateToContainerInspect(id); ``` -**`deprecated`** :warning: It will be removed in a future version. Use {@link DockerDesktopClient.viewContainerInspect} instead. +**`Deprecated`** + +:warning: It will be removed in a future version. #### Parameters @@ -253,7 +267,9 @@ Navigate to the container stats to see the CPU, memory, disk read/write and netw await window.ddClient.navigateToContainerStats(id); ``` -**`deprecated`** :warning: It will be removed in a future version. Use {@link DockerDesktopClient.viewContainerStats} instead. +**`Deprecated`** + +:warning: It will be removed in a future version. #### Parameters @@ -282,7 +298,9 @@ Navigate to the images window in Docker Desktop. await window.ddClient.navigateToImages(id); ``` -**`deprecated`** :warning: It will be removed in a future version. Use [NavigationIntents.viewImages](NavigationIntents.md#viewimages) instead. +**`Deprecated`** + +:warning: It will be removed in a future version. Use [viewImages](NavigationIntents.md#viewimages) instead. #### Returns @@ -305,7 +323,9 @@ In this navigation route you can find the image layers, commands, created time a await window.ddClient.navigateToImage(id, tag); ``` -**`deprecated`** :warning: It will be removed in a future version. Use [NavigationIntents.viewImage](NavigationIntents.md#viewimage) instead. +**`Deprecated`** + +:warning: It will be removed in a future version. Use [viewImage](NavigationIntents.md#viewimage) instead. #### Parameters @@ -336,7 +356,9 @@ Navigate to the volumes window in Docker Desktop. await window.ddClient.navigateToVolumes(); ``` -**`deprecated`** :warning: It will be removed in a future version. Use [NavigationIntents.viewVolumes](NavigationIntents.md#viewvolumes) instead. +**`Deprecated`** + +:warning: It will be removed in a future version. Use [viewVolumes](NavigationIntents.md#viewvolumes) instead. #### Returns @@ -358,7 +380,9 @@ Navigate to a specific volume in Docker Desktop. window.ddClient.navigateToVolume(volume); ``` -**`deprecated`** :warning: It will be removed in a future version. Use [NavigationIntents.viewVolume](NavigationIntents.md#viewvolume) instead. +**`Deprecated`** + +:warning: It will be removed in a future version. Use [viewVolume](NavigationIntents.md#viewvolume) instead. #### Parameters @@ -386,7 +410,9 @@ Navigate to the Dev Environments window in Docker Desktop. window.ddClient.navigateToDevEnvironments(); ``` -**`deprecated`** :warning: It will be removed in a future version. Use [NavigationIntents.viewDevEnvironments](NavigationIntents.md#viewdevenvironments) instead. +**`Deprecated`** + +:warning: It will be removed in a future version. Use [viewDevEnvironments](NavigationIntents.md#viewdevenvironments) instead. #### Returns @@ -412,7 +438,9 @@ window.ddClient.execHostCmd(`cliShippedOnHost xxx`).then((cmdResult: any) => { }); ``` -**`deprecated`** :warning: It will be removed in a future version. Use [ExtensionCli.exec](ExtensionCli.md#exec) instead. +**`Deprecated`** + +:warning: It will be removed in a future version. Use [exec](ExtensionCli.md#exec) instead. #### Parameters @@ -450,7 +478,9 @@ window.ddClient.spawnHostCmd( ); ``` -**`deprecated`** :warning: It will be removed in a future version. Use [ExtensionCli.exec](ExtensionCli.md#exec) instead. +**`Deprecated`** + +:warning: It will be removed in a future version. Use [exec](ExtensionCli.md#exec) instead. #### Parameters @@ -472,7 +502,7 @@ ___ ### execDockerCmd -▸ **execDockerCmd**(`cmd`, ...`args`): `Promise`<[`ExecResultV0`](ExecResultV0.md)\> +▸ **execDockerCmd**(`cmd`, `...args`): `Promise`<[`ExecResultV0`](ExecResultV0.md)\> You can also directly execute the docker binary. @@ -480,7 +510,9 @@ You can also directly execute the docker binary. const output = await window.ddClient.execDockerCmd("info"); ``` -**`deprecated`** :warning: It will be removed in a future version. Use [DockerCommand.exec](DockerCommand.md#exec) instead. +**`Deprecated`** + +:warning: It will be removed in a future version. Use [exec](DockerCommand.md#exec) instead. #### Parameters @@ -507,7 +539,7 @@ For convenience, the command result object also has methods to easily parse it d - `output.parseJsonLines(): any[]` parses each output line as a json object. If the output of the command is too long, or you need to get the output as a stream you can use the -spawnDockerCmd function: + * spawnDockerCmd function: ```typescript window.ddClient.spawnDockerCmd("logs", ["-f", "..."], (data, error) => { @@ -525,7 +557,9 @@ ___ ▸ **spawnDockerCmd**(`cmd`, `args`, `callback`): `void` -**`deprecated`** :warning: It will be removed in a future version. Use [DockerCommand.exec](DockerCommand.md#exec) instead. +**`Deprecated`** + +:warning: It will be removed in a future version. Use [exec](DockerCommand.md#exec) instead. #### Parameters @@ -555,7 +589,9 @@ Opens an external URL with the system default browser. window.ddClient.openExternal("https://docker.com"); ``` -**`deprecated`** :warning: It will be removed in a future version. Use [Host.openExternal](Host.md#openexternal) instead. +**`Deprecated`** + +:warning: It will be removed in a future version. Use [openExternal](Host.md#openexternal) instead. #### Parameters @@ -585,7 +621,9 @@ Display a toast message of type success. window.ddClient.toastSuccess("message"); ``` -**`deprecated`** :warning: It will be removed in a future version. Use [Toast.success](Toast.md#success) instead. +**`Deprecated`** + +:warning: It will be removed in a future version. Use [success](Toast.md#success) instead. #### Parameters @@ -613,7 +651,9 @@ Display a toast message of type warning. window.ddClient.toastWarning("message"); ``` -**`deprecated`** :warning: It will be removed in a future version. Use [Toast.warning](Toast.md#warning) instead. +**`Deprecated`** + +:warning: It will be removed in a future version. Use [warning](Toast.md#warning) instead. #### Parameters @@ -641,7 +681,9 @@ Display a toast message of type error. window.ddClient.toastError("message"); ``` -**`deprecated`** :warning: It will be removed in a future version. Use [Toast.error](Toast.md#error) instead. +**`Deprecated`** + +:warning: It will be removed in a future version. Use [error](Toast.md#error) instead. #### Parameters diff --git a/desktop/extensions-sdk/dev/api/reference/interfaces/Exec.md b/desktop/extensions-sdk/dev/api/reference/interfaces/Exec.md index 8cc49b6d7a..f54fdbacaf 100644 --- a/desktop/extensions-sdk/dev/api/reference/interfaces/Exec.md +++ b/desktop/extensions-sdk/dev/api/reference/interfaces/Exec.md @@ -14,7 +14,9 @@ skip_read_time: true Executes a command. -**`since`** 0.2.0 +**`Since`** + +0.2.0 #### Parameters @@ -38,7 +40,9 @@ Streams the result of a command if `stream` is specified in the `options` parame Specify the `stream` if the output of your command is too long or if you need to stream things indefinitely (for example container logs). -**`since`** 0.2.2 +**`Since`** + +0.2.2 #### Parameters diff --git a/desktop/extensions-sdk/dev/api/reference/interfaces/ExecOptions.md b/desktop/extensions-sdk/dev/api/reference/interfaces/ExecOptions.md index 39e6cb3634..3662f0dc80 100644 --- a/desktop/extensions-sdk/dev/api/reference/interfaces/ExecOptions.md +++ b/desktop/extensions-sdk/dev/api/reference/interfaces/ExecOptions.md @@ -6,7 +6,9 @@ skip_read_time: true # Interface: ExecOptions -**`since`** 0.3.0 +**`Since`** + +0.3.0 ## Hierarchy diff --git a/desktop/extensions-sdk/dev/api/reference/interfaces/ExecProcess.md b/desktop/extensions-sdk/dev/api/reference/interfaces/ExecProcess.md index 3176f9bb66..cf1008df44 100644 --- a/desktop/extensions-sdk/dev/api/reference/interfaces/ExecProcess.md +++ b/desktop/extensions-sdk/dev/api/reference/interfaces/ExecProcess.md @@ -6,7 +6,9 @@ skip_read_time: true # Interface: ExecProcess -**`since`** 0.2.3 +**`Since`** + +0.2.3 ## Methods diff --git a/desktop/extensions-sdk/dev/api/reference/interfaces/ExecResult.md b/desktop/extensions-sdk/dev/api/reference/interfaces/ExecResult.md index c0d60c5d4f..6ce631ef71 100644 --- a/desktop/extensions-sdk/dev/api/reference/interfaces/ExecResult.md +++ b/desktop/extensions-sdk/dev/api/reference/interfaces/ExecResult.md @@ -6,7 +6,9 @@ skip_read_time: true # Interface: ExecResult -**`since`** 0.2.0 +**`Since`** + +0.2.0 ## Hierarchy diff --git a/desktop/extensions-sdk/dev/api/reference/interfaces/ExecStreamOptions.md b/desktop/extensions-sdk/dev/api/reference/interfaces/ExecStreamOptions.md index 0513195a2f..33c05f3049 100644 --- a/desktop/extensions-sdk/dev/api/reference/interfaces/ExecStreamOptions.md +++ b/desktop/extensions-sdk/dev/api/reference/interfaces/ExecStreamOptions.md @@ -6,28 +6,36 @@ skip_read_time: true # Interface: ExecStreamOptions -**`since`** 0.2.2 +**`Since`** -## Methods +0.2.2 + +## Properties ### onOutput -▸ `Optional` **onOutput**(`data`): `void` +• `Optional` **onOutput**: (`data`: { `stdout`: `string` ; `stderr?`: `undefined` } \| { `stdout?`: `undefined` ; `stderr`: `string` }) => `void` + +#### Type declaration + +▸ (`data`): `void` Invoked when receiving output from command execution. By default, the output is split into chunks at arbitrary boundaries. If you prefer the output to be split into complete lines, set `splitOutputLines` to true. The callback is then invoked once for each line. -**`since`** 0.2.0 +**`Since`** -#### Parameters +0.2.0 + +##### Parameters | Name | Type | Description | | :------ | :------ | :------ | | `data` | { `stdout`: `string` ; `stderr?`: `undefined` } \| { `stdout?`: `undefined` ; `stderr`: `string` } | output content. Can include either stdout string, or stderr string, one at a time. | -#### Returns +##### Returns `void` @@ -35,17 +43,21 @@ ___ ### onError -▸ `Optional` **onError**(`error`): `void` +• `Optional` **onError**: (`error`: `any`) => `void` + +#### Type declaration + +▸ (`error`): `void` Invoked to report error if the executed command errors. -#### Parameters +##### Parameters | Name | Type | Description | | :------ | :------ | :------ | | `error` | `any` | the error happening in the executed command | -#### Returns +##### Returns `void` @@ -53,21 +65,25 @@ ___ ### onClose -▸ `Optional` **onClose**(`exitCode`): `void` +• `Optional` **onClose**: (`exitCode`: `number`) => `void` + +#### Type declaration + +▸ (`exitCode`): `void` Invoked when process exits. -#### Parameters +##### Parameters | Name | Type | Description | | :------ | :------ | :------ | | `exitCode` | `number` | the process exit code | -#### Returns +##### Returns `void` -## Properties +___ ### splitOutputLines diff --git a/desktop/extensions-sdk/dev/api/reference/interfaces/Extension.md b/desktop/extensions-sdk/dev/api/reference/interfaces/Extension.md index aaff189e15..5f7e1fe628 100644 --- a/desktop/extensions-sdk/dev/api/reference/interfaces/Extension.md +++ b/desktop/extensions-sdk/dev/api/reference/interfaces/Extension.md @@ -6,7 +6,9 @@ skip_read_time: true # Interface: Extension -**`since`** 0.2.0 +**`Since`** + +0.2.0 ## Properties @@ -19,3 +21,13 @@ ___ ### host • `Optional` `Readonly` **host**: [`ExtensionHost`](ExtensionHost.md) + +___ + +### image + +• `Readonly` **image**: `string` + +**`Since`** + +0.3.3 diff --git a/desktop/extensions-sdk/dev/api/reference/interfaces/ExtensionCli.md b/desktop/extensions-sdk/dev/api/reference/interfaces/ExtensionCli.md index d37b691330..5ddfb7e935 100644 --- a/desktop/extensions-sdk/dev/api/reference/interfaces/ExtensionCli.md +++ b/desktop/extensions-sdk/dev/api/reference/interfaces/ExtensionCli.md @@ -6,7 +6,9 @@ skip_read_time: true # Interface: ExtensionCli -**`since`** 0.2.0 +**`Since`** + +0.2.0 ## Properties diff --git a/desktop/extensions-sdk/dev/api/reference/interfaces/ExtensionHost.md b/desktop/extensions-sdk/dev/api/reference/interfaces/ExtensionHost.md index 45db25be5f..86a5fad26c 100644 --- a/desktop/extensions-sdk/dev/api/reference/interfaces/ExtensionHost.md +++ b/desktop/extensions-sdk/dev/api/reference/interfaces/ExtensionHost.md @@ -6,7 +6,9 @@ skip_read_time: true # Interface: ExtensionHost -**`since`** 0.2.0 +**`Since`** + +0.2.0 ## Properties diff --git a/desktop/extensions-sdk/dev/api/reference/interfaces/ExtensionVM.md b/desktop/extensions-sdk/dev/api/reference/interfaces/ExtensionVM.md index 883a5e4388..e51834c1bb 100644 --- a/desktop/extensions-sdk/dev/api/reference/interfaces/ExtensionVM.md +++ b/desktop/extensions-sdk/dev/api/reference/interfaces/ExtensionVM.md @@ -6,7 +6,9 @@ skip_read_time: true # Interface: ExtensionVM -**`since`** 0.2.0 +**`Since`** + +0.2.0 ## Properties @@ -58,11 +60,17 @@ await ddClient.extension.vm.cli.exec("ls", ["-l"], { }); ``` -**`param`** Command to execute. +**`Param`** -**`param`** Arguments of the command to execute. +Command to execute. -**`param`** The callback function where to listen from the command output data and errors. +**`Param`** + +Arguments of the command to execute. + +**`Param`** + +The callback function where to listen from the command output data and errors. ___ diff --git a/desktop/extensions-sdk/dev/api/reference/interfaces/Host.md b/desktop/extensions-sdk/dev/api/reference/interfaces/Host.md index e31fcb115c..d8dc89c4e2 100644 --- a/desktop/extensions-sdk/dev/api/reference/interfaces/Host.md +++ b/desktop/extensions-sdk/dev/api/reference/interfaces/Host.md @@ -6,7 +6,9 @@ skip_read_time: true # Interface: Host -**`since`** 0.2.0 +**`Since`** + +0.2.0 ## Methods @@ -16,7 +18,9 @@ skip_read_time: true Opens an external URL with the system default browser. -**`since`** 0.2.0 +**`Since`** + +0.2.0 ```typescript ddClient.host.openExternal("https://docker.com"); @@ -40,7 +44,9 @@ ddClient.host.openExternal("https://docker.com"); Returns a string identifying the operating system platform. See https://nodejs.org/api/os.html#osplatform -**`since`** 0.2.2 +**`Since`** + +0.2.2 ___ @@ -50,7 +56,9 @@ ___ Returns the operating system CPU architecture. See https://nodejs.org/api/os.html#osarch -**`since`** 0.2.2 +**`Since`** + +0.2.2 ___ @@ -60,4 +68,6 @@ ___ Returns the host name of the operating system. See https://nodejs.org/api/os.html#oshostname -**`since`** 0.2.2 +**`Since`** + +0.2.2 diff --git a/desktop/extensions-sdk/dev/api/reference/interfaces/HttpService.md b/desktop/extensions-sdk/dev/api/reference/interfaces/HttpService.md index 7857637e6d..2b396bf86c 100644 --- a/desktop/extensions-sdk/dev/api/reference/interfaces/HttpService.md +++ b/desktop/extensions-sdk/dev/api/reference/interfaces/HttpService.md @@ -6,7 +6,9 @@ skip_read_time: true # Interface: HttpService -**`since`** 0.2.0 +**`Since`** + +0.2.0 ## Methods diff --git a/desktop/extensions-sdk/dev/api/reference/interfaces/NavigationIntents.md b/desktop/extensions-sdk/dev/api/reference/interfaces/NavigationIntents.md index b253b761ce..eada671eec 100644 --- a/desktop/extensions-sdk/dev/api/reference/interfaces/NavigationIntents.md +++ b/desktop/extensions-sdk/dev/api/reference/interfaces/NavigationIntents.md @@ -6,7 +6,9 @@ skip_read_time: true # Interface: NavigationIntents -**`since`** 0.2.0 +**`Since`** + +0.2.0 ## Container Methods diff --git a/desktop/extensions-sdk/dev/api/reference/interfaces/OpenDialogResult.md b/desktop/extensions-sdk/dev/api/reference/interfaces/OpenDialogResult.md index 7326e04b3b..47691f5dfa 100644 --- a/desktop/extensions-sdk/dev/api/reference/interfaces/OpenDialogResult.md +++ b/desktop/extensions-sdk/dev/api/reference/interfaces/OpenDialogResult.md @@ -6,7 +6,9 @@ skip_read_time: true # Interface: OpenDialogResult -**`since`** 0.2.3 +**`Since`** + +0.2.3 ## Properties diff --git a/desktop/extensions-sdk/dev/api/reference/interfaces/RawExecResult.md b/desktop/extensions-sdk/dev/api/reference/interfaces/RawExecResult.md index 47418e4944..f8341ffbcb 100644 --- a/desktop/extensions-sdk/dev/api/reference/interfaces/RawExecResult.md +++ b/desktop/extensions-sdk/dev/api/reference/interfaces/RawExecResult.md @@ -6,7 +6,9 @@ skip_read_time: true # Interface: RawExecResult -**`since`** 0.2.0 +**`Since`** + +0.2.0 ## Hierarchy diff --git a/desktop/extensions-sdk/dev/api/reference/interfaces/RequestConfig.md b/desktop/extensions-sdk/dev/api/reference/interfaces/RequestConfig.md index 76f78a73c9..41fbb6cc31 100644 --- a/desktop/extensions-sdk/dev/api/reference/interfaces/RequestConfig.md +++ b/desktop/extensions-sdk/dev/api/reference/interfaces/RequestConfig.md @@ -6,7 +6,9 @@ skip_read_time: true # Interface: RequestConfig -**`since`** 0.2.0 +**`Since`** + +0.2.0 ## Properties diff --git a/desktop/extensions-sdk/dev/api/reference/interfaces/ServiceError.md b/desktop/extensions-sdk/dev/api/reference/interfaces/ServiceError.md index baad7d9442..b3eeee13ef 100644 --- a/desktop/extensions-sdk/dev/api/reference/interfaces/ServiceError.md +++ b/desktop/extensions-sdk/dev/api/reference/interfaces/ServiceError.md @@ -9,7 +9,9 @@ skip_read_time: true Error thrown when an HTTP response is received with a status code that falls out to the range of 2xx. -**`since`** 0.2.0 +**`Since`** + +0.2.0 ## Properties diff --git a/desktop/extensions-sdk/dev/api/reference/interfaces/SpawnOptions.md b/desktop/extensions-sdk/dev/api/reference/interfaces/SpawnOptions.md index 8b1282f281..85d5d1304b 100644 --- a/desktop/extensions-sdk/dev/api/reference/interfaces/SpawnOptions.md +++ b/desktop/extensions-sdk/dev/api/reference/interfaces/SpawnOptions.md @@ -6,7 +6,9 @@ skip_read_time: true # Interface: SpawnOptions -**`since`** 0.3.0 +**`Since`** + +0.3.0 ## Hierarchy diff --git a/desktop/extensions-sdk/dev/api/reference/interfaces/Toast.md b/desktop/extensions-sdk/dev/api/reference/interfaces/Toast.md index dcf876fc80..b2fff77aae 100644 --- a/desktop/extensions-sdk/dev/api/reference/interfaces/Toast.md +++ b/desktop/extensions-sdk/dev/api/reference/interfaces/Toast.md @@ -10,7 +10,9 @@ Toasts provide a brief notification to the user. They appear temporarily and shouldn't interrupt the user experience. They also don't require user input to disappear. -**`since`** 0.2.0 +**`Since`** + +0.2.0 ## Methods diff --git a/desktop/extensions-sdk/dev/test-debug.md b/desktop/extensions-sdk/dev/test-debug.md index 29782ccaec..a574bd3d3e 100644 --- a/desktop/extensions-sdk/dev/test-debug.md +++ b/desktop/extensions-sdk/dev/test-debug.md @@ -26,7 +26,9 @@ After an extension is deployed, it is also possible to open Chrome DevTools from ### Hot reloading whilst developing the UI -During UI development, it’s helpful to use hot reloading to test your changes without rebuilding your entire extension. To do this, you can configure Docker Desktop to load your UI from a development server, such as the one Create React App starts when invoked with yarn start. +During UI development, it’s helpful to use hot reloading to test your changes without rebuilding your entire +extension. To do this, you can configure Docker Desktop to load your UI from a development server, such as the one +[Vite](https://vitejs.dev/) starts when invoked with `npm start`. Assuming your app runs on the default port, start your UI app and then run: @@ -35,12 +37,12 @@ $ cd ui $ npm run dev ``` -This starts a development server that listens on port 5173. +This starts a development server that listens on port 3000. You can now tell Docker Desktop to use this as the frontend source. In another terminal run: ```console -$ docker extension dev ui-source http://localhost:5173 +$ docker extension dev ui-source http://localhost:3000 ``` Close and reopen the Docker Desktop dashboard and go to your extension. All the changes to the frontend code are immediately visible. @@ -55,7 +57,7 @@ $ docker extension dev reset If your extension is composed of one or more services running as containers in the Docker Desktop VM, you can access them easily from the dashboard in Docker Desktop. -1. In Docker Desktop, navigate to **Settings** or **Preferences** if you’re a Mac user. +1. In Docker Desktop, navigate to **Settings**. 2. Under the **Extensions** tab, select the **Show Docker Desktop Extensions system containers** option. You can now view your extension containers and their logs. diff --git a/desktop/extensions-sdk/extensions/DISTRIBUTION.md b/desktop/extensions-sdk/extensions/DISTRIBUTION.md index 18ff42db98..b16229795a 100644 --- a/desktop/extensions-sdk/extensions/DISTRIBUTION.md +++ b/desktop/extensions-sdk/extensions/DISTRIBUTION.md @@ -15,7 +15,7 @@ The Docker image must have several [image labels](labels.md), providing informat > See how to use [extension labels](labels.md) to provide extension overview information. -To Package and release an extension, you must build a Docker image (`docker build`), and push the image to [DockerHub](https://hub.docker.com/){: target="_blank" rel="noopener" class="_" } (`docker push`) with a specific tag that allows you to manage versions of the extension. +To package and release an extension, you must build a Docker image (`docker build`), and push the image to [DockerHub](https://hub.docker.com/){: target="_blank" rel="noopener" class="_" } (`docker push`) with a specific tag that allows you to manage versions of the extension. ## Release your extension @@ -42,7 +42,7 @@ Users can download and install the newer version of any extension without updati ## Extension API dependencies -Extensions must specify the Extension API version they rely on. Docker Desktop will check the extension required version, and only propose to install extensions that are compatible with the current Docker Desktop installed. Users might need to update Docker Desktop in order to install the latest extensions available. +Extensions must specify the Extension API version they rely on. Docker Desktop checks the extension required version, and only propose to install extensions that are compatible with the current Docker Desktop installed. Users might need to update Docker Desktop in order to install the latest extensions available. Extension image labels must specify the API version that the extension relies upon. This allows Docker Desktop to inspect newer versions of extension images without downloading the full extension image upfront. diff --git a/desktop/extensions-sdk/extensions/images/open-share.PNG b/desktop/extensions-sdk/extensions/images/open-share.PNG deleted file mode 100644 index 64b16a68a4..0000000000 Binary files a/desktop/extensions-sdk/extensions/images/open-share.PNG and /dev/null differ diff --git a/desktop/extensions-sdk/extensions/index.md b/desktop/extensions-sdk/extensions/index.md index 95f5f08017..060d4d6c6b 100644 --- a/desktop/extensions-sdk/extensions/index.md +++ b/desktop/extensions-sdk/extensions/index.md @@ -4,7 +4,7 @@ description: General steps in how to publish an extension keywords: Docker, Extensions, sdk, publish --- -This section describes how to make your extension available, and how to make your extension more visible so users can discover it and install it in a single click. +This section describes how to make your extension available and more visible, so users can discover it and install it with a single click. ## Release your extension @@ -12,32 +12,34 @@ You have developed your extension and tested it locally. You are now ready to re Releasing your extension consists of: -- Provide information about your extension: description, screenshots, etc. so users can decide to install your extension -- [Validate](./validate.md) the extension is built in the right format and includes the required information -- Make the extension image available on [Docker Hub](https://hub.docker.com/){: target="_blank" rel="noopener" class="_" }: +- Providing information about your extension: description, screenshots, etc. so users can decide to install your extension +- [Validating](./validate.md) that the extension is built in the right format and includes the required information +- Making the extension image available on [Docker Hub](https://hub.docker.com/){: target="_blank" rel="noopener" class="_" } -See [Package and release your extension](DISTRIBUTION.md) for details about the release process. +See [Package and release your extension](DISTRIBUTION.md) for more details about the release process. ## Promote your extension Once your extension is available on Docker Hub, users who have access to the extension image can install it using the Docker CLI. -However, you might want a better way to make your extension visible and easy to install than copy-pasting CLI commands in a terminal. ### Use a share extension link -You can [generate a share URL](share.md) in order to share your extension within your team, or promote your extension on the internet (website, blogs, social media...). This will allow users to view the extension description and screenshots, and decide to install it in a single click. +You can also [generate a share URL](share.md) in order to share your extension within your team, or promote your extension on the internet. The share link allows users to view the extension description and screenshots. ### Publish your extension in the Marketplace -You can publish your extension in the Extension marketplace to make it more discoverable. You must [submit your extension](publish.md) if you want to have it published in the marketplace. +You can publish your extension in the Extensions Marketplace to make it more discoverable. You must [submit your extension](publish.md) if you want to have it published in the Marketplace. ## What happens next ### Extension new releases Once you have released your extension, you can push a new release just by pushing a new version of the extension image, with an incremented tag (still using semver conventions). -Docker extensions published in the marketplace will benefit from update notifications to all Desktop users that have installed the extension. See more details about [new releases and updates](DISTRIBUTION.md#new-releases-and-updates) +Docker extensions published in the Marketplace benefit from update notifications to all Desktop users that have installed the extension. For more details, see [new releases and updates](DISTRIBUTION.md#new-releases-and-updates) ### Extension support and user feedback -In addition to provide a description of you extension features, and screenshots, you should also specify additional URLs in [extension labels](labels.md). This will direct users to your website for reporting bugs and feedback, and accessing documentation and support. +In addition to providing a description of your extension's features and screenshots, you should also specify additional URLs using [extension labels](labels.md). This direct users to your website for reporting bugs and feedback, and accessing documentation and support. + +{% include extensions-form.md %} + diff --git a/desktop/extensions-sdk/extensions/labels.md b/desktop/extensions-sdk/extensions/labels.md index 09cc72ff0f..aa126a2e69 100644 --- a/desktop/extensions-sdk/extensions/labels.md +++ b/desktop/extensions-sdk/extensions/labels.md @@ -4,11 +4,11 @@ description: Docker extension labels keywords: Docker, extensions, sdk, labels --- -Extensions use image labels to provide additional information like title, description, screenshots, and more. +Extensions use image labels to provide additional information such as title, description, screenshots, and more. -These information allow to display an overview of the extension to users so they can choose to install it: +This information is then displayed as an overview of the extension, so users can choose to install it -![List preview](images/marketplace-details.png) +![An extension overveiw, generated from labels](images/marketplace-details.png) You can define [Image labels](../../../engine/reference/builder.md#label) in the extension's `Dockerfile`. @@ -21,13 +21,13 @@ Here is the list of labels you need to specify when building your extension: | `org.opencontainers.image.vendor` | Yes | Name of the distributing entity, organization, or individual. | Acme, Inc. | | `com.docker.desktop.extension.api.version` | Yes | Version of the Docker Extension manager that the extension is compatible with. It must follow [semantic versioning](https://semver.org/). | A specific version like `0.1.0` or, a constraint expression: `>= 0.1.0`, `>= 1.4.7, < 2.0` . For your first extension, you can use `docker extension version` to know the SDK API version and specify `>= `. | | `com.docker.desktop.extension.icon` | Yes | The extension icon (format: .svg .png .jpg) | {{ site.docs_url }}/assets/images/engine.svg | -| `com.docker.extension.screenshots` | Yes | A JSON array of image URLs and an alternative text displayed to users (in the order they appear in your metadata) in your extension's details page. **Note:** The recommended size for screenshots is 2400x1600 pixels. | `"[{"alt":"alternative text for image 1",` `"url":"https://foo.bar/image1.png"},` `{"alt":"alternative text for image2",` `"url":"https://foo.bar/image2.jpg"}]"` | +| `com.docker.extension.screenshots` | Yes | A JSON array of image URLs and an alternative text displayed to users (in the order they appear in your metadata) in your extension's details page. **Note:** The recommended size for screenshots is 2400x1600 pixels. | `[{"alt":"alternative text for image 1",` `"url":"https://foo.bar/image1.png"},` `{"alt":"alternative text for image2",` `"url":"https://foo.bar/image2.jpg"}]` | | `com.docker.extension.detailed-description` | Yes | Additional information in plain text or HTML about the extension to display in the details dialog. | `My detailed description` or `

    My detailed description

    ` | | `com.docker.extension.publisher-url` | Yes | The publisher website URL to display in the details dialog. | `https://foo.bar` | | `com.docker.extension.additional-urls` | No | A JSON array of titles and additional URLs displayed to users (in the order they appear in your metadata) in your extension's details page. Docker recommends you display the following links if they apply: documentation, support, terms of service, and privacy policy links. | `[{"title":"Documentation","url":"https://foo.bar/docs"},` `{"title":"Support","url":"https://foo.bar/support"},` `{"title":"Terms of Service","url":"https://foo.bar/tos"},` `{"title":"Privacy policy","url":"https://foo.bar/privacy-policy"}]` | | `com.docker.extension.changelog` | Yes | Changelog in plain text or HTML containing the change for the current version only. | `Extension changelog` or `

    Extension changelog

      ` `
    • New feature A
      • ` `
    • Bug fix on feature B

    ` | | `com.docker.extension.account-info` | No | Whether the user needs to register to a SaaS platform to use some features of the extension. | `required` in case it does, leave it empty otherwise. | -| `com.docker.extension.categories` | No | The list of Marketplace categories that your extension belongs to: `ci-cd`, `container-orchestration`, `cloud-deployment`, `cloud-development`, `database`, `kubernetes`, `networking`, `security`,`testing-tools`, `utility-tools`,`volumes`. If you don't specify this label, users won't be able to find your extension in the Extension Marketplace when filtering by a category. Extensions published to the Marketplace before the 22nd of September 2022 have been auto-categorized by Docker. | Specified as comma separated values in case of having multiple categories e.g: `kubernetes,security` or a single value e.g. `kubernetes`. | +| `com.docker.extension.categories` | No | The list of Marketplace categories that your extension belongs to: `ci-cd`, `container-orchestration`, `cloud-deployment`, `cloud-development`, `database`, `kubernetes`, `networking`, `security`,`testing-tools`, `utility-tools`,`volumes`. If you don't specify this label, users won't be able to find your extension in the Extensions Marketplace when filtering by a category. Extensions published to the Marketplace before the 22nd of September 2022 have been auto-categorized by Docker. | Specified as comma separated values in case of having multiple categories e.g: `kubernetes,security` or a single value e.g. `kubernetes`. | > Missing required labels > @@ -35,7 +35,7 @@ Here is the list of labels you need to specify when building your extension: > HTML content styling > -> Docker Desktop will apply CSS styles to the provided HTML content. You can make sure that it renders correctly +> Docker Desktop applies CSS styles to the provided HTML content. You can make sure that it renders correctly > [within the marketplace](#preview-the-extension-in-the-marketplace). Docker recommends that you follow the > [Styling guidelines](../design/index.md). @@ -43,7 +43,7 @@ Here is the list of labels you need to specify when building your extension: You can validate that the image labels render as you expect. -When you build and install your unpublished extension, you can preview the extension in the Marketplace "installed" tab. You can see how the extension labels render in the list and in the details page of the extension. +When you build and install your unpublished extension, you can preview the extension in the Marketplace **Managed** tab. You can see how the extension labels render in the list and in the details page of the extension. > Preview extensions already listed in Marketplace > @@ -53,5 +53,3 @@ When you build and install your unpublished extension, you can preview the exten > Use `docker tag org/published-extension unpublished-extension` and then `docker extension install unpublished-extension`. ![List preview](images/list-preview.png) - -![List preview](images/details-preview.png) diff --git a/desktop/extensions-sdk/extensions/multi-arch.md b/desktop/extensions-sdk/extensions/multi-arch.md index d7b2ae4b2a..666ec24cbd 100644 --- a/desktop/extensions-sdk/extensions/multi-arch.md +++ b/desktop/extensions-sdk/extensions/multi-arch.md @@ -93,7 +93,7 @@ FROM alpine LABEL org.opencontainers.image.title="example-extension" \ org.opencontainers.image.description="My Example Extension" \ org.opencontainers.image.vendor="Docker Inc." \ - com.docker.desktop.extension.api.version=">= 0.1.0" + com.docker.desktop.extension.api.version=">= 0.3.3" COPY --from=dl /out / ``` @@ -140,8 +140,6 @@ As a result, when `TARGETARCH` equals: When the extension is installed, the extension framework copies the binaries from the extension image at `/darwin/kubectl` for Darwin, or `/windows/kubectl.exe` for Windows, to a specific location in the user’s host filesystem. -## FAQs +## Can I develop extensions that run Windows containers? -### Can I develop extensions that run Windows containers? - -Although Docker Extensions is supported on Docker Desktop for Windows, Mac, and Linux, the extension framework only supports linux containers. Therefore, you must target `linux` as the OS when you build your extension image. +Although Docker Extensions is supported on Docker Desktop for Windows, Mac, and Linux, the extension framework only supports Linux containers. Therefore, you must target `linux` as the OS when you build your extension image. diff --git a/desktop/extensions-sdk/extensions/publish.md b/desktop/extensions-sdk/extensions/publish.md index efdaadfce1..e9d9b4940b 100644 --- a/desktop/extensions-sdk/extensions/publish.md +++ b/desktop/extensions-sdk/extensions/publish.md @@ -14,13 +14,13 @@ All extensions submitted to the Extension Marketplace are reviewed and approved ### Before you submit -Ensure your extension has followed the guidelines outlined in this section before submitting for your extension for review. Docker highly encourage you to check the guidelines as not doing so may considerably impact the duration of the approval process. +Ensure your extension has followed the guidelines outlined in this section before submitting for your extension for review. Docker highly encourages you to check the guidelines as not doing so may considerably impact the duration of the approval process. These guidelines don't replace Docker's terms of service or guarantee approval. As the Extension Marketplace continues adding new features for both Extension users and publishers, expect that you maintain your extension over time to ensure it stays available in the Marketplace. #### Guidelines: -- Ensure that you’ve ran the [validation checks](validate.md) +- Ensure that you’ve run the [validation checks](validate.md) - Review the [design guidelines](../design/design-guidelines.md) - Ensure the [UI styling](../design/index.md) is in line with Docker Desktop guidelines - Ensure your extensions support both light and dark mode diff --git a/desktop/extensions-sdk/guides/invoke-host-binaries.md b/desktop/extensions-sdk/guides/invoke-host-binaries.md index 80f4300ae1..1a060e074f 100644 --- a/desktop/extensions-sdk/guides/invoke-host-binaries.md +++ b/desktop/extensions-sdk/guides/invoke-host-binaries.md @@ -4,11 +4,13 @@ description: Add invocations to host binaries from the frontend with the extensi keywords: Docker, extensions, sdk, build --- -In some cases, your extension needs to invoke some command from the host (the computer of your users). For example, you +In some cases, your extension needs to invoke some command from the host. For example, you might want to invoke the CLI of your cloud provider to create a new resource, or the CLI of a tool your extension -provides, or even a shell script that you want to run on the host. You could do that executing the CLI from a container with the extension SDK. But this CLI needs to access the host's -filesystem, which isn't easy nor fast if it runs in a container. -Host binaries allow exactly this: to invoke from the extension executables (as binaries, shell scripts) +provides, or even a shell script that you want to run on the host. + +You could do that by executing the CLI from a container with the extension SDK. But this CLI needs to access the host's filesystem, which isn't easy nor fast if it runs in a container. + +However host binaries invoke from the extension executables (as binaries, shell scripts) shipped as part of your extension and deployed to the host. As extensions can run on multiple platforms, this means that you need to ship the executables for all the platforms you want to support. @@ -18,7 +20,7 @@ Learn more about extensions [architecture](../architecture/index.md). > > Only executables shipped as part of the extension can be invoked with the SDK. -In this example, this CLI will be a simple `Hello world` script that must be invoked with a parameter and will return a +In this example, the CLI is a simple `Hello world` script that must be invoked with a parameter and returns a string. ## Add the executables to the extension @@ -97,8 +99,9 @@ export function App() {
    > **Important** +> > We don't have an example for Vue yet. [Fill out the form](https://docs.google.com/forms/d/e/1FAIpQLSdxJDGFJl5oJ06rG7uqtw1rsSBZpUhv_s9HHtw80cytkh2X-Q/viewform?usp=pp_url&entry.1333218187=Vue){: target="_blank" rel="noopener" class="_"} -> and let us know you'd like a sample with Vue. +> and let us know if you'd like a sample with Vue. {: .important } @@ -107,8 +110,9 @@ export function App() {
    > **Important** +> > We don't have an example for Angular yet. [Fill out the form](https://docs.google.com/forms/d/e/1FAIpQLSdxJDGFJl5oJ06rG7uqtw1rsSBZpUhv_s9HHtw80cytkh2X-Q/viewform?usp=pp_url&entry.1333218187=Angular){: target="_blank" rel="noopener" class="_"} -> and let us know you'd like a sample with Angular. +> and let us know if you'd like a sample with Angular. {: .important } @@ -117,8 +121,9 @@ export function App() {
    > **Important** +> > We don't have an example for Svelte yet. [Fill out the form](https://docs.google.com/forms/d/e/1FAIpQLSdxJDGFJl5oJ06rG7uqtw1rsSBZpUhv_s9HHtw80cytkh2X-Q/viewform?usp=pp_url&entry.1333218187=Svelte){: target="_blank" rel="noopener" class="_"} -> and let us know you'd like a sample with Svelte. +> and let us know if you'd like a sample with Svelte. {: .important } @@ -126,8 +131,8 @@ export function App() { ## Configure the metadata file -The host binaries must be specified in the `metadata.json` so that Docker Desktop copies them on the host when installing -the extension. Once the extension is uninstalled, the binaries that were copied will be removed as well. +The host binaries must be specified in the `metadata.json` so that Docker Desktop copies them on to the host when installing +the extension. Once the extension is uninstalled, the binaries that were copied are removed as well. ```json { diff --git a/desktop/extensions-sdk/guides/oauth2-flow.md b/desktop/extensions-sdk/guides/oauth2-flow.md index ac3d8d483d..5f24082dee 100644 --- a/desktop/extensions-sdk/guides/oauth2-flow.md +++ b/desktop/extensions-sdk/guides/oauth2-flow.md @@ -14,15 +14,16 @@ Learn how you can let users authenticate from your Docker Extension using OAuth In OAuth 2.0, the term "grant type" refers to the way an application gets an access token. Although OAuth 2.0 defines several grant types, this page only describes how to authorize users from your Docker Extension using the Authorization Code grant type. -## Authorization Code grant flow +## Authorization code grant flow The Authorization Code grant type is used by confidential and public clients to exchange an authorization code for an access token. After the user returns to the client via the redirect URL, the application gets the authorization code from the URL and uses it to request an access token. -![oauth2-flow](images/oauth2-flow.png){: style=width:80% } +![Flow for OAuth 2.0](images/oauth2-flow.png){: style=width:80% } The image above shows that: + - The Docker Extension asks the user to authorize access to their data. - If the user grants access, the Docker Extension then requests an access token from the service provider, passing the access grant from the user and authentication details to identify the client. - The service provider then validates these details and returns an access token. @@ -33,9 +34,9 @@ The image above shows that: - Auth URL: The endpoint for the API provider authorization server, to retrieve the auth code. - Redirect URI: The client application callback URL to redirect to after auth. This must be registered with the API provider. -Once the user enters the username and password, they are successfully authenticated. +Once the user enters the username and password, they're successfully authenticated. -## Step One: Open a browser page to authenticate the user +## Open a browser page to authenticate the user From the extension UI, you can provide a button that, when selected, opens a new window in a browser to authenticate the user. @@ -46,46 +47,29 @@ example: window.ddClient.openExternal("https://authorization-server.com/authorize? response_type=code &client_id=T70hJ3ls5VTYG8ylX3CZsfIu - &redirect_uri=${REDIRECT_URI} - &scope=photo+offline_access - &state=kH_0FdAtjCfYjOkF); + &redirect_uri=${REDIRECT_URI}); ``` -## Step Two: Get the authorization code and access token +## Get the authorization code and access token -### From the extension UI +You can get the authorization code from the extension UI by listing `docker-desktop://dashboard/extension-tab?extensionId=awesome/my-extension` as the `redirect_uri` in the OAuth app you're using and concatenating the authorization code as a query parameter. The extension UI code will then be able to read the corresponding code query-param. -> **Passing the access token** -> -> Currently, passing the authorization code as a query parameter to the `docker-desktop://dashboard/open` URL is not supported. +> Note +> using this feature requires the extension SDK 0.3.3 in Docker Desktop. You need to ensure that the required SDK version for your extension set with `com.docker.desktop.extension.api.version` in [image labels](../extensions/labels.md) is higher than 0.3.3. {: .important} -You cannot get the authorization code from the extension UI by listing `docker-desktop://dashboard/open` as the `redirect_uri` in the OAuth app you're using and concatenating the authorization code as a query parameter. - -See [from backend service](#from-a-backend-service) instead. - -### From a backend service - -You need a backend service running as part of your extension to handle the OAuth 2.0 flow. For this, you must ensure the Redirect URI is registered with the API provider to redirect to that location after OAuth has completed, e.g. `http://localhost:8080/callback`. - -The default communication is socket-based. The backend service needs to expose the port in order for the browser to connect to it. - #### Authorization -This step is where the user enters their credentials in the browser. After the authorization is complete, the user is redirected back to your backend service, and you'll consume the authorization code that is part of the query parameters in the URL. - -How you consume the query parameters depends on the technology that is used by the backend service. +This step is where the user enters their credentials in the browser. After the authorization is complete, the user is redirected back to your extension user interface, and the extension UI code can consume the authorization code that's part of the query parameters in the URL. #### Exchange the Authorization Code Next, you exchange the authorization code for an access token. -The backend service must build a `POST` request to the token endpoint with the following parameters: +The extension must send a `POST` request to the oauth authorization server with the following parameters: ``` POST https://authorization-server.com/token - -grant_type=authorization_code &client_id=T70hJ3ls5VTYG8ylX3CZsfIu &client_secret=YABbyHQShPeO1T3NDQZP8q5m3Jpb_UPNmIzqhLDCScSnRyVG &redirect_uri=${REDIRECT_URI} @@ -94,14 +78,9 @@ grant_type=authorization_code > **Note** > -> The client's credentials are included in the `POST` body in this example. Other authorization servers may require that the credentials are sent as a HTTP Basic Authentication header. - -#### Token Endpoint Response - -Finally, you can read the access token from the HTTP response and pass it to the extension UI by having the browser after OAuth be redirected to the backend service. The backend service, in turn, has to explicitly redirect the browser to `docker-desktop://dashboard/open`. - -## Step three: Store the access token +> The client's credentials are included in the `POST` query params in this example. OAuth authorization servers may require that the credentials are sent as a HTTP Basic Authentication header or might support different formats. See your OAuth provider docs for details. +### Store the access token The Docker Extensions SDK doesn't currently provide a specific mechanism to store secrets. diff --git a/desktop/extensions-sdk/guides/security.md b/desktop/extensions-sdk/guides/security.md index 510c25759a..1e031ba648 100644 --- a/desktop/extensions-sdk/guides/security.md +++ b/desktop/extensions-sdk/guides/security.md @@ -6,30 +6,18 @@ keywords: Docker, extensions, sdk, security ## Extension capabilities -An extension can have the following optional parts; a user interface in HTML or JavaScript, a backend part that runs as a container, and executables deployed on the host machine. +An extension can have the following optional parts: +* A user interface in HTML or JavaScript, displayed in Docker Desktop Dashboard +* A backend part that runs as a container +* Executables deployed on the host machine. -Extensions are executed with the same permissions as the Docker Desktop user. Extension capabilities include running any docker commands (including running containers and mounting folders), running extension binaries, and accessing files on your machine. +Extensions are executed with the same permissions as the Docker Desktop user. Extension capabilities include running any Docker commands (including running containers and mounting folders), running extension binaries, and accessing files on your machine that are accessible by the user running Docker Desktop. -The Extensions SDK provides a set of JavaScript APIs to invoke commands or execute these binaries from the extension UI code. Extensions can also provide a backend part that starts a long-lived running container in the background. +The Extensions SDK provides a set of JavaScript APIs to invoke commands or invoke these binaries from the extension UI code. Extensions can also provide a backend part that starts a long-lived running container in the background. + +> **Important** +> +> Make sure you trust the publisher or author of the extension when you install it, as the extension has the same access rights as the user running Docker Desktop. +{: .important} Learn more in the [architecture section](https://docs.docker.com/desktop/extensions-sdk/architecture/) - -An extension's code is loaded into the Docker Desktop UI electron app. The extension UI code is subject to some constraints for security reasons, described below. - -## Sandboxing - -Extension UI code is rendered in a sandboxed environment and does not have a node.js environment initialized, nor direct access to the electron APIs. -The extension UI code cannot perform privileged tasks, such as making changes to the system, or spawning subprocesses, except by using the SDK APIs provided with the extension framework. -It can also perform interactions with Docker Desktop, such as navigating to various places in the Dashboard, only through the extension SDK APIs. - -## Extension isolation - -Extensions are isolated from each other and extension UI code is running in its own session for each extension. Extensions cannot access other extensions’ session data. - -`localStorage` is one of the mechanisms of a browser’s web storage. It allows users to save data as key-value pairs in the browser for later use. `localStorage` does not clear data when the browser (the extension pane) closes. This makes it ideal for persisting data when navigating out of the extension to other parts of Docker Desktop. - -If your extension uses `localStorage` to store data, other extensions running in Docker Desktop cannot access the local storage of your extension. The extension’s local storage is persisted even after Docker Desktop is stopped or restarted. When an extension is upgraded, its local storage is persisted, whereas when it is uninstalled, its local storage is completely removed. - -## Cross site-scripting - -CORS rules are enforced with same-origin policy enabled, so the extension UI code cannot load external scripts. diff --git a/desktop/extensions-sdk/guides/use-docker-socket-from-backend.md b/desktop/extensions-sdk/guides/use-docker-socket-from-backend.md index d504c8f04e..271af392e8 100644 --- a/desktop/extensions-sdk/guides/use-docker-socket-from-backend.md +++ b/desktop/extensions-sdk/guides/use-docker-socket-from-backend.md @@ -4,13 +4,14 @@ description: Docker extension metadata keywords: Docker, extensions, sdk, metadata --- -Docker extensions can invoke Docker commands directly from the frontend with the SDK. In some cases, it is useful to also +Extensions can invoke Docker commands directly from the frontend with the SDK. In some cases, it is useful to also interact with the Docker engine from the backend. Extension backend containers can mount the Docker socket and use it to -interact with the Docker engine from the extension backend logic. (Learn more about the [Docker engine socket](/engine/reference/commandline/dockerd/#examples)) +interact with the Docker engine from the extension backend logic. Learn more about the [Docker engine socket](/engine/reference/commandline/dockerd/#examples)) However, when mounting the Docker socket from an extension container that lives in the Desktop virtual machine, you want to mount the Docker socket from inside the VM, and not mount `/var/run/docker.sock` from the host filesystem (using the Docker socket from the host can lead to permission issues in containers). + In order to do so, you can use `/var/run/docker.sock.raw`. Docker Desktop mounts the socket that lives in the Desktop VM, and not from the host. ```yaml diff --git a/desktop/extensions-sdk/index.md b/desktop/extensions-sdk/index.md index 88b680c9ec..266294d6f8 100644 --- a/desktop/extensions-sdk/index.md +++ b/desktop/extensions-sdk/index.md @@ -3,23 +3,20 @@ title: Overview description: Overall index for Docker Extensions SDK documentation keywords: Docker, Extensions, sdk redirect_from: - - /desktop/extensions-sdk/dev/overview/ + - /desktop/extensions-sdk/dev/overview/ --- Use the resources in this section to create your own Docker Extension. -> Beta -> -> The Docker Extensions SDK is currently in [Beta](../../release-lifecycle.md#beta). -> Features and APIs detailed below are subject to change. - Extensions are packaged as specially formatted Docker images, which our CLI tool helps to build. At the root of the image filesystem is a `metadata.json` file which describes the content of the extension. It is a fundamental element of a Docker extension. An extension can contain a UI part and backend parts that run either on the host or in the Desktop virtual machine. -For further details, see the [architecture page](architecture/index.md). +For further information, see [Architecture](architecture/index.md). + +Extensions are distributed through Docker Hub. However, development of extensions can be done locally without the need to push the extension to Docker Hub. See [Extensions distribution](extensions/DISTRIBUTION.md) for further details. + +{% include extensions-form.md %} -Extensions are distributed through the Docker Hub. -Development of extensions can be done locally without the need to push the extension to Docker Hub. See [Extensions distribution](extensions/DISTRIBUTION.md) for further details.
    @@ -48,7 +45,7 @@ Development of extensions can be done locally without the need to push the exten Design quidelines

    View the design guidelines

    -

    Ensure your extension aligns to Docker's design guidelines and principles

    +

    Ensure your extension aligns to Docker's design guidelines and principles.

    @@ -69,7 +66,7 @@ Development of extensions can be done locally without the need to push the exten Kubernetes

    Interacting with Kubernetes

    -

    Find information on how to interact indirectly with a Kubernetes cluster from your Docker extension.

    +

    Find information on how to interact indirectly with a Kubernetes cluster from your Docker Extension.

    diff --git a/desktop/extensions-sdk/process.md b/desktop/extensions-sdk/process.md index f2d9503c65..ef7fc9f766 100644 --- a/desktop/extensions-sdk/process.md +++ b/desktop/extensions-sdk/process.md @@ -24,11 +24,13 @@ For further inspiration, see the other examples in the [samples folder](https:// ### Part two: Publish and distribute your extension -Docker Desktop displays published extensions in the Extensions Marketplace. The Extensions Marketplace is a curated space where developers from all over can discover extensions to improve their developer experience and upload their own extension to share with the world. +Docker Desktop displays published extensions in the Extensions Marketplace. The Extensions Marketplace is a curated space where developers can discover extensions to improve their developer experience and upload their own extension to share with the world. -All extensions submitted to the Extension Marketplace are reviewed and approved by our team before listing. This review process ensures a level of trust, security, and quality for developers using Extensions and allows for Extension developers to get feedback on what will improve their Extensions experience. +All extensions submitted to the Extensions Marketplace are reviewed and approved by our team before listing. This review process ensures a level of trust, security, and quality for developers using extensions and allows for extension developers to recieve feedback and then improve their extension experience. -If you want your extension to be published in the Marketplace, you can submit your extension [here](https://www.docker.com/products/extensions/submissions/){:target="_blank" rel="noopener" class="_"}. We’ll review your submission and provide feedback if changes are needed before we can validate and publish it to make it available to all Docker Desktop users. +If you want your extension to be published in the Marketplace, you can submit your extension [here](https://www.docker.com/products/extensions/submissions/){:target="_blank" rel="noopener" class="_"}. We’ll review your submission and provide feedback if changes are needed before we validate and publish it to make it available to all Docker Desktop users. + +{% include extensions-form.md %} ## What’s next? diff --git a/desktop/extensions-sdk/quickstart.md b/desktop/extensions-sdk/quickstart.md index 45e0f27fd4..60081a05ed 100644 --- a/desktop/extensions-sdk/quickstart.md +++ b/desktop/extensions-sdk/quickstart.md @@ -8,16 +8,16 @@ redirect_from: Follow the guide below to build a basic Docker Extension quickly. The Quickstart guide automatically generates boilerplate files for you. -> Note -> -> NodeJS and Go are only required when you follow the quickstart guide to build an extension. It uses the `docker extension init` command to automatically generate boilerplate files. This command uses a template based on a ReactJS and Go application. - ## Prerequisites - [Docker Desktop](../release-notes.md) - [NodeJS](https://nodejs.org/){:target="_blank" rel="noopener" class="_"} - [Go](https://go.dev/dl/){:target="_blank" rel="noopener" class="_"} +> Note +> +> NodeJS and Go are only required when you follow the quickstart guide to build an extension. It uses the `docker extension init` command to automatically generate boilerplate files. This command uses a template based on a ReactJS and Go application. + ## Step one: Set up your directory To set up your directory, use the `init` subcommand and provide a name for your extension. @@ -79,6 +79,7 @@ To remove the extension, run: ```console $ docker extension rm ``` +{% include extensions-form.md %} ## What's next diff --git a/desktop/extensions/index.md b/desktop/extensions/index.md index f1e20622a8..a879444b90 100644 --- a/desktop/extensions/index.md +++ b/desktop/extensions/index.md @@ -6,21 +6,17 @@ toc_min: 1 toc_max: 2 --- -> **Beta** -> -> This feature is currently in [Beta](../../release-lifecycle.md#beta). We recommend that you do not use Docker Extensions in production environments. - -Docker Extensions lets you use third-party tools within Docker Desktop to extend its functionality. +Docker Extensions let you use third-party tools within Docker Desktop to extend its functionality. You can seamlessly connect your favorite development tools to your application development and deployment workflows. Augment Docker Desktop with debugging, testing, security, and networking functionalities, and build custom add-ons using the Extensions [SDK](../extensions-sdk/index.md). -Anyone can use Docker Extensions and there is no limit to the number of extensions you can install. +Anyone can use Docker Extensions and there is no limit to the number of extensions you can install. -![extenstions](../images/extensions-marketplace.PNG){:width="750px"} +![Extensions Marketplace](../images/marketplace.png){:width="750px"} ## What extensions are available? -There is a mix of partner and community-built extensions and Docker-built extensions. +There is a mix of partner and community-built extensions and Docker-built extensions. You can explore the list of available extensions in [Docker Hub](https://hub.docker.com/search?q=&type=extension){:target="_blank" rel="noopener" class="_"} or in the Extensions Marketplace within Docker Desktop. To find out more about Docker Extensions, we recommend the video walkthrough from DockerCon 2022: diff --git a/desktop/extensions/non-marketplace.md b/desktop/extensions/non-marketplace.md index 2c3027a04f..bfd0833689 100644 --- a/desktop/extensions/non-marketplace.md +++ b/desktop/extensions/non-marketplace.md @@ -20,7 +20,7 @@ You can install an extension that has been developed by the community or interna > **Note** > > Ensure the option **Allow only extensions distributed through the Docker Marketplace** is disabled. Otherwise, this prevents any extension not listed in the Marketplace, via the Extension SDK tools from, being installed. -> You can change this option in **Settings**, or **Preferences** if you use macOS. +> You can change this option in **Settings**. To install an extension which is not present in the Marketplace, you can use the Extensions CLI that is bundled with Docker Desktop. diff --git a/desktop/extensions/settings-feedback.md b/desktop/extensions/settings-feedback.md index 80a5f0ecc5..7fe1e336d2 100644 --- a/desktop/extensions/settings-feedback.md +++ b/desktop/extensions/settings-feedback.md @@ -10,7 +10,7 @@ title: Settings and feedback Docker Extensions is switched on by default. To change your settings: -1. Navigate to **Settings**, or **Preferences** if you're a Mac user. +1. Navigate to **Settings**. 2. Select the **Extensions** tab. 3. Next to **Enable Docker Extensions**, select or clear the checkbox to set your desired state. 4. In the bottom-right corner, select **Apply & Restart**. @@ -19,7 +19,7 @@ Docker Extensions is switched on by default. To change your settings: You can install extensions through the Marketplace or through the Extensions SDK tools. You can choose to only allow published extensions. These are extensions that have been reviewed and published in the Extensions Marketplace. -1. Navigate to **Settings**, or **Preferences** if you're a Mac user. +1. Navigate to **Settings**. 2. Select the **Extensions** tab. 3. Next to **Allow only extensions distributed through the Docker Marketplace**, select or clear the checkbox to set your desired state. 4. In the bottom-right corner, select **Apply & Restart**. @@ -29,7 +29,7 @@ You can install extensions through the Marketplace or through the Extensions SDK By default, containers created by extensions are hidden from the list of containers in Docker Dashboard and the Docker CLI. To make them visible update your settings: -1. Navigate to **Settings**, or **Preferences** if you're a Mac user. +1. Navigate to **Settings**. 2. Select the **Extensions** tab. 3. Next to **Show Docker Extensions system containers**, select or clear the checkbox to set your desired state. 4. In the bottom-right corner, select **Apply & Restart**. diff --git a/desktop/faqs/linuxfaqs.md b/desktop/faqs/linuxfaqs.md index 2d3abddfd1..0497043cd7 100644 --- a/desktop/faqs/linuxfaqs.md +++ b/desktop/faqs/linuxfaqs.md @@ -168,7 +168,7 @@ Docker Desktop stores Linux containers and images in a single, large "disk image ### Where is the disk image file? -To locate the disk image file, select **Preferences** from the Docker Dashboard then **Advanced** from the **Resources** tab. +To locate the disk image file, select **Settings** from the Docker Dashboard then **Advanced** from the **Resources** tab. The **Advanced** tab displays the location of the disk image. It also displays the maximum size of the disk image and the actual space the disk image is consuming. Note that other tools might display space usage of the file in terms of the maximum file size, and not the actual file size. @@ -184,7 +184,7 @@ If the disk image file is too large, you can: To move the disk image file to a different location: -1. Select **Preferences** then **Advanced** from the **Resources** tab. +1. Select **Settings** then **Advanced** from the **Resources** tab. 2. In the **Disk image location** section, click **Browse** and choose a new location for the disk image. @@ -246,7 +246,7 @@ In this example, the actual size of the disk is `2333548` KB, whereas the maximu To reduce the maximum size of the disk image file: -1. From Docker Dashboard select **Preferences** then **Advanced** from the **Resources** tab. +1. From Docker Dashboard select **Settings** then **Advanced** from the **Resources** tab. 2. The **Disk image size** section contains a slider that allows you to change the maximum size of the disk image. Adjust the slider to set a lower limit. diff --git a/desktop/faqs/macfaqs.md b/desktop/faqs/macfaqs.md index e094283265..f2e6d0f0bd 100644 --- a/desktop/faqs/macfaqs.md +++ b/desktop/faqs/macfaqs.md @@ -33,7 +33,7 @@ Docker Desktop stores Linux containers and images in a single, large "disk image #### Where is the disk image file? -To locate the disk image file, select **Preferences** from the Docker Dashboard then **Advanced** from the **Resources** tab. +To locate the disk image file, select **Settings** from the Docker Dashboard then **Advanced** from the **Resources** tab. The **Advanced** tab displays the location of the disk image. It also displays the maximum size of the disk image and the actual space the disk image is consuming. Note that other tools might display space usage of the file in terms of the maximum file size, and not the actual file size. @@ -49,7 +49,7 @@ If the disk image file is too big, you can: To move the disk image file to a different location: -1. Select **Preferences** then **Advanced** from the **Resources** tab. +1. Select **Settings** then **Advanced** from the **Resources** tab. 2. In the **Disk image location** section, click **Browse** and choose a new location for the disk image. @@ -111,7 +111,7 @@ In this example, the actual size of the disk is `2333548` KB, whereas the maximu To reduce the maximum size of the disk image file: -1. Select **Preferences** then **Advanced** from the **Resources** tab. +1. Select **Settings** then **Advanced** from the **Resources** tab. 2. The **Disk image size** section contains a slider that allows you to change the maximum size of the disk image. Adjust the slider to set a lower limit. diff --git a/desktop/get-started.md b/desktop/get-started.md index b6bf4bcf7c..298727ce79 100644 --- a/desktop/get-started.md +++ b/desktop/get-started.md @@ -31,9 +31,9 @@ redirect_from: Once Docker Desktop is installed, the Quick Start Guide launches. It includes a simple exercise to build an example Docker image, run it as a container, push and save the image to Docker Hub. - ![Docker Quick Start tutorial](images/docker-tutorial-linux.png) + ![Docker Quick Start tutorial](images/docker-tutorial.png) -To run the Quick Start Guide on demand, select ![whale menu](images/whale-x.svg){: .inline} and then choose **Quick Start Guide**. +To run the Quick Start Guide on demand, select the Docker menu ![whale menu](images/whale-x.svg){: .inline} and then choose **Quick Start Guide**. For a more detailed guide, see [Get started](../get-started/index.md). @@ -49,17 +49,17 @@ In large enterprises where admin access is restricted, administrators can create ### Two-factor authentication -Docker Desktop enables you to sign in to Docker Hub using two-factor authentication. Two-factor authentication provides an extra layer of security when accessing your Docker Hub account. +Docker Desktop lets you to sign in to Docker Hub using two-factor authentication. Two-factor authentication provides an extra layer of security when accessing your Docker Hub account. -You must enable two-factor authentication in Docker Hub before signing into your Docker Hub account through Docker Desktop. For instructions, see [Enable two-factor authentication for Docker Hub](/docker-hub/2fa/). +You must turn on two-factor authentication in Docker Hub before signing into your Docker Hub account through Docker Desktop. For instructions, see [Enable two-factor authentication for Docker Hub](/docker-hub/2fa/). -After two-factor authentication is enabled: +After two-factor authentication is turned on: 1. Go to the Docker Desktop menu and then select **Sign in / Create Docker ID**. -2. Enter your Docker ID and password and click **Sign in**. +2. Enter your Docker ID and password and select **Sign in**. -3. After you have successfully signed in, Docker Desktop prompts you to enter the authentication code. Enter the six-digit code from your phone and then click **Verify**. +3. After you have successfully signed in, Docker Desktop prompts you to enter the authentication code. Enter the six-digit code from your phone and then select **Verify**. ### Credentials management for Linux users @@ -67,10 +67,15 @@ Docker Desktop relies on [`pass`](https://www.passwordstore.org/){: target="_bla Before signing in to Docker Hub from the Docker Dashboard or the Docker menu, you must initialize `pass`. Docker Desktop displays a warning if you've not initialized `pass`. -You can intialize pass by using a gpg key. To generate a gpg key, run: +You can initialize pass by using a gpg key. To generate a gpg key, run: ``` console $ gpg --generate-key +``` + +Below is an example similar to what you see once you run the above command: + +```console ... GnuPG needs to construct a user ID to identify your key. @@ -87,10 +92,14 @@ uid Molly sub rsa3072 2022-03-31 [E] [expires: 2024-03-30] ``` -To initialize `pass`, run the following command using the public key generated from the previous command +To initialize `pass`, run the following command using the public key generated from the previous command: + +```console +$ pass init +``` +Below is an example similar to what you see once you run the above command: ```console -molly@ubuntu:~$ pass init mkdir: created directory '/home/molly/.password-store/' Password store initialized for ``` @@ -107,7 +116,7 @@ Digest: sha256:3c6b73ce467f04d4897d7a7439782721fd28ec9bf62ea2ad9e81a5fb7fb3ff96 Status: Downloaded newer image for molly/privateimage:latest docker.io/molly/privateimage:latest ``` -## Where to go next +## What's next? - [Explore Docker Desktop](use-desktop/index.md) and its features. - Change your Docker Desktop settings diff --git a/desktop/hardened-desktop/registry-access-management.md b/desktop/hardened-desktop/registry-access-management.md index d5b43f4d03..0588b38e4c 100644 --- a/desktop/hardened-desktop/registry-access-management.md +++ b/desktop/hardened-desktop/registry-access-management.md @@ -52,6 +52,7 @@ The new Registry Access Management policy takes effect after the developer succe There are certain limitations when using Registry Access Management: - Windows image pulls, and image builds are not restricted +- When RAM is enabled, the registry restrictions are currently applied to the [ADD](/engine/reference/builder/#add) instruction of the Dockerfile when the parameter of the ADD instruction is a URL. A workaround for this is to add the domains of URL parameters to the list of allowed registry addresses under the Registry Access Management settings of your organization. - Builds such as `docker buildx` using a Kubernetes driver are not restricted - Builds such as `docker buildx` using a custom docker-container driver are not restricted - Blocking is DNS-based; you must use a registry's access control mechanisms to distinguish between “push” and “pull” diff --git a/desktop/hardened-desktop/settings-management/configure.md b/desktop/hardened-desktop/settings-management/configure.md index f2c2e8ee34..55365408ed 100644 --- a/desktop/hardened-desktop/settings-management/configure.md +++ b/desktop/hardened-desktop/settings-management/configure.md @@ -141,4 +141,4 @@ Docker doesn't automatically mandate that developers re-launch and sign in once In Docker Desktop, developers see the relevant settings grayed out and the message **Locked by your administrator**. -![Proxy settings grayed out](/assets/images/grayed-setting.png){:width="350px"} +![Proxy settings grayed out with Settings Management](/assets/images/grayed-setting.png){:width="350px"} diff --git a/desktop/images/dashboard.PNG b/desktop/images/dashboard.PNG index 43bb97b9ef..a72a50a708 100644 Binary files a/desktop/images/dashboard.PNG and b/desktop/images/dashboard.PNG differ diff --git a/desktop/images/docker-tutorial.png b/desktop/images/docker-tutorial.png new file mode 100644 index 0000000000..269293201f Binary files /dev/null and b/desktop/images/docker-tutorial.png differ diff --git a/desktop/images/extensions-marketplace.PNG b/desktop/images/extensions-marketplace.PNG index ccaad69572..7428ba111e 100644 Binary files a/desktop/images/extensions-marketplace.PNG and b/desktop/images/extensions-marketplace.PNG differ diff --git a/desktop/images/marketplace.png b/desktop/images/marketplace.png new file mode 100644 index 0000000000..ea1349e9bb Binary files /dev/null and b/desktop/images/marketplace.png differ diff --git a/desktop/index.md b/desktop/index.md index b2b3ad37ce..879b4ec489 100644 --- a/desktop/index.md +++ b/desktop/index.md @@ -16,10 +16,12 @@ redirect_from: > employees OR more than $10 million USD in annual revenue) requires a paid > subscription. -Docker Desktop is an easy-to-install application for your Mac, Linux, or Windows environment +Docker Desktop is a one-click-install application for your Mac, Linux, or Windows environment that enables you to build and share containerized applications and microservices. -It provides a simple interface that enables you to manage your containers, applications, and images directly from your machine without having to use the CLI to perform core actions. +It provides a straightforward GUI (Graphical User Interface) that lets you manage your containers, applications, and images directly from your machine. Docker Desktop can be used either on it's own or as a complementary tool to the CLI. + +Docker Desktop reduces the time spent on complex setups so you can focus on writing code. It takes care of port mappings, file system concerns, and other default settings, and is regularly updated with bug fixes and security updates.