diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 38106195861..06b820aa845 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -15,12 +15,16 @@ /content/manuals/extensions-sdk/ @aevesdocker -/content/manuals/scout/ @dvdksn +/content/manuals/scout/ @craig-osterhout /content/manuals/docker-hub/ @craig-osterhout /content/manuals/engine/ @dvdksn +/content/reference/api/engine/ @dvdksn + +/content/reference/cli/ @dvdksn + /content/manuals/subscription/ @sarahsanders-docker /content/manuals/security/ @aevesdocker @@ -29,7 +33,7 @@ /content/manuals/docker-hub/official_images/ @craig-osterhout -/content/manuals/registry/ @dvdksn +/content/manuals/registry/ @craig-osterhout /content/manuals/admin/ @sarahsanders-docker @@ -37,3 +41,6 @@ /content/manuals/accounts/ @sarahsanders-docker +/hack @dvdksn + +/_vendor @dvdksn diff --git a/.github/ISSUE_TEMPLATE/new_guide.yml b/.github/ISSUE_TEMPLATE/new_guide.yml new file mode 100644 index 00000000000..4d9c4bbc9f1 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/new_guide.yml @@ -0,0 +1,25 @@ +# https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-githubs-form-schema +name: New guide +description: Propose a new guide for Docker docs +labels: + - area/guides + - kind/proposal + +body: + - type: textarea + attributes: + label: Description + description: | + Briefly describe the topic that you would like us to cover. + validations: + required: true + - type: checkboxes + attributes: + label: Would you like to contribute this guide? + description: | + If you select this checkbox, you indicate that you're willing to + contribute this guide. If not, we will treat this issue as a request, + and someone (a Docker employee, Docker captain, or community member) + may pick it up and start working on it. + options: + - label: "Yes" diff --git a/.github/labeler.yml b/.github/labeler.yml index bd7e0104000..11cef0e77f6 100644 --- a/.github/labeler.yml +++ b/.github/labeler.yml @@ -2,7 +2,7 @@ area/release: - changed-files: - any-glob-to-any-file: - .github/** - - _releaser/** + - hack/releaser/** - netlify.toml area/config: @@ -14,6 +14,7 @@ area/config: - docker-bake.hcl - hugo.yaml - pagefind.yml + - hack/vendor area/contrib: - changed-files: @@ -28,7 +29,7 @@ area/tests: - .markdownlint.json - .vale.ini - _vale/** - - scripts/test_* + - hack/test/* area/build: - changed-files: @@ -159,6 +160,11 @@ area/accounts: - any-glob-to-any-file: - content/manuals/accounts/** +area/copilot: + - changed-files: + - any-glob-to-any-file: + - content/manuals/copilot/** + hugo: - changed-files: - any-glob-to-any-file: @@ -178,3 +184,4 @@ dependencies: - go.sum - package*.json - _vendor/** + - hack/vendor diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 67e06543eac..cc169ecacbb 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -11,12 +11,42 @@ on: - main pull_request: +env: + # Use edge release of buildx (latest RC, fallback to latest stable) + SETUP_BUILDX_VERSION: edge + SETUP_BUILDKIT_IMAGE: "moby/buildkit:latest" + permissions: contents: read # to fetch code (actions/checkout) jobs: + releaser: + runs-on: ubuntu-24.04 + steps: + - + name: Checkout + uses: actions/checkout@v4 + - + name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + with: + version: ${{ env.SETUP_BUILDX_VERSION }} + driver-opts: image=${{ env.SETUP_BUILDKIT_IMAGE }} + - + name: Build + uses: docker/bake-action@v5 + with: + files: | + docker-bake.hcl + targets: releaser-build + set: | + *.cache-from=type=gha,scope=releaser + *.cache-to=type=gha,scope=releaser,mode=max + build: runs-on: ubuntu-24.04 + needs: + - releaser steps: - name: Checkout @@ -34,6 +64,16 @@ jobs: set: | *.cache-from=type=gha,scope=build *.cache-to=type=gha,scope=build,mode=max + - + name: Check Cloudfront config + uses: docker/bake-action@v5 + with: + targets: aws-cloudfront-update + env: + DRY_RUN: true + AWS_REGION: us-east-1 + AWS_CLOUDFRONT_ID: 0123456789ABCD + AWS_LAMBDA_FUNCTION: DockerDocsRedirectFunction-dummy vale: if: ${{ github.event_name == 'pull_request' }} @@ -76,25 +116,3 @@ jobs: *.cache-to=type=gha,scope=validate-${{ matrix.target }},mode=max *.cache-from=type=gha,scope=validate-${{ matrix.target }} *.cache-from=type=gha,scope=build - - # build-releaser builds the _releaser used for AWS deployment in publish workflow. - # It's just to be sure it builds correctly. - build-releaser: - runs-on: ubuntu-24.04 - steps: - - - name: Checkout - uses: actions/checkout@v4 - - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@v3 - - - name: Build - uses: docker/bake-action@v5 - with: - files: | - docker-bake.hcl - targets: releaser-build - set: | - *.cache-from=type=gha,scope=releaser - *.cache-to=type=gha,scope=releaser,mode=max diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index 8be67f66a23..a4e6d9b9047 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -12,6 +12,11 @@ on: - main - published +env: + # Use edge release of buildx (latest RC, fallback to latest stable) + SETUP_BUILDX_VERSION: edge + SETUP_BUILDKIT_IMAGE: "moby/buildkit:latest" + # these permissions are needed to interact with GitHub's OIDC Token endpoint. permissions: id-token: write @@ -80,6 +85,9 @@ jobs: - name: Set up Docker Buildx uses: docker/setup-buildx-action@v3 + with: + version: ${{ env.SETUP_BUILDX_VERSION }} + driver-opts: image=${{ env.SETUP_BUILDKIT_IMAGE }} - name: Build website uses: docker/bake-action@v5 diff --git a/.github/workflows/validate-upstream.yml b/.github/workflows/validate-upstream.yml index 408cea0c817..79c048f6284 100644 --- a/.github/workflows/validate-upstream.yml +++ b/.github/workflows/validate-upstream.yml @@ -23,6 +23,11 @@ on: type: boolean required: false +env: + # Use edge release of buildx (latest RC, fallback to latest stable) + SETUP_BUILDX_VERSION: edge + SETUP_BUILDKIT_IMAGE: "moby/buildkit:latest" + jobs: run: runs-on: ubuntu-24.04 @@ -80,6 +85,9 @@ jobs: - name: Set up Docker Buildx uses: docker/setup-buildx-action@v3 + with: + version: ${{ env.SETUP_BUILDX_VERSION }} + driver-opts: image=${{ env.SETUP_BUILDKIT_IMAGE }} - name: Validate uses: docker/bake-action@v5 diff --git a/Dockerfile b/Dockerfile index 0489b3ef649..6604b4b1134 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,22 +1,43 @@ # syntax=docker/dockerfile:1 # check=skip=InvalidBaseImagePlatform -# ALPINE_VERSION sets the Alpine Linux version for all Alpine stages -ARG ALPINE_VERSION=3.20 -# GO_VERSION sets the Go version for the base stage +ARG ALPINE_VERSION=3.21 ARG GO_VERSION=1.23 -# HTMLTEST_VERSION sets the wjdp/htmltest version for HTML testing ARG HTMLTEST_VERSION=0.17.0 -# HUGO_VERSION sets the version of Hugo to build the site with -ARG HUGO_VERSION=0.136.3 +ARG HUGO_VERSION=0.139.0 +ARG NODE_VERSION=22 +ARG PAGEFIND_VERSION=1.1.1 -# build-base is the base stage used for building the site -FROM ghcr.io/gohugoio/hugo:v${HUGO_VERSION} AS build-base +# base defines the generic base stage +FROM golang:${GO_VERSION}-alpine${ALPINE_VERSION} AS base +RUN apk add --no-cache \ + git \ + nodejs \ + npm \ + gcompat + +# npm downloads Node.js dependencies +FROM base AS npm ENV NODE_ENV="production" +WORKDIR /out RUN --mount=source=package.json,target=package.json \ --mount=source=package-lock.json,target=package-lock.json \ --mount=type=cache,target=/root/.npm \ npm ci + +# hugo downloads the Hugo binary +FROM base AS hugo +ARG TARGETARCH +ARG HUGO_VERSION +WORKDIR /out +ADD https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-${TARGETARCH}.tar.gz . +RUN tar xvf hugo_extended_${HUGO_VERSION}_linux-${TARGETARCH}.tar.gz + +# build-base is the base stage used for building the site +FROM base AS build-base +WORKDIR /project +COPY --from=hugo /out/hugo /bin/hugo +COPY --from=npm /out/node_modules node_modules COPY . . # build creates production builds with Hugo @@ -25,7 +46,9 @@ FROM build-base AS build ARG HUGO_ENV="development" # DOCS_URL sets the base URL for the site ARG DOCS_URL="https://docs.docker.com" -RUN hugo --gc --minify -e $HUGO_ENV -b $DOCS_URL +ENV HUGO_CACHEDIR="/tmp/hugo_cache" +RUN --mount=type=cache,target=/tmp/hugo_cache \ + hugo --gc --minify -e $HUGO_ENV -b $DOCS_URL # lint lints markdown files FROM davidanson/markdownlint-cli2:v0.14.0 AS lint @@ -61,8 +84,8 @@ RUN hugo mod vendor # vendor is an empty stage with only vendored Hugo modules FROM scratch AS vendor -COPY --from=update-modules /src/_vendor /_vendor -COPY --from=update-modules /src/go.* / +COPY --from=update-modules /project/_vendor /_vendor +COPY --from=update-modules /project/go.* / # build-upstream builds an upstream project with a replacement module FROM build-base AS build-upstream @@ -87,10 +110,7 @@ RUN htmltest FROM alpine:${ALPINE_VERSION} AS unused-media RUN apk add --no-cache fd ripgrep WORKDIR /test -RUN --mount=type=bind,target=. <<"EOT" -set -ex -./scripts/test_unused_media.sh -EOT +RUN --mount=type=bind,target=. ./hack/test/unused_media # path-warnings checks for duplicate target paths FROM build-base AS path-warnings @@ -105,8 +125,8 @@ fi EOT # pagefind installs the Pagefind runtime -FROM node:alpine${ALPINE_VERSION} AS pagefind -ARG PAGEFIND_VERSION=1.1.1 +FROM base AS pagefind +ARG PAGEFIND_VERSION COPY --from=build /project/public ./public RUN --mount=type=bind,src=pagefind.yml,target=pagefind.yml \ npx pagefind@v${PAGEFIND_VERSION} --output-path "/pagefind" @@ -122,7 +142,7 @@ RUN apk add yq COPY --from=build /project/public ./public RUN --mount=type=bind,target=. <<"EOT" set -ex -./scripts/test_go_redirects.sh +./hack/test/go_redirects EOT # release is an empty scratch image with only compiled assets diff --git a/Makefile b/Makefile index 6acc1776313..8a5b14de683 100644 --- a/Makefile +++ b/Makefile @@ -1,3 +1,3 @@ .PHONY: vendor vendor: ## vendor hugo modules - ./scripts/vendor.sh + ./hack/vendor diff --git a/_releaser/go.sum b/_releaser/go.sum deleted file mode 100644 index 6a266d61164..00000000000 --- a/_releaser/go.sum +++ /dev/null @@ -1,52 +0,0 @@ -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/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/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= -github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c= -github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= -github.com/hexops/gotextdiff v1.0.3 h1:gitA9+qJrrTCsiCl7+kh75nPqQt1cx4ZkudSTLoUqJM= -github.com/jmespath/go-jmespath v0.4.0 h1:BEgLn5cpjn8UN1mAw4NjwDrS35OdebyEtFe+9YPoQUg= -github.com/jmespath/go-jmespath v0.4.0/go.mod h1:T8mJZnbsbmF+m6zOOFylbeCJqk5+pHWvzYPziyZiYoo= -github.com/jmespath/go-jmespath/internal/testify v1.5.1 h1:shLQSRRSCCPj3f2gpwzGwWFoC7ycTf1rcQZHOlsJ6N8= -github.com/jmespath/go-jmespath/internal/testify v1.5.1/go.mod h1:L3OGu8Wl2/fWfCI6z80xFu9LTZmf1ZRjMHUOPmWr69U= -github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0= -github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM= -github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4= -github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME= -github.com/yuin/goldmark v1.4.13/go.mod h1:6yULJ656Px+3vBD8DxQVa3kxgyrAnzto9xy5taEt/CY= -golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w= -golang.org/x/crypto v0.0.0-20210921155107-089bfa567519/go.mod h1:GvvjBRRGRdwPK5ydBHafDWAxML/pGHZbMvKqRZ5+Abc= -golang.org/x/mod v0.6.0-dev.0.20220419223038-86c51ed26bb4/go.mod h1:jJ57K6gSWd91VN4djpZkiMVwK6gcyfeH4XE8wZrZaV4= -golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s= -golang.org/x/net v0.0.0-20210226172049-e18ecbb05110/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg= -golang.org/x/net v0.0.0-20220722155237-a158d28d115b/go.mod h1:XRhObCWvk6IyKnWLug+ECip1KBveYUHfp+8e9klMJ9c= -golang.org/x/net v0.1.0/go.mod h1:Cx3nUiGt4eDBEyega/BKRp+/AlGL8hYe7U9odMt2Cco= -golang.org/x/net v0.17.0 h1:pVaXccu2ozPjCXewfr1S7xza/zcXTity9cCdXQYSjIM= -golang.org/x/net v0.17.0/go.mod h1:NxSsAGuq816PNPmqtQdLE42eU2Fs7NoRIZrHJAlaCOE= -golang.org/x/sync v0.0.0-20190423024810-112230192c58/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-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY= -golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/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-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/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= -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.3/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/go.mod h1:mrYo+phRRbMaCq/xk9113O4dZlRixOauAjOtrjsXDZ8= -golang.org/x/text v0.13.0 h1:ablQoSUd0tRdKxZewP80B+BaqeKJuVhuRxj/dkrun3k= -golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ= -golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo= -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= -gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= -gopkg.in/yaml.v2 v2.2.8/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI= -gopkg.in/yaml.v2 v2.4.0 h1:D8xgwECY7CYvx+Y2n4sBz93Jn9JRvxdiyyo8CTfuKaY= -gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ= diff --git a/_vale/Docker/Acronyms.yml b/_vale/Docker/Acronyms.yml index c1fa32d4483..ae5de53732f 100644 --- a/_vale/Docker/Acronyms.yml +++ b/_vale/Docker/Acronyms.yml @@ -4,83 +4,135 @@ link: https://docs.docker.com/contribute/style/grammar/#acronyms-and-initialisms level: warning ignorecase: false # Ensures that the existence of 'first' implies the existence of 'second'. -first: '\b([A-Z]{3,5})\b' -second: '(?:\b[A-Z][a-z]+ )+\(([A-Z]{3,5})\)' +first: '\b([A-Z]{2,5})\b' +second: '(?:\b[A-Z][a-z]+ )+\(([A-Z]{2,5})s?\)' # ... with the exception of these: exceptions: + - AGPL + - AI - API - ARM - ASP - AUFS - AWS - BIOS + - BPF + - BSD + - CI + - CISA - CLI + - CNCF + - CORS - CPU - CSS - CSV - CVE - DCT - DEBUG + - DHCP + - DNS - DOM - DPI - DSOS - DVP + - ECI - ELK - FAQ - FUSE + - GB - GCC - GDB - GET - GHSA + - GNU + - GPG + - GPL - GPU + - GRUB - GTK - GUI - HEAD - HTML - HTTP - HTTPS + - IAM + - IBM + - ID - IDE + - IP - JAR - JSON - JSX - LESS - LLDB + - LTS + - MAC + - MDM + - MDN + - NAT - NET - NFS - NOTE + - NTFS + - NTLM + - NUMA - NVDA + - OCI + - OS - OSS - PATH - PDF + - PEM + - PID - PHP - POSIX - POST + - QEMU - RAM - REPL - REST + - RHEL + - RPM - RSA + - SAML + - SARIF - SBOM + - SCIM - SCM - SCSS - SDK + - SLES + - SLSA + - SOCKS + - SPDX - SQL - SSD - SSH - SSL + - SSO - SVG - TBD - TCP + - TCP - TIP + - TLS - TODO - TTY + - TXT + - UDP - URI - URL - USB - USD - UTF + - UUID - VAT + - VLAN + - VM + - VPN - WSL - XML - XSS - YAML + - ZFS - ZIP diff --git a/_vale/Docker/RecommendedWords.yml b/_vale/Docker/RecommendedWords.yml index c4bd532dfbf..2721e0881fb 100644 --- a/_vale/Docker/RecommendedWords.yml +++ b/_vale/Docker/RecommendedWords.yml @@ -14,7 +14,7 @@ swap: (?:sign on|log on|log in|logon|login): sign in above: previous adaptor: adapter - admin: administrator + admin(?! console): administrator administrate: administer afterwards: afterward allow: let @@ -31,12 +31,12 @@ swap: check box: checkbox check boxes: checkboxes click: select + distro: distribution ergo: therefore file name: filename keypress: keystroke mutices: mutexes repo: repository - scan: analyze scroll: navigate url: URL vs: versus diff --git a/_vale/config/vocabularies/Docker/accept.txt b/_vale/config/vocabularies/Docker/accept.txt index 036c9e83347..1036af5ee67 100644 --- a/_vale/config/vocabularies/Docker/accept.txt +++ b/_vale/config/vocabularies/Docker/accept.txt @@ -1,23 +1,13 @@ -A?GPL(v3)? -APIs? -ARM -AWS -Admin Console +(?-i)[A-Z]{2,}'?s Amazon -Ambassador Anchore Apple Artifactory -Autobuild Autotest Azure Btrfs BuildKit BusyBox -CISA -CNCF -CORS -CVEs? CentOS Ceph Chrome @@ -27,13 +17,10 @@ Codefresh Codespaces CouchDB Couchbase -DHCP -DNS -DSOS -DVP Datadog Ddosify Debootstrap +Dev Dev Environments? Django Docker Build Cloud @@ -55,114 +42,106 @@ Ethernet Fargate Fedora Flink -GPG -GPUs? -GRUB GeoNetwork Git GitHub( Actions)? Google Grafana Gravatar -HTTP HyperKit -IAM -IPs? IPv[46] IPvlan Intel Intune -Jamf JFrog +Jamf JetBrains Kerberos Kitematic Kubernetes -LTS Linux LinuxKit Logstash -MAC Mac Mail(chimp|gun) -MDM Microsoft MySQL -NAT +NFSv\d Netplan Nginx -NTLM Nuxeo -OAT OAuth -OCI OTel Okta -PAT +PKG +Paketo Postgres PowerShell Python -QEMU -RHEL -RPM S3 -SAML -SARIF -SBOMs? -SCIM -SDKs? -SLES -SLSA -SPDX SQLite -SSH -SSO Slack Snyk Solr SonarQube Syft +Sysbox Sysdig -TCP -TLS -TXT Testcontainers Traefik -UDP -URLs? -UUID Ubuntu Unix -VLAN -VM VMware -WSL Wasm Windows WireMock +Zscaler Zsh +[Aa]nonymized? +[Aa]utobuild +[Aa]llowlist +[Bb]uildpack(s)? [Bb]uildx [Cc]odenames? [Cc]ompose -[Dd]istros +[Dd]istroless [Ff]ilepaths? [Ff]iletypes? [GgCc]oroutine [Hh]ostname [Ii]nfosec +[Kk]eyrings? [Ll]oopback +[Mm]emcached [Mm]oby +[Nn]amespace [Oo]nboarding [Pp]aravirtualization +[Pp]repend +[Pp]rocfs +[Pp]roxied [Pp]roxying [Rr]eal-time [Rr]untimes? [Ss]andbox(ed)? +[Ss]eccomp +[Ss]ubmounts? +[Ss]ubpaths? +[Ss]ubtrees? +[Ss]wappable [Ss]wappable [Ss]warm +[Ss]warm +[Ss]yscalls? +[Ss]ysfs [Tt]oolchains? -[Vv]irtualize +[Uu]narchived? +[Uu]ngated +[Uu]ntrusted +[Uu]serland +[Uu]serspace [Vv]irtiofs +[Vv]irtualize [Ww]alkthrough cgroup config @@ -181,17 +160,21 @@ kubectl kubefwd kubelet lookup +label_file macOS macvlan mfsymlinks minikube +monorepos? musl nameserver namespace +namespacing npm osquery osxfs pgAdmin +rootful runc snapshotters? stdin @@ -201,6 +184,6 @@ systemd tmpfs ufw umask -ungated vSphere vpnkit +windowsfilter diff --git a/_vendor/github.com/docker/buildx/docs/bake-reference.md b/_vendor/github.com/docker/buildx/docs/bake-reference.md index b60d391c895..19483210a5b 100644 --- a/_vendor/github.com/docker/buildx/docs/bake-reference.md +++ b/_vendor/github.com/docker/buildx/docs/bake-reference.md @@ -359,6 +359,21 @@ target "app" { } ``` +### `target.call` + +Specifies the frontend method to use. Frontend methods let you, for example, +execute build checks only, instead of running a build. This is the same as the +`--call` flag. + +```hcl +target "app" { + call = "check" +} +``` + +For more information about frontend methods, refer to the CLI reference for +[`docker buildx build --call`](https://docs.docker.com/reference/cli/docker/buildx/build/#call). + ### `target.context` Specifies the location of the build context to use for this target. @@ -844,7 +859,7 @@ The following example forces the builder to always pull all images referenced in ```hcl target "default" { - pull = "always" + pull = true } ``` diff --git a/_vendor/github.com/docker/cli/docs/reference/dockerd.md b/_vendor/github.com/docker/cli/docs/reference/dockerd.md index bb603c9b386..ae6eb2fee3e 100644 --- a/_vendor/github.com/docker/cli/docs/reference/dockerd.md +++ b/_vendor/github.com/docker/cli/docs/reference/dockerd.md @@ -892,7 +892,7 @@ Alternatively, you can set custom locations for CDI specifications using the When CDI is enabled for a daemon, you can view the configured CDI specification directories using the `docker info` command. -#### Daemon logging format +#### Daemon logging format {#log-format} The `--log-format` option or "log-format" option in the [daemon configuration file](#daemon-configuration-file) lets you set the format for logs produced by the daemon. The logging format should @@ -1000,7 +1000,7 @@ Example of usage: } ``` -### Enable feature in the daemon (--feature) +### Enable feature in the daemon (--feature) {#feature} The `--feature` option lets you enable or disable a feature in the daemon. This option corresponds with the "features" field in the [daemon.json configuration file](#daemon-configuration-file). diff --git a/_vendor/github.com/docker/cli/docs/reference/run.md b/_vendor/github.com/docker/cli/docs/reference/run.md index 186f1f8b5e5..db06ad71f66 100644 --- a/_vendor/github.com/docker/cli/docs/reference/run.md +++ b/_vendor/github.com/docker/cli/docs/reference/run.md @@ -134,7 +134,7 @@ You can identify a container in three ways: The UUID identifier is a random ID assigned to the container by the daemon. The daemon generates a random string name for containers automatically. You can -also defined a custom name using [the `--name` flag](https://docs.docker.com/reference/cli/docker/container/run/#name). +also define a custom name using [the `--name` flag](https://docs.docker.com/reference/cli/docker/container/run/#name). Defining a `name` can be a handy way to add meaning to a container. If you specify a `name`, you can use it when referring to the container in a user-defined network. This works for both background and foreground Docker @@ -285,7 +285,7 @@ See 'docker run --help'. ### 126 Exit code `126` indicates that the specified contained command can't be invoked. -The container command in the following example is: `/etc; echo $?`. +The container command in the following example is: `/etc`. ```console $ docker run busybox /etc; echo $? diff --git a/_vendor/github.com/docker/compose/v2/docs/reference/compose.md b/_vendor/github.com/docker/compose/v2/docs/reference/compose.md index 5a69a01b508..d625c253e67 100644 --- a/_vendor/github.com/docker/compose/v2/docs/reference/compose.md +++ b/_vendor/github.com/docker/compose/v2/docs/reference/compose.md @@ -13,6 +13,7 @@ Define and run multi-container applications with Docker |:--------------------------------|:----------------------------------------------------------------------------------------| | [`attach`](compose_attach.md) | Attach local standard input, output, and error streams to a service's running container | | [`build`](compose_build.md) | Build or rebuild services | +| [`commit`](compose_commit.md) | Create a new image from a service container's changes | | [`config`](compose_config.md) | Parse, resolve and render compose file in canonical format | | [`cp`](compose_cp.md) | Copy files/folders between a service container and the local filesystem | | [`create`](compose_create.md) | Creates containers for a service | diff --git a/_vendor/github.com/docker/compose/v2/docs/reference/compose_commit.md b/_vendor/github.com/docker/compose/v2/docs/reference/compose_commit.md new file mode 100644 index 00000000000..1aad40931f9 --- /dev/null +++ b/_vendor/github.com/docker/compose/v2/docs/reference/compose_commit.md @@ -0,0 +1,19 @@ +# docker compose commit + + +Create a new image from a service container's changes + +### Options + +| Name | Type | Default | Description | +|:------------------|:---------|:--------|:-----------------------------------------------------------| +| `-a`, `--author` | `string` | | Author (e.g., "John Hannibal Smith ") | +| `-c`, `--change` | `list` | | Apply Dockerfile instruction to the created image | +| `--dry-run` | `bool` | | Execute command in dry run mode | +| `--index` | `int` | `0` | index of the container if service has multiple replicas. | +| `-m`, `--message` | `string` | | Commit message | +| `-p`, `--pause` | `bool` | `true` | Pause container during commit | + + + + diff --git a/_vendor/github.com/docker/compose/v2/docs/reference/compose_up.md b/_vendor/github.com/docker/compose/v2/docs/reference/compose_up.md index 295000734b1..410ec84b52d 100644 --- a/_vendor/github.com/docker/compose/v2/docs/reference/compose_up.md +++ b/_vendor/github.com/docker/compose/v2/docs/reference/compose_up.md @@ -51,7 +51,7 @@ If the process is interrupted using `SIGINT` (ctrl + C) or `SIGTERM`, the contai | `-t`, `--timeout` | `int` | `0` | Use this timeout in seconds for container shutdown when attached or when containers are already running | | `--timestamps` | `bool` | | Show timestamps | | `--wait` | `bool` | | Wait for services to be running\|healthy. Implies detached mode. | -| `--wait-timeout` | `int` | `0` | Maximum duration to wait for the project to be running\|healthy | +| `--wait-timeout` | `int` | `0` | Maximum duration in seconds to wait for the project to be running\|healthy | | `-w`, `--watch` | `bool` | | Watch source code and rebuild/refresh containers when files are updated. | diff --git a/_vendor/github.com/docker/compose/v2/docs/reference/docker_compose.yaml b/_vendor/github.com/docker/compose/v2/docs/reference/docker_compose.yaml index f59ec4a04b2..1c6fb4970e7 100644 --- a/_vendor/github.com/docker/compose/v2/docs/reference/docker_compose.yaml +++ b/_vendor/github.com/docker/compose/v2/docs/reference/docker_compose.yaml @@ -7,6 +7,7 @@ plink: docker.yaml cname: - docker compose attach - docker compose build + - docker compose commit - docker compose config - docker compose cp - docker compose create @@ -39,6 +40,7 @@ cname: clink: - docker_compose_attach.yaml - docker_compose_build.yaml + - docker_compose_commit.yaml - docker_compose_config.yaml - docker_compose_cp.yaml - docker_compose_create.yaml diff --git a/_vendor/github.com/docker/compose/v2/docs/reference/docker_compose_commit.yaml b/_vendor/github.com/docker/compose/v2/docs/reference/docker_compose_commit.yaml new file mode 100644 index 00000000000..95f4834a97b --- /dev/null +++ b/_vendor/github.com/docker/compose/v2/docs/reference/docker_compose_commit.yaml @@ -0,0 +1,76 @@ +command: docker compose commit +short: Create a new image from a service container's changes +long: Create a new image from a service container's changes +usage: docker compose commit [OPTIONS] SERVICE [REPOSITORY[:TAG]] +pname: docker compose +plink: docker_compose.yaml +options: + - option: author + shorthand: a + value_type: string + description: Author (e.g., "John Hannibal Smith ") + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: change + shorthand: c + value_type: list + description: Apply Dockerfile instruction to the created image + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: index + value_type: int + default_value: "0" + description: index of the container if service has multiple replicas. + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: message + shorthand: m + value_type: string + description: Commit message + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: pause + shorthand: p + value_type: bool + default_value: "true" + description: Pause container during commit + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: dry-run + value_type: bool + default_value: "false" + description: Execute command in dry run mode + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +deprecated: false +hidden: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/_vendor/github.com/docker/compose/v2/docs/reference/docker_compose_up.yaml b/_vendor/github.com/docker/compose/v2/docs/reference/docker_compose_up.yaml index 4c895f6a65b..1474cfe2ee6 100644 --- a/_vendor/github.com/docker/compose/v2/docs/reference/docker_compose_up.yaml +++ b/_vendor/github.com/docker/compose/v2/docs/reference/docker_compose_up.yaml @@ -289,7 +289,8 @@ options: - option: wait-timeout value_type: int default_value: "0" - description: Maximum duration to wait for the project to be running|healthy + description: | + Maximum duration in seconds to wait for the project to be running|healthy deprecated: false hidden: false experimental: false diff --git a/_vendor/github.com/docker/scout-cli/docs/docker_scout_sbom.yaml b/_vendor/github.com/docker/scout-cli/docs/docker_scout_sbom.yaml index dd6b1ea8623..7a804e37e9d 100644 --- a/_vendor/github.com/docker/scout-cli/docs/docker_scout_sbom.yaml +++ b/_vendor/github.com/docker/scout-cli/docs/docker_scout_sbom.yaml @@ -44,6 +44,7 @@ options: - list: list of packages of the image - json: json representation of the SBOM - spdx: spdx representation of the SBOM + - cyclonedx: cyclone dx representation of the SBOM deprecated: false hidden: false experimental: false diff --git a/_vendor/github.com/docker/scout-cli/docs/scout_cves.md b/_vendor/github.com/docker/scout-cli/docs/scout_cves.md index cd95ab4df42..bdb7f82921d 100644 --- a/_vendor/github.com/docker/scout-cli/docs/scout_cves.md +++ b/_vendor/github.com/docker/scout-cli/docs/scout_cves.md @@ -264,8 +264,8 @@ pkg:apk/alpine/zlib@1.2.12-r1?arch=aarch64&distro=alpine-3.16.1 ... 11 vulnerabilities found in 2 packages - LOW 0 - MEDIUM 8 - HIGH 2 CRITICAL 1 + HIGH 2 + MEDIUM 8 + LOW 0 ``` diff --git a/_vendor/github.com/docker/scout-cli/docs/scout_sbom.md b/_vendor/github.com/docker/scout-cli/docs/scout_sbom.md index bda5eb3d5b8..a335d5f83f2 100644 --- a/_vendor/github.com/docker/scout-cli/docs/scout_sbom.md +++ b/_vendor/github.com/docker/scout-cli/docs/scout_sbom.md @@ -5,13 +5,13 @@ Generate or display SBOM of an image ### Options -| Name | Type | Default | Description | -|:----------------------|:--------------|:--------|:----------------------------------------------------------------------------------------------------------------------------------------------| -| `--format` | `string` | `json` | Output format:
- list: list of packages of the image
- json: json representation of the SBOM
- spdx: spdx representation of the SBOM | -| `--only-package-type` | `stringSlice` | | Comma separated list of package types (like apk, deb, rpm, npm, pypi, golang, etc)
Can only be used with --format list | -| `-o`, `--output` | `string` | | Write the report to a file | -| `--platform` | `string` | | Platform of image to analyze | -| `--ref` | `string` | | Reference to use if the provided tarball contains multiple references.
Can only be used with archive | +| Name | Type | Default | Description | +|:----------------------|:--------------|:--------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `--format` | `string` | `json` | Output format:
- list: list of packages of the image
- json: json representation of the SBOM
- spdx: spdx representation of the SBOM
- cyclonedx: cyclone dx representation of the SBOM | +| `--only-package-type` | `stringSlice` | | Comma separated list of package types (like apk, deb, rpm, npm, pypi, golang, etc)
Can only be used with --format list | +| `-o`, `--output` | `string` | | Write the report to a file | +| `--platform` | `string` | | Platform of image to analyze | +| `--ref` | `string` | | Reference to use if the provided tarball contains multiple references.
Can only be used with archive | diff --git a/_vendor/github.com/moby/buildkit/docs/attestations/attestation-storage.md b/_vendor/github.com/moby/buildkit/docs/attestations/attestation-storage.md index 18095d05e13..a42fab303a5 100644 --- a/_vendor/github.com/moby/buildkit/docs/attestations/attestation-storage.md +++ b/_vendor/github.com/moby/buildkit/docs/attestations/attestation-storage.md @@ -1,4 +1,6 @@ -# Image Attestation Storage +--- +title: Image attestation storage +--- Buildkit supports creating and attaching attestations to build artifacts. These attestations can provide valuable information from the build process, diff --git a/_vendor/github.com/moby/buildkit/docs/attestations/slsa-definitions.md b/_vendor/github.com/moby/buildkit/docs/attestations/slsa-definitions.md index 313d8114f44..08b692df3d3 100644 --- a/_vendor/github.com/moby/buildkit/docs/attestations/slsa-definitions.md +++ b/_vendor/github.com/moby/buildkit/docs/attestations/slsa-definitions.md @@ -1,4 +1,6 @@ -# SLSA definitions +--- +title: SLSA definitions +--- BuildKit supports the [creation of SLSA Provenance](./slsa-provenance.md) for builds that it runs. diff --git a/_vendor/github.com/moby/buildkit/docs/buildkitd.toml.md b/_vendor/github.com/moby/buildkit/docs/buildkitd.toml.md index 607c5e34baa..71061c62686 100644 --- a/_vendor/github.com/moby/buildkit/docs/buildkitd.toml.md +++ b/_vendor/github.com/moby/buildkit/docs/buildkitd.toml.md @@ -62,11 +62,25 @@ insecure-entitlements = [ "network.host", "security.insecure" ] # Whether run subprocesses in main pid namespace or not, this is useful for # running rootless buildkit inside a container. noProcessSandbox = false + + # gc enables/disables garbage collection gc = true - # gckeepstorage can be an integer number of bytes (e.g. 512000000), a string - # with a unit (e.g. "512MB"), or a string percentage of the total disk - # space (e.g. "10%") - gckeepstorage = 9000 + # reservedSpace is the minimum amount of disk space guaranteed to be + # retained by this buildkit worker - any usage below this threshold will not + # be reclaimed during garbage collection. + # all disk space parameters can be an integer number of bytes (e.g. + # 512000000), a string with a unit (e.g. "512MB"), or a string percentage + # of the total disk space (e.g. "10%") + reservedSpace = "30%" + # maxUsedSpace is the maximum amount of disk space that may be used by + # this buildkit worker - any usage above this threshold will be reclaimed + # during garbage collection. + maxUsedSpace = "60%" + # minFreeSpace is the target amount of free disk space that the garbage + # collector will attempt to leave - however, it will never be bought below + # reservedSpace. + minFreeSpace = "20GB" + # alternate OCI worker binary name(example 'crun'), by default either # buildkit-runc or runc binary is used binary = "" @@ -83,26 +97,51 @@ insecure-entitlements = [ "network.host", "security.insecure" ] "foo" = "bar" [[worker.oci.gcpolicy]] - # keepBytes can be an integer number of bytes (e.g. 512000000), a string - # with a unit (e.g. "512MB"), or a string percentage of the total disk - # space (e.g. "10%") - keepBytes = "512MB" + # reservedSpace is the minimum amount of disk space guaranteed to be + # retained by this policy - any usage below this threshold will not be + # reclaimed during # garbage collection. + reservedSpace = "512MB" + # maxUsedSpace is the maximum amount of disk space that may be used by this + # policy - any usage above this threshold will be reclaimed during garbage + # collection. + maxUsedSpace = "1GB" + # minFreeSpace is the target amount of free disk space that the garbage + # collector will attempt to leave - however, it will never be bought below + # reservedSpace. + minFreeSpace = "10GB" + # keepDuration can be an integer number of seconds (e.g. 172800), or a # string duration (e.g. "48h") keepDuration = "48h" filters = [ "type==source.local", "type==exec.cachemount", "type==source.git.checkout"] [[worker.oci.gcpolicy]] all = true - keepBytes = 1024000000 + reservedSpace = 1024000000 [worker.containerd] address = "/run/containerd/containerd.sock" enabled = true platforms = [ "linux/amd64", "linux/arm64" ] namespace = "buildkit" + + # gc enables/disables garbage collection gc = true - # gckeepstorage sets storage limit for default gc profile, in bytes. - gckeepstorage = 9000 + # reservedSpace is the minimum amount of disk space guaranteed to be + # retained by this buildkit worker - any usage below this threshold will not + # be reclaimed during garbage collection. + # all disk space parameters can be an integer number of bytes (e.g. + # 512000000), a string with a unit (e.g. "512MB"), or a string percentage + # of the total disk space (e.g. "10%") + reservedSpace = "30%" + # maxUsedSpace is the maximum amount of disk space that may be used by + # this buildkit worker - any usage above this threshold will be reclaimed + # during garbage collection. + maxUsedSpace = "60%" + # minFreeSpace is the target amount of free disk space that the garbage + # collector will attempt to leave - however, it will never be bought below + # reservedSpace. + minFreeSpace = "20GB" + # maintain a pool of reusable CNI network namespaces to amortize the overhead # of allocating and releasing the namespaces cniPoolSize = 16 @@ -119,12 +158,12 @@ insecure-entitlements = [ "network.host", "security.insecure" ] options = { BinaryName = "runc" } [[worker.containerd.gcpolicy]] - keepBytes = 512000000 + reservedSpace = 512000000 keepDuration = 172800 filters = [ "type==source.local", "type==exec.cachemount", "type==source.git.checkout"] [[worker.containerd.gcpolicy]] all = true - keepBytes = 1024000000 + reservedSpace = 1024000000 # registry configures a new Docker register used for cache import or output. [registry."docker.io"] diff --git a/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/reference.md b/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/reference.md index 1cf73cd242c..a5749ca533c 100644 --- a/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/reference.md +++ b/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/reference.md @@ -47,8 +47,8 @@ be UPPERCASE to distinguish them from arguments more easily. Docker runs instructions in a Dockerfile in order. A Dockerfile **must begin with a `FROM` instruction**. This may be after [parser directives](#parser-directives), [comments](#format), and globally scoped -[ARGs](#arg). The `FROM` instruction specifies the [parent -image](https://docs.docker.com/glossary/#parent-image) from which you are +[ARGs](#arg). The `FROM` instruction specifies the [base +image](https://docs.docker.com/glossary/#base-image) from which you are building. `FROM` may only be preceded by one or more `ARG` instructions, which declare arguments that are used in `FROM` lines in the Dockerfile. @@ -192,11 +192,6 @@ following lines are all treated identically: # dIrEcTiVe=value ``` -The following parser directives are supported: - -- `syntax` -- `escape` - ### syntax @@ -345,6 +340,11 @@ despite warnings. To make the build fail on warnings, set `#check=error=true`. # check=error=true ``` +> [!NOTE] +> When using the `check` directive, with `error=true` option, it is recommended +> to pin the [Dockerfile syntax](#syntax) to a specific version. Otherwise, your build may +> start to fail when new checks are added in the future versions. + To combine both the `skip` and `error` options, use a semi-colon to separate them: @@ -723,7 +723,7 @@ This can be used to: The supported mount types are: | Type | Description | -| ---------------------------------------- | --------------------------------------------------------------------------------------------------------- | +| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | [`bind`](#run---mounttypebind) (default) | Bind-mount context directories (read-only). | | [`cache`](#run---mounttypecache) | Mount a temporary directory to cache directories for compilers and package managers. | | [`tmpfs`](#run---mounttypetmpfs) | Mount a `tmpfs` in the build container. | @@ -736,7 +736,7 @@ This mount type allows binding files or directories to the build container. A bind mount is read-only by default. | Option | Description | -| ---------------- | ---------------------------------------------------------------------------------------------- | +| ---------------------------------- | ---------------------------------------------------------------------------------------------- | | `target`, `dst`, `destination`[^1] | Mount path. | | `source` | Source path in the `from`. Defaults to the root of the `from`. | | `from` | Build stage, context, or image name for the root of the source. Defaults to the build context. | @@ -748,7 +748,7 @@ This mount type allows the build container to cache directories for compilers and package managers. | Option | Description | -| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | Optional ID to identify separate/different caches. Defaults to value of `target`. | | `target`, `dst`, `destination`[^1] | Mount path. | | `ro`,`readonly` | Read-only if set. | @@ -797,7 +797,7 @@ case. This mount type allows mounting `tmpfs` in the build container. | Option | Description | -| ------------ | ----------------------------------------------------- | +| ---------------------------------- | ----------------------------------------------------- | | `target`, `dst`, `destination`[^1] | Mount path. | | `size` | Specify an upper limit on the size of the filesystem. | @@ -842,7 +842,7 @@ environment variable with the same name. # syntax=docker/dockerfile:1 FROM alpine RUN --mount=type=secret,id=API_KEY,env=API_KEY \ - some-command --token-from-env API_KEY + some-command --token-from-env $API_KEY ``` Assuming that the `API_KEY` environment variable is set in the build @@ -858,7 +858,7 @@ This mount type allows the build container to access SSH keys via SSH agents, with support for passphrases. | Option | Description | -| ---------- | ---------------------------------------------------------------------------------------------- | +| ------------------------------ | ---------------------------------------------------------------------------------------------- | | `id` | ID of SSH agent socket or key. Defaults to "default". | | `target`, `dst`, `destination` | SSH agent socket path. Defaults to `/run/buildkit/ssh_agent.${N}`. | | `required` | If set to `true`, the instruction errors out when the key is unavailable. Defaults to `false`. | @@ -938,7 +938,6 @@ The command is run in the host's network environment (similar to > which needs to be enabled when starting the buildkitd daemon with > `--allow-insecure-entitlement network.host` flag or in [buildkitd config](https://github.com/moby/buildkit/blob/master/docs/buildkitd.toml.md), > and for a build request with [`--allow network.host` flag](https://docs.docker.com/engine/reference/commandline/buildx_build/#allow). -{ .warning } ### RUN --security @@ -959,7 +958,6 @@ This is equivalent to running `docker run --privileged`. > enabled when starting the buildkitd daemon with > `--allow-insecure-entitlement security.insecure` flag or in [buildkitd config](https://github.com/moby/buildkit/blob/master/docs/buildkitd.toml.md), > and for a build request with [`--allow security.insecure` flag](https://docs.docker.com/engine/reference/commandline/buildx_build/#allow). -{ .warning } Default sandbox mode can be activated via `--security=sandbox`, but that is no-op. @@ -1012,7 +1010,7 @@ both the `CMD` and `ENTRYPOINT` instructions should be specified in the ## LABEL ```dockerfile -LABEL = = = ... +LABEL = [=...] ``` The `LABEL` instruction adds metadata to an image. A `LABEL` is a @@ -1047,9 +1045,9 @@ LABEL multi.label1="value1" \ > using string interpolation (e.g. `LABEL example="foo-$ENV_VAR"`), single > quotes will take the string as is without unpacking the variable's value. -Labels included in base or parent images (images in the `FROM` line) are -inherited by your image. If a label already exists but with a different value, -the most-recently-applied value overrides any previously-set value. +Labels included in base images (images in the `FROM` line) are inherited by +your image. If a label already exists but with a different value, the +most-recently-applied value overrides any previously-set value. To view an image's labels, use the `docker image inspect` command. You can use the `--format` option to show just the labels; @@ -1139,7 +1137,7 @@ port. For detailed information, see the ## ENV ```dockerfile -ENV = ... +ENV = [=...] ``` The `ENV` instruction sets the environment variable `` to the value @@ -1232,7 +1230,7 @@ The available `[OPTIONS]` are: | [`--chown`](#add---chown---chmod) | | | [`--chmod`](#add---chown---chmod) | 1.2 | | [`--link`](#add---link) | 1.4 | -| [`--exclude`](#add---exclude) | 1.7 | +| [`--exclude`](#add---exclude) | 1.7-labs | The `ADD` instruction copies new files or directories from `` and adds them to the filesystem of the image at the path ``. Files and directories @@ -1517,8 +1515,8 @@ The available `[OPTIONS]` are: | [`--chown`](#copy---chown---chmod) | | | [`--chmod`](#copy---chown---chmod) | 1.2 | | [`--link`](#copy---link) | 1.4 | -| [`--parents`](#copy---parents) | 1.7 | -| [`--exclude`](#copy---exclude) | 1.7 | +| [`--parents`](#copy---parents) | 1.7-labs | +| [`--exclude`](#copy---exclude) | 1.7-labs | The `COPY` instruction copies new files or directories from `` and adds them to the filesystem of the image at the path ``. Files and directories @@ -1815,7 +1813,7 @@ COPY [--parents[=]] ... The `--parents` flag preserves parent directories for `src` entries. This flag defaults to `false`. ```dockerfile -# syntax=docker/dockerfile:1.7-labs +# syntax=docker/dockerfile:1-labs FROM scratch COPY ./x/a.txt ./y/a.txt /no_parents/ @@ -1835,7 +1833,7 @@ directories after it will be preserved. This may be especially useful copies bet with `--from` where the source paths need to be absolute. ```dockerfile -# syntax=docker/dockerfile:1.7-labs +# syntax=docker/dockerfile:1-labs FROM scratch COPY --parents ./x/./y/*.txt /parents/ @@ -1877,6 +1875,9 @@ supporting wildcards and matching using Go's For example, to add all files starting with "hom", excluding files with a `.txt` extension: ```dockerfile +# syntax=docker/dockerfile:1-labs +FROM scratch + COPY --exclude=*.txt hom* /mydir/ ``` @@ -1886,6 +1887,9 @@ even if the files paths match the pattern specified in ``. To add all files starting with "hom", excluding files with either `.txt` or `.md` extensions: ```dockerfile +# syntax=docker/dockerfile:1-labs +FROM scratch + COPY --exclude=*.txt --exclude=*.md hom* /mydir/ ``` @@ -2212,7 +2216,8 @@ Keep the following things in mind about volumes in the Dockerfile. - a drive other than `C:` - **Changing the volume from within the Dockerfile**: If any build steps change the - data within the volume after it has been declared, those changes will be discarded. + data within the volume after it has been declared, those changes will be discarded + when using the legacy builder. When using Buildkit, the changes will instead be kept. - **JSON formatting**: The list is parsed as a JSON array. You must enclose words with double quotes (`"`) rather than single quotes (`'`). @@ -2250,7 +2255,6 @@ runtime, runs the relevant `ENTRYPOINT` and `CMD` commands. > > On Windows, the user must be created first if it's not a built-in account. > This can be done with the `net user` command called as part of a Dockerfile. -{ .warning } ```dockerfile FROM microsoft/windowsservercore @@ -2305,7 +2309,7 @@ Therefore, to avoid unintended operations in unknown directories, it's best prac ## ARG ```dockerfile -ARG [=] +ARG [=] [[=]...] ``` The `ARG` instruction defines a variable that users can pass at build-time to @@ -2321,7 +2325,6 @@ flag. > > Refer to the [`RUN --mount=type=secret`](#run---mounttypesecret) section to > learn about secure ways to use secrets when building images. -{ .warning } A Dockerfile may include one or more `ARG` instructions. For example, the following is a valid Dockerfile: @@ -2349,9 +2352,8 @@ at build-time, the builder uses the default. ### Scope -An `ARG` variable definition comes into effect from the line on which it is -defined in the Dockerfile not from the argument's use on the command-line or -elsewhere. For example, consider this Dockerfile: +An `ARG` variable comes into effect from the line on which it is declared in +the Dockerfile. For example, consider this Dockerfile: ```dockerfile FROM busybox @@ -2367,24 +2369,22 @@ A user builds this file by calling: $ docker build --build-arg username=what_user . ``` -The `USER` at line 2 evaluates to `some_user` as the `username` variable is defined on the -subsequent line 3. The `USER` at line 4 evaluates to `what_user`, as the `username` argument is -defined and the `what_user` value was passed on the command line. Prior to its definition by an -`ARG` instruction, any use of a variable results in an empty string. +- The `USER` instruction on line 2 evaluates to the `some_user` fallback, + because the `username` variable is not yet declared. +- The `username` variable is declared on line 3, and available for reference in + Dockerfile instruction from that point onwards. +- The `USER` instruction on line 4 evaluates to `what_user`, since at that + point the `username` argument has a value of `what_user` which was passed on + the command line. Prior to its definition by an `ARG` instruction, any use of + a variable results in an empty string. -An `ARG` instruction goes out of scope at the end of the build -stage where it was defined. To use an argument in multiple stages, each stage must -include the `ARG` instruction. +An `ARG` variable declared within a build stage is automatically inherited by +other stages based on that stage. Unrelated build stages do not have access to +the variable. To use an argument in multiple distinct stages, each stage must +include the `ARG` instruction, or they must both be based on a shared base +stage in the same Dockerfile where the variable is declared. -```dockerfile -FROM busybox -ARG SETTINGS -RUN ./run/setup $SETTINGS - -FROM busybox -ARG SETTINGS -RUN ./run/other $SETTINGS -``` +For more information, refer to [variable scoping](https://docs.docker.com/build/building/variables/#scoping). ### Using ARG variables @@ -2622,8 +2622,6 @@ another build. The trigger will be executed in the context of the downstream build, as if it had been inserted immediately after the `FROM` instruction in the downstream Dockerfile. -Any build instruction can be registered as a trigger. - This is useful if you are building an image which will be used as a base to build other images, for example an application build environment or a daemon which may be customized with user-specific configuration. @@ -2666,11 +2664,26 @@ ONBUILD ADD . /app/src ONBUILD RUN /usr/local/bin/python-build --dir /app/src ``` +### Copy or mount from stage, image, or context + +As of Dockerfile syntax 1.11, you can use `ONBUILD` with instructions that copy +or mount files from other stages, images, or build contexts. For example: + +```dockerfile +# syntax=docker/dockerfile:1.11 +FROM alpine AS baseimage +ONBUILD COPY --from=build /usr/bin/app /app +ONBUILD RUN --mount=from=config,target=/opt/appconfig ... +``` + +If the source of `from` is a build stage, the stage must be defined in the +Dockerfile where `ONBUILD` gets triggered. If it's a named context, that +context must be passed to the downstream build. + ### ONBUILD limitations - Chaining `ONBUILD` instructions using `ONBUILD ONBUILD` isn't allowed. - The `ONBUILD` instruction may not trigger `FROM` or `MAINTAINER` instructions. -- `ONBUILD COPY --from` is [not supported](https://github.com/moby/buildkit/issues/816). ## STOPSIGNAL @@ -3002,10 +3015,9 @@ hello world For examples of Dockerfiles, refer to: -- The ["build images" section](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/) -- The ["get started" tutorial](https://docs.docker.com/get-started/) -- The [language-specific getting started guides](https://docs.docker.com/language/) -- The [build guide](https://docs.docker.com/build/guide/) +- The [building best practices page](https://docs.docker.com/build/building/best-practices/) +- The ["get started" tutorials](https://docs.docker.com/get-started/) +- The [language-specific getting started guides](https://docs.docker.com/guides/language/) [^1]: Value required [^2]: For Docker-integrated [BuildKit](https://docs.docker.com/build/buildkit/#getting-started) and `docker buildx build` diff --git a/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/_index.md b/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/_index.md index bd22a77db9c..0938ace3dfe 100644 --- a/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/_index.md +++ b/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/_index.md @@ -103,5 +103,9 @@ To learn more about how to use build checks, see CopyIgnoredFile (experimental) Attempting to Copy file that is excluded by .dockerignore + + InvalidDefinitionDescription (experimental) + Comment for build stage or argument should follow the format: `# `. If this is not intended to be a description comment, add an empty line or comment between the instruction and the comment. + diff --git a/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/consistent-instruction-casing.md b/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/consistent-instruction-casing.md index b080490d473..cef6e16c7a1 100644 --- a/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/consistent-instruction-casing.md +++ b/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/consistent-instruction-casing.md @@ -1,6 +1,7 @@ --- title: ConsistentInstructionCasing -description: All commands within the Dockerfile should use the same casing (either upper or lower) +description: >- + All commands within the Dockerfile should use the same casing (either upper or lower) aliases: - /go/dockerfile/rule/consistent-instruction-casing/ --- diff --git a/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/copy-ignored-file.md b/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/copy-ignored-file.md index fd16896131b..3e8e57e8d4c 100644 --- a/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/copy-ignored-file.md +++ b/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/copy-ignored-file.md @@ -1,6 +1,7 @@ --- title: CopyIgnoredFile -description: Attempting to Copy file that is excluded by .dockerignore +description: >- + Attempting to Copy file that is excluded by .dockerignore aliases: - /go/dockerfile/rule/copy-ignored-file/ --- diff --git a/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/duplicate-stage-name.md b/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/duplicate-stage-name.md index 67fe4da8c1f..71cdfcaf91d 100644 --- a/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/duplicate-stage-name.md +++ b/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/duplicate-stage-name.md @@ -1,6 +1,7 @@ --- title: DuplicateStageName -description: Stage names should be unique +description: >- + Stage names should be unique aliases: - /go/dockerfile/rule/duplicate-stage-name/ --- diff --git a/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/from-as-casing.md b/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/from-as-casing.md index 5897f66fb23..03506c0ac80 100644 --- a/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/from-as-casing.md +++ b/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/from-as-casing.md @@ -1,6 +1,7 @@ --- title: FromAsCasing -description: The 'as' keyword should match the case of the 'from' keyword +description: >- + The 'as' keyword should match the case of the 'from' keyword aliases: - /go/dockerfile/rule/from-as-casing/ --- diff --git a/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/from-platform-flag-const-disallowed.md b/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/from-platform-flag-const-disallowed.md index 9e4f7878871..8a89ba27518 100644 --- a/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/from-platform-flag-const-disallowed.md +++ b/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/from-platform-flag-const-disallowed.md @@ -1,6 +1,7 @@ --- title: FromPlatformFlagConstDisallowed -description: FROM --platform flag should not use a constant value +description: >- + FROM --platform flag should not use a constant value aliases: - /go/dockerfile/rule/from-platform-flag-const-disallowed/ --- diff --git a/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/invalid-default-arg-in-from.md b/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/invalid-default-arg-in-from.md index 2e6ff309d3d..aedce495ab7 100644 --- a/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/invalid-default-arg-in-from.md +++ b/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/invalid-default-arg-in-from.md @@ -1,6 +1,7 @@ --- title: InvalidDefaultArgInFrom -description: Default value for global ARG results in an empty or invalid base image name +description: >- + Default value for global ARG results in an empty or invalid base image name aliases: - /go/dockerfile/rule/invalid-default-arg-in-from/ --- diff --git a/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/invalid-definition-description.md b/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/invalid-definition-description.md new file mode 100644 index 00000000000..31ca1f7bc72 --- /dev/null +++ b/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/invalid-definition-description.md @@ -0,0 +1,71 @@ +--- +title: InvalidDefinitionDescription +description: >- + Comment for build stage or argument should follow the format: `# `. If this is not intended to be a description comment, add an empty line or comment between the instruction and the comment. +aliases: + - /go/dockerfile/rule/invalid-definition-description/ +--- + +> [!NOTE] +> This check is experimental and is not enabled by default. To enable it, see +> [Experimental checks](https://docs.docker.com/go/build-checks-experimental/). + +## Output + +```text +Comment for build stage or argument should follow the format: `# `. If this is not intended to be a description comment, add an empty line or comment between the instruction and the comment. +``` + +## Description + +The [`--call=outline`](https://docs.docker.com/reference/cli/docker/buildx/build/#call-outline) +and [`--call=targets`](https://docs.docker.com/reference/cli/docker/buildx/build/#call-outline) +flags for the `docker build` command print descriptions for build targets and arguments. +The descriptions are generated from [Dockerfile comments](https://docs.docker.com/reference/cli/docker/buildx/build/#descriptions) +that immediately precede the `FROM` or `ARG` instruction +and that begin with the name of the build stage or argument. +For example: + +```dockerfile +# build-cli builds the CLI binary +FROM alpine AS build-cli +# VERSION controls the version of the program +ARG VERSION=1 +``` + +In cases where preceding comments are not meant to be descriptions, +add an empty line or comment between the instruction and the preceding comment. + +## Examples + +❌ Bad: A non-descriptive comment on the line preceding the `FROM` command. + +```dockerfile +# a non-descriptive comment +FROM scratch AS base + +# another non-descriptive comment +ARG VERSION=1 +``` + +✅ Good: An empty line separating non-descriptive comments. + +```dockerfile +# a non-descriptive comment + +FROM scratch AS base + +# another non-descriptive comment + +ARG VERSION=1 +``` + +✅ Good: Comments describing `ARG` keys and stages immediately proceeding the command. + +```dockerfile +# base is a stage for compiling source +FROM scratch AS base +# VERSION This is the version number. +ARG VERSION=1 +``` + diff --git a/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/json-args-recommended.md b/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/json-args-recommended.md index 0d69b2a67ca..0fa7b01def1 100644 --- a/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/json-args-recommended.md +++ b/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/json-args-recommended.md @@ -1,6 +1,7 @@ --- title: JSONArgsRecommended -description: JSON arguments recommended for ENTRYPOINT/CMD to prevent unintended behavior related to OS signals +description: >- + JSON arguments recommended for ENTRYPOINT/CMD to prevent unintended behavior related to OS signals aliases: - /go/dockerfile/rule/json-args-recommended/ --- @@ -50,10 +51,41 @@ Note that running programs as PID 1 means the program now has the special responsibilities and behaviors associated with PID 1 in Linux, such as reaping child processes. -Alternatively, if you want to ignore this lint rule because you do want your -executable to be invoked via a shell, you can use the -[`SHELL`](https://docs.docker.com/reference/dockerfile.md#shell) Dockerfile -instruction to explicitly specify a shell to use. +### Workarounds + +There might still be cases when you want to run your containers under a shell. +When using exec form, shell features such as variable expansion, piping (`|`) +and command chaining (`&&`, `||`, `;`), are not available. To use such +features, you need to use shell form. + +Here are some ways you can achieve that. Note that this still means that +executables run as child-processes of a shell. + +#### Create a wrapper script + +You can create an entrypoint script that wraps your startup commands, and +execute that script with a JSON-formatted `ENTRYPOINT` command. + +✅ Good: the `ENTRYPOINT` uses JSON format. + +```dockerfile +FROM alpine +RUN apk add bash +COPY --chmod=755 <- + Legacy key/value format with whitespace separator should not be used aliases: - /go/dockerfile/rule/legacy-key-value-format/ --- diff --git a/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/maintainer-deprecated.md b/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/maintainer-deprecated.md index c777a17d345..95c1f18dffa 100644 --- a/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/maintainer-deprecated.md +++ b/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/maintainer-deprecated.md @@ -1,6 +1,7 @@ --- title: MaintainerDeprecated -description: The MAINTAINER instruction is deprecated, use a label instead to define an image author +description: >- + The MAINTAINER instruction is deprecated, use a label instead to define an image author aliases: - /go/dockerfile/rule/maintainer-deprecated/ --- diff --git a/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/multiple-instructions-disallowed.md b/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/multiple-instructions-disallowed.md index 6f8313f55e6..09267bfd220 100644 --- a/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/multiple-instructions-disallowed.md +++ b/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/multiple-instructions-disallowed.md @@ -1,6 +1,7 @@ --- title: MultipleInstructionsDisallowed -description: Multiple instructions of the same type should not be used in the same stage +description: >- + Multiple instructions of the same type should not be used in the same stage aliases: - /go/dockerfile/rule/multiple-instructions-disallowed/ --- diff --git a/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/no-empty-continuation.md b/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/no-empty-continuation.md index 4636eabf5d7..8437859e456 100644 --- a/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/no-empty-continuation.md +++ b/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/no-empty-continuation.md @@ -1,6 +1,7 @@ --- title: NoEmptyContinuation -description: Empty continuation lines will become errors in a future release +description: >- + Empty continuation lines will become errors in a future release aliases: - /go/dockerfile/rule/no-empty-continuation/ --- diff --git a/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/redundant-target-platform.md b/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/redundant-target-platform.md index 84bdfae060f..f6192bb3b44 100644 --- a/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/redundant-target-platform.md +++ b/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/redundant-target-platform.md @@ -1,6 +1,7 @@ --- title: RedundantTargetPlatform -description: Setting platform to predefined $TARGETPLATFORM in FROM is redundant as this is the default behavior +description: >- + Setting platform to predefined $TARGETPLATFORM in FROM is redundant as this is the default behavior aliases: - /go/dockerfile/rule/redundant-target-platform/ --- diff --git a/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/reserved-stage-name.md b/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/reserved-stage-name.md index bde3509be83..7f2a550d351 100644 --- a/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/reserved-stage-name.md +++ b/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/reserved-stage-name.md @@ -1,6 +1,7 @@ --- title: ReservedStageName -description: Reserved words should not be used as stage names +description: >- + Reserved words should not be used as stage names aliases: - /go/dockerfile/rule/reserved-stage-name/ --- diff --git a/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/secrets-used-in-arg-or-env.md b/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/secrets-used-in-arg-or-env.md index 4bee96fbdd7..db9d1caae67 100644 --- a/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/secrets-used-in-arg-or-env.md +++ b/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/secrets-used-in-arg-or-env.md @@ -1,6 +1,7 @@ --- title: SecretsUsedInArgOrEnv -description: Sensitive data should not be used in the ARG or ENV commands +description: >- + Sensitive data should not be used in the ARG or ENV commands aliases: - /go/dockerfile/rule/secrets-used-in-arg-or-env/ --- diff --git a/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/stage-name-casing.md b/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/stage-name-casing.md index 6aa82144725..1324350a2e3 100644 --- a/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/stage-name-casing.md +++ b/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/stage-name-casing.md @@ -1,6 +1,7 @@ --- title: StageNameCasing -description: Stage names should be lowercase +description: >- + Stage names should be lowercase aliases: - /go/dockerfile/rule/stage-name-casing/ --- diff --git a/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/undefined-arg-in-from.md b/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/undefined-arg-in-from.md index c07b60115b3..3ec4632d2d1 100644 --- a/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/undefined-arg-in-from.md +++ b/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/undefined-arg-in-from.md @@ -1,6 +1,7 @@ --- title: UndefinedArgInFrom -description: FROM command must use declared ARGs +description: >- + FROM command must use declared ARGs aliases: - /go/dockerfile/rule/undefined-arg-in-from/ --- diff --git a/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/undefined-var.md b/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/undefined-var.md index 037e16bd239..f44ae6960a2 100644 --- a/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/undefined-var.md +++ b/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/undefined-var.md @@ -1,6 +1,7 @@ --- title: UndefinedVar -description: Variables should be defined before their use +description: >- + Variables should be defined before their use aliases: - /go/dockerfile/rule/undefined-var/ --- @@ -13,24 +14,25 @@ Usage of undefined variable '$foo' ## Description -Before you reference an environment variable or a build argument in a `RUN` -instruction, you should ensure that the variable is declared in the Dockerfile, -using the `ARG` or `ENV` instructions. +This check ensures that environment variables and build arguments are correctly +declared before being used. While undeclared variables might not cause an +immediate build failure, they can lead to unexpected behavior or errors later +in the build process. -Attempting to access an environment variable without explicitly declaring it -doesn't necessarily result in a build error, but it may yield an unexpected -result or an error later on in the build process. +This check does not evaluate undefined variables for `RUN`, `CMD`, and +`ENTRYPOINT` instructions where you use the [shell form](https://docs.docker.com/reference/dockerfile/#shell-form). +That's because when you use shell form, variables are resolved by the command +shell. -This check also attempts to detect if you're accessing a variable with a typo. -For example, given the following Dockerfile: +It also detects common mistakes like typos in variable names. For example, in +the following Dockerfile: ```dockerfile FROM alpine ENV PATH=$PAHT:/app/bin ``` -The check detects that `$PAHT` is undefined, and that it's probably a -misspelling of `PATH`. +The check identifies that `$PAHT` is undefined and likely a typo for `$PATH`: ```text Usage of undefined variable '$PAHT' (did you mean $PATH?) @@ -53,3 +55,17 @@ ARG foo COPY $foo . ``` +❌ Bad: `$foo` is undefined. + +```dockerfile +FROM alpine AS base +ARG VERSION=$foo +``` + +✅ Good: the base image defines `$PYTHON_VERSION` + +```dockerfile +FROM python AS base +ARG VERSION=$PYTHON_VERSION +``` + diff --git a/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/workdir-relative-path.md b/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/workdir-relative-path.md index 2e165323e4f..06043ea15a0 100644 --- a/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/workdir-relative-path.md +++ b/_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/workdir-relative-path.md @@ -1,6 +1,7 @@ --- title: WorkdirRelativePath -description: Relative workdir without an absolute workdir declared within the build can have unexpected results if the base image changes +description: >- + Relative workdir without an absolute workdir declared within the build can have unexpected results if the base image changes aliases: - /go/dockerfile/rule/workdir-relative-path/ --- diff --git a/_vendor/github.com/moby/moby/docs/api/v1.25.yaml b/_vendor/github.com/moby/moby/docs/api/v1.25.yaml index fcdf392a909..f3aba9f65c2 100644 --- a/_vendor/github.com/moby/moby/docs/api/v1.25.yaml +++ b/_vendor/github.com/moby/moby/docs/api/v1.25.yaml @@ -3501,10 +3501,12 @@ paths: type: "string" - name: "h" in: "query" + required: true description: "Height of the tty session in characters" type: "integer" - name: "w" in: "query" + required: true description: "Width of the tty session in characters" type: "integer" tags: ["Container"] @@ -5721,10 +5723,12 @@ paths: type: "string" - name: "h" in: "query" + required: true description: "Height of the TTY session in characters" type: "integer" - name: "w" in: "query" + required: true description: "Width of the TTY session in characters" type: "integer" tags: ["Exec"] diff --git a/_vendor/github.com/moby/moby/docs/api/v1.26.yaml b/_vendor/github.com/moby/moby/docs/api/v1.26.yaml index db036d6b3f3..cd1470fb324 100644 --- a/_vendor/github.com/moby/moby/docs/api/v1.26.yaml +++ b/_vendor/github.com/moby/moby/docs/api/v1.26.yaml @@ -3505,10 +3505,12 @@ paths: type: "string" - name: "h" in: "query" + required: true description: "Height of the tty session in characters" type: "integer" - name: "w" in: "query" + required: true description: "Width of the tty session in characters" type: "integer" tags: ["Container"] @@ -5729,10 +5731,12 @@ paths: type: "string" - name: "h" in: "query" + required: true description: "Height of the TTY session in characters" type: "integer" - name: "w" in: "query" + required: true description: "Width of the TTY session in characters" type: "integer" tags: ["Exec"] diff --git a/_vendor/github.com/moby/moby/docs/api/v1.27.yaml b/_vendor/github.com/moby/moby/docs/api/v1.27.yaml index b4511318060..2b4b3e5be56 100644 --- a/_vendor/github.com/moby/moby/docs/api/v1.27.yaml +++ b/_vendor/github.com/moby/moby/docs/api/v1.27.yaml @@ -3572,10 +3572,12 @@ paths: type: "string" - name: "h" in: "query" + required: true description: "Height of the tty session in characters" type: "integer" - name: "w" in: "query" + required: true description: "Width of the tty session in characters" type: "integer" tags: ["Container"] @@ -5803,10 +5805,12 @@ paths: type: "string" - name: "h" in: "query" + required: true description: "Height of the TTY session in characters" type: "integer" - name: "w" in: "query" + required: true description: "Width of the TTY session in characters" type: "integer" tags: ["Exec"] diff --git a/_vendor/github.com/moby/moby/docs/api/v1.28.yaml b/_vendor/github.com/moby/moby/docs/api/v1.28.yaml index 5781053b28d..f565ef5d1d0 100644 --- a/_vendor/github.com/moby/moby/docs/api/v1.28.yaml +++ b/_vendor/github.com/moby/moby/docs/api/v1.28.yaml @@ -3663,10 +3663,12 @@ paths: type: "string" - name: "h" in: "query" + required: true description: "Height of the tty session in characters" type: "integer" - name: "w" in: "query" + required: true description: "Width of the tty session in characters" type: "integer" tags: ["Container"] @@ -5918,10 +5920,12 @@ paths: type: "string" - name: "h" in: "query" + required: true description: "Height of the TTY session in characters" type: "integer" - name: "w" in: "query" + required: true description: "Width of the TTY session in characters" type: "integer" tags: ["Exec"] diff --git a/_vendor/github.com/moby/moby/docs/api/v1.29.yaml b/_vendor/github.com/moby/moby/docs/api/v1.29.yaml index 1ab1f00f318..ff014b2086e 100644 --- a/_vendor/github.com/moby/moby/docs/api/v1.29.yaml +++ b/_vendor/github.com/moby/moby/docs/api/v1.29.yaml @@ -3696,10 +3696,12 @@ paths: type: "string" - name: "h" in: "query" + required: true description: "Height of the tty session in characters" type: "integer" - name: "w" in: "query" + required: true description: "Width of the tty session in characters" type: "integer" tags: ["Container"] @@ -5951,10 +5953,12 @@ paths: type: "string" - name: "h" in: "query" + required: true description: "Height of the TTY session in characters" type: "integer" - name: "w" in: "query" + required: true description: "Width of the TTY session in characters" type: "integer" tags: ["Exec"] diff --git a/_vendor/github.com/moby/moby/docs/api/v1.30.yaml b/_vendor/github.com/moby/moby/docs/api/v1.30.yaml index c182c9149f4..3461d022b03 100644 --- a/_vendor/github.com/moby/moby/docs/api/v1.30.yaml +++ b/_vendor/github.com/moby/moby/docs/api/v1.30.yaml @@ -3921,10 +3921,12 @@ paths: type: "string" - name: "h" in: "query" + required: true description: "Height of the tty session in characters" type: "integer" - name: "w" in: "query" + required: true description: "Width of the tty session in characters" type: "integer" tags: ["Container"] @@ -6205,10 +6207,12 @@ paths: type: "string" - name: "h" in: "query" + required: true description: "Height of the TTY session in characters" type: "integer" - name: "w" in: "query" + required: true description: "Width of the TTY session in characters" type: "integer" tags: ["Exec"] diff --git a/_vendor/github.com/moby/moby/docs/api/v1.31.yaml b/_vendor/github.com/moby/moby/docs/api/v1.31.yaml index 05812bfa06f..61c232bbe49 100644 --- a/_vendor/github.com/moby/moby/docs/api/v1.31.yaml +++ b/_vendor/github.com/moby/moby/docs/api/v1.31.yaml @@ -3990,10 +3990,12 @@ paths: type: "string" - name: "h" in: "query" + required: true description: "Height of the tty session in characters" type: "integer" - name: "w" in: "query" + required: true description: "Width of the tty session in characters" type: "integer" tags: ["Container"] @@ -6297,10 +6299,12 @@ paths: type: "string" - name: "h" in: "query" + required: true description: "Height of the TTY session in characters" type: "integer" - name: "w" in: "query" + required: true description: "Width of the TTY session in characters" type: "integer" tags: ["Exec"] diff --git a/_vendor/github.com/moby/moby/docs/api/v1.32.yaml b/_vendor/github.com/moby/moby/docs/api/v1.32.yaml index 85b2341f44b..158d205d578 100644 --- a/_vendor/github.com/moby/moby/docs/api/v1.32.yaml +++ b/_vendor/github.com/moby/moby/docs/api/v1.32.yaml @@ -5223,10 +5223,12 @@ paths: type: "string" - name: "h" in: "query" + required: true description: "Height of the tty session in characters" type: "integer" - name: "w" in: "query" + required: true description: "Width of the tty session in characters" type: "integer" tags: ["Container"] @@ -7335,10 +7337,12 @@ paths: type: "string" - name: "h" in: "query" + required: true description: "Height of the TTY session in characters" type: "integer" - name: "w" in: "query" + required: true description: "Width of the TTY session in characters" type: "integer" tags: ["Exec"] diff --git a/_vendor/github.com/moby/moby/docs/api/v1.33.yaml b/_vendor/github.com/moby/moby/docs/api/v1.33.yaml index 20b0878ea60..af1375432b5 100644 --- a/_vendor/github.com/moby/moby/docs/api/v1.33.yaml +++ b/_vendor/github.com/moby/moby/docs/api/v1.33.yaml @@ -5227,10 +5227,12 @@ paths: type: "string" - name: "h" in: "query" + required: true description: "Height of the tty session in characters" type: "integer" - name: "w" in: "query" + required: true description: "Width of the tty session in characters" type: "integer" tags: ["Container"] @@ -7343,10 +7345,12 @@ paths: type: "string" - name: "h" in: "query" + required: true description: "Height of the TTY session in characters" type: "integer" - name: "w" in: "query" + required: true description: "Width of the TTY session in characters" type: "integer" tags: ["Exec"] diff --git a/_vendor/github.com/moby/moby/docs/api/v1.34.yaml b/_vendor/github.com/moby/moby/docs/api/v1.34.yaml index 4e17b3fbd92..d36f7d5bb57 100644 --- a/_vendor/github.com/moby/moby/docs/api/v1.34.yaml +++ b/_vendor/github.com/moby/moby/docs/api/v1.34.yaml @@ -5255,10 +5255,12 @@ paths: type: "string" - name: "h" in: "query" + required: true description: "Height of the tty session in characters" type: "integer" - name: "w" in: "query" + required: true description: "Width of the tty session in characters" type: "integer" tags: ["Container"] @@ -7383,10 +7385,12 @@ paths: type: "string" - name: "h" in: "query" + required: true description: "Height of the TTY session in characters" type: "integer" - name: "w" in: "query" + required: true description: "Width of the TTY session in characters" type: "integer" tags: ["Exec"] diff --git a/_vendor/github.com/moby/moby/docs/api/v1.35.yaml b/_vendor/github.com/moby/moby/docs/api/v1.35.yaml index 82aa3cff8ba..5071dfd2396 100644 --- a/_vendor/github.com/moby/moby/docs/api/v1.35.yaml +++ b/_vendor/github.com/moby/moby/docs/api/v1.35.yaml @@ -5263,10 +5263,12 @@ paths: type: "string" - name: "h" in: "query" + required: true description: "Height of the tty session in characters" type: "integer" - name: "w" in: "query" + required: true description: "Width of the tty session in characters" type: "integer" tags: ["Container"] @@ -7416,10 +7418,12 @@ paths: type: "string" - name: "h" in: "query" + required: true description: "Height of the TTY session in characters" type: "integer" - name: "w" in: "query" + required: true description: "Width of the TTY session in characters" type: "integer" tags: ["Exec"] diff --git a/_vendor/github.com/moby/moby/docs/api/v1.36.yaml b/_vendor/github.com/moby/moby/docs/api/v1.36.yaml index 0e5e4fe58cf..96e905d3fe2 100644 --- a/_vendor/github.com/moby/moby/docs/api/v1.36.yaml +++ b/_vendor/github.com/moby/moby/docs/api/v1.36.yaml @@ -5283,10 +5283,12 @@ paths: type: "string" - name: "h" in: "query" + required: true description: "Height of the tty session in characters" type: "integer" - name: "w" in: "query" + required: true description: "Width of the tty session in characters" type: "integer" tags: ["Container"] @@ -7450,10 +7452,12 @@ paths: type: "string" - name: "h" in: "query" + required: true description: "Height of the TTY session in characters" type: "integer" - name: "w" in: "query" + required: true description: "Width of the TTY session in characters" type: "integer" tags: ["Exec"] diff --git a/_vendor/github.com/moby/moby/docs/api/v1.37.yaml b/_vendor/github.com/moby/moby/docs/api/v1.37.yaml index 80cbc2199bd..f10b2912360 100644 --- a/_vendor/github.com/moby/moby/docs/api/v1.37.yaml +++ b/_vendor/github.com/moby/moby/docs/api/v1.37.yaml @@ -5303,10 +5303,12 @@ paths: type: "string" - name: "h" in: "query" + required: true description: "Height of the tty session in characters" type: "integer" - name: "w" in: "query" + required: true description: "Width of the tty session in characters" type: "integer" tags: ["Container"] @@ -7493,10 +7495,12 @@ paths: type: "string" - name: "h" in: "query" + required: true description: "Height of the TTY session in characters" type: "integer" - name: "w" in: "query" + required: true description: "Width of the TTY session in characters" type: "integer" tags: ["Exec"] diff --git a/_vendor/github.com/moby/moby/docs/api/v1.38.yaml b/_vendor/github.com/moby/moby/docs/api/v1.38.yaml index f74d9679767..f82650b0198 100644 --- a/_vendor/github.com/moby/moby/docs/api/v1.38.yaml +++ b/_vendor/github.com/moby/moby/docs/api/v1.38.yaml @@ -5364,10 +5364,12 @@ paths: type: "string" - name: "h" in: "query" + required: true description: "Height of the tty session in characters" type: "integer" - name: "w" in: "query" + required: true description: "Width of the tty session in characters" type: "integer" tags: ["Container"] @@ -7564,10 +7566,12 @@ paths: type: "string" - name: "h" in: "query" + required: true description: "Height of the TTY session in characters" type: "integer" - name: "w" in: "query" + required: true description: "Width of the TTY session in characters" type: "integer" tags: ["Exec"] diff --git a/_vendor/github.com/moby/moby/docs/api/v1.39.yaml b/_vendor/github.com/moby/moby/docs/api/v1.39.yaml index 2c7021c02bc..297cec305b9 100644 --- a/_vendor/github.com/moby/moby/docs/api/v1.39.yaml +++ b/_vendor/github.com/moby/moby/docs/api/v1.39.yaml @@ -6654,10 +6654,12 @@ paths: type: "string" - name: "h" in: "query" + required: true description: "Height of the TTY session in characters" type: "integer" - name: "w" in: "query" + required: true description: "Width of the TTY session in characters" type: "integer" tags: ["Container"] @@ -8836,10 +8838,12 @@ paths: type: "string" - name: "h" in: "query" + required: true description: "Height of the TTY session in characters" type: "integer" - name: "w" in: "query" + required: true description: "Width of the TTY session in characters" type: "integer" tags: ["Exec"] diff --git a/_vendor/github.com/moby/moby/docs/api/v1.40.yaml b/_vendor/github.com/moby/moby/docs/api/v1.40.yaml index 15bd011876e..fc2c7c8cf9f 100644 --- a/_vendor/github.com/moby/moby/docs/api/v1.40.yaml +++ b/_vendor/github.com/moby/moby/docs/api/v1.40.yaml @@ -6960,10 +6960,12 @@ paths: type: "string" - name: "h" in: "query" + required: true description: "Height of the TTY session in characters" type: "integer" - name: "w" in: "query" + required: true description: "Width of the TTY session in characters" type: "integer" tags: ["Container"] @@ -9169,10 +9171,12 @@ paths: type: "string" - name: "h" in: "query" + required: true description: "Height of the TTY session in characters" type: "integer" - name: "w" in: "query" + required: true description: "Width of the TTY session in characters" type: "integer" tags: ["Exec"] diff --git a/_vendor/github.com/moby/moby/docs/api/v1.41.yaml b/_vendor/github.com/moby/moby/docs/api/v1.41.yaml index 2dcae1faf8d..54a4c80d246 100644 --- a/_vendor/github.com/moby/moby/docs/api/v1.41.yaml +++ b/_vendor/github.com/moby/moby/docs/api/v1.41.yaml @@ -7249,10 +7249,12 @@ paths: type: "string" - name: "h" in: "query" + required: true description: "Height of the TTY session in characters" type: "integer" - name: "w" in: "query" + required: true description: "Width of the TTY session in characters" type: "integer" tags: ["Container"] @@ -9460,10 +9462,12 @@ paths: type: "string" - name: "h" in: "query" + required: true description: "Height of the TTY session in characters" type: "integer" - name: "w" in: "query" + required: true description: "Width of the TTY session in characters" type: "integer" tags: ["Exec"] diff --git a/_vendor/github.com/moby/moby/docs/api/v1.42.yaml b/_vendor/github.com/moby/moby/docs/api/v1.42.yaml index 80e24f6c4ec..b3745325d2b 100644 --- a/_vendor/github.com/moby/moby/docs/api/v1.42.yaml +++ b/_vendor/github.com/moby/moby/docs/api/v1.42.yaml @@ -7468,10 +7468,12 @@ paths: type: "string" - name: "h" in: "query" + required: true description: "Height of the TTY session in characters" type: "integer" - name: "w" in: "query" + required: true description: "Width of the TTY session in characters" type: "integer" tags: ["Container"] @@ -9779,10 +9781,12 @@ paths: type: "string" - name: "h" in: "query" + required: true description: "Height of the TTY session in characters" type: "integer" - name: "w" in: "query" + required: true description: "Width of the TTY session in characters" type: "integer" tags: ["Exec"] diff --git a/_vendor/github.com/moby/moby/docs/api/v1.43.yaml b/_vendor/github.com/moby/moby/docs/api/v1.43.yaml index e7a3d5d0278..934e77e0548 100644 --- a/_vendor/github.com/moby/moby/docs/api/v1.43.yaml +++ b/_vendor/github.com/moby/moby/docs/api/v1.43.yaml @@ -7486,10 +7486,12 @@ paths: type: "string" - name: "h" in: "query" + required: true description: "Height of the TTY session in characters" type: "integer" - name: "w" in: "query" + required: true description: "Width of the TTY session in characters" type: "integer" tags: ["Container"] @@ -9797,10 +9799,12 @@ paths: type: "string" - name: "h" in: "query" + required: true description: "Height of the TTY session in characters" type: "integer" - name: "w" in: "query" + required: true description: "Width of the TTY session in characters" type: "integer" tags: ["Exec"] diff --git a/_vendor/github.com/moby/moby/docs/api/v1.44.yaml b/_vendor/github.com/moby/moby/docs/api/v1.44.yaml index 019ceb8eb7f..709203bf854 100644 --- a/_vendor/github.com/moby/moby/docs/api/v1.44.yaml +++ b/_vendor/github.com/moby/moby/docs/api/v1.44.yaml @@ -7642,10 +7642,12 @@ paths: type: "string" - name: "h" in: "query" + required: true description: "Height of the TTY session in characters" type: "integer" - name: "w" in: "query" + required: true description: "Width of the TTY session in characters" type: "integer" tags: ["Container"] @@ -9965,10 +9967,12 @@ paths: type: "string" - name: "h" in: "query" + required: true description: "Height of the TTY session in characters" type: "integer" - name: "w" in: "query" + required: true description: "Width of the TTY session in characters" type: "integer" tags: ["Exec"] diff --git a/_vendor/github.com/moby/moby/docs/api/v1.45.yaml b/_vendor/github.com/moby/moby/docs/api/v1.45.yaml index c651bfdd5c8..9aa5c241fd7 100644 --- a/_vendor/github.com/moby/moby/docs/api/v1.45.yaml +++ b/_vendor/github.com/moby/moby/docs/api/v1.45.yaml @@ -7628,10 +7628,12 @@ paths: type: "string" - name: "h" in: "query" + required: true description: "Height of the TTY session in characters" type: "integer" - name: "w" in: "query" + required: true description: "Width of the TTY session in characters" type: "integer" tags: ["Container"] @@ -9945,10 +9947,12 @@ paths: type: "string" - name: "h" in: "query" + required: true description: "Height of the TTY session in characters" type: "integer" - name: "w" in: "query" + required: true description: "Width of the TTY session in characters" type: "integer" tags: ["Exec"] diff --git a/_vendor/github.com/moby/moby/docs/api/v1.46.yaml b/_vendor/github.com/moby/moby/docs/api/v1.46.yaml index 2f714c4ca8d..5945f098f4e 100644 --- a/_vendor/github.com/moby/moby/docs/api/v1.46.yaml +++ b/_vendor/github.com/moby/moby/docs/api/v1.46.yaml @@ -7749,10 +7749,12 @@ paths: type: "string" - name: "h" in: "query" + required: true description: "Height of the TTY session in characters" type: "integer" - name: "w" in: "query" + required: true description: "Width of the TTY session in characters" type: "integer" tags: ["Container"] @@ -9112,6 +9114,19 @@ paths: all tags of the given image that are present in the local image store are pushed. type: "string" + - name: "platform" + type: "string" + in: "query" + description: | + JSON-encoded OCI platform to select the platform-variant to push. + If not provided, all available variants will attempt to be pushed. + + If the daemon provides a multi-platform image store, this selects + the platform-variant to push to the registry. If the image is + a single-platform image, or if the multi-platform image does not + provide a variant matching the given platform, an error is returned. + + Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}` - name: "X-Registry-Auth" in: "header" description: | @@ -9121,11 +9136,6 @@ paths: details. type: "string" required: true - - name: "platform" - in: "query" - description: "Select a platform-specific manifest to be pushed. OCI platform (JSON encoded)" - type: "string" - x-nullable: true tags: ["Image"] /images/{name}/tag: post: @@ -10071,10 +10081,12 @@ paths: type: "string" - name: "h" in: "query" + required: true description: "Height of the TTY session in characters" type: "integer" - name: "w" in: "query" + required: true description: "Width of the TTY session in characters" type: "integer" tags: ["Exec"] diff --git a/_vendor/github.com/moby/moby/docs/api/v1.47.yaml b/_vendor/github.com/moby/moby/docs/api/v1.47.yaml index 7e87be82983..a4b63a1833b 100644 --- a/_vendor/github.com/moby/moby/docs/api/v1.47.yaml +++ b/_vendor/github.com/moby/moby/docs/api/v1.47.yaml @@ -7881,10 +7881,12 @@ paths: type: "string" - name: "h" in: "query" + required: true description: "Height of the TTY session in characters" type: "integer" - name: "w" in: "query" + required: true description: "Width of the TTY session in characters" type: "integer" tags: ["Container"] @@ -9249,6 +9251,19 @@ paths: all tags of the given image that are present in the local image store are pushed. type: "string" + - name: "platform" + type: "string" + in: "query" + description: | + JSON-encoded OCI platform to select the platform-variant to push. + If not provided, all available variants will attempt to be pushed. + + If the daemon provides a multi-platform image store, this selects + the platform-variant to push to the registry. If the image is + a single-platform image, or if the multi-platform image does not + provide a variant matching the given platform, an error is returned. + + Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}` - name: "X-Registry-Auth" in: "header" description: | @@ -9258,11 +9273,6 @@ paths: details. type: "string" required: true - - name: "platform" - in: "query" - description: "Select a platform-specific manifest to be pushed. OCI platform (JSON encoded)" - type: "string" - x-nullable: true tags: ["Image"] /images/{name}/tag: post: @@ -10208,10 +10218,12 @@ paths: type: "string" - name: "h" in: "query" + required: true description: "Height of the TTY session in characters" type: "integer" - name: "w" in: "query" + required: true description: "Width of the TTY session in characters" type: "integer" tags: ["Exec"] diff --git a/_vendor/github.com/moby/moby/docs/api/version-history.md b/_vendor/github.com/moby/moby/docs/api/version-history.md index 88f27bebec2..b9207d4d60b 100644 --- a/_vendor/github.com/moby/moby/docs/api/version-history.md +++ b/_vendor/github.com/moby/moby/docs/api/version-history.md @@ -15,7 +15,7 @@ keywords: "API, Docker, rcli, REST, documentation" ## v1.47 API changes -[Docker Engine API v1.47](https://docs.docker.com/engine/api/v1.47/) documentation +[Docker Engine API v1.47](https://docs.docker.com/reference/api/engine/version/v1.47/) documentation * `GET /images/json` response now includes `Manifests` field, which contains information about the sub-manifests included in the image index. This @@ -27,7 +27,7 @@ keywords: "API, Docker, rcli, REST, documentation" ## v1.46 API changes -[Docker Engine API v1.46](https://docs.docker.com/engine/api/v1.46/) documentation +[Docker Engine API v1.46](https://docs.docker.com/reference/api/engine/version/v1.46/) documentation * `GET /info` now includes a `Containerd` field containing information about the location of the containerd API socket and containerd namespaces used @@ -95,7 +95,7 @@ are not part of the underlying image's Config, and deprecated: ## v1.45 API changes -[Docker Engine API v1.45](https://docs.docker.com/engine/api/v1.45/) documentation +[Docker Engine API v1.45](https://docs.docker.com/reference/api/engine/version/v1.45/) documentation * `POST /containers/create` now supports `VolumeOptions.Subpath` which allows a subpath of a named volume to be mounted. @@ -113,7 +113,7 @@ are not part of the underlying image's Config, and deprecated: ## v1.44 API changes -[Docker Engine API v1.44](https://docs.docker.com/engine/api/v1.44/) documentation +[Docker Engine API v1.44](https://docs.docker.com/reference/api/engine/version/v1.44/) documentation * GET `/images/json` now accepts an `until` filter. This accepts a timestamp and lists all images created before it. The `` can be Unix timestamps, @@ -182,7 +182,7 @@ are not part of the underlying image's Config, and deprecated: ## v1.43 API changes -[Docker Engine API v1.43](https://docs.docker.com/engine/api/v1.43/) documentation +[Docker Engine API v1.43](https://docs.docker.com/reference/api/engine/version/v1.43/) documentation * `POST /containers/create` now accepts `Annotations` as part of `HostConfig`. Can be used to attach arbitrary metadata to the container, which will also be @@ -199,7 +199,7 @@ are not part of the underlying image's Config, and deprecated: ## v1.42 API changes -[Docker Engine API v1.42](https://docs.docker.com/engine/api/v1.42/) documentation +[Docker Engine API v1.42](https://docs.docker.com/reference/api/engine/version/v1.42/) documentation * Removed the `BuilderSize` field on the `GET /system/df` endpoint. This field was introduced in API 1.31 as part of an experimental feature, and no longer @@ -307,7 +307,7 @@ are not part of the underlying image's Config, and deprecated: ## v1.41 API changes -[Docker Engine API v1.41](https://docs.docker.com/engine/api/v1.41/) documentation +[Docker Engine API v1.41](https://docs.docker.com/reference/api/engine/version/v1.41/) documentation * `GET /events` now returns `prune` events after pruning resources have completed. Prune events are returned for `container`, `network`, `volume`, `image`, and @@ -395,7 +395,7 @@ are not part of the underlying image's Config, and deprecated: ## v1.40 API changes -[Docker Engine API v1.40](https://docs.docker.com/engine/api/v1.40/) documentation +[Docker Engine API v1.40](https://docs.docker.com/reference/api/engine/version/v1.40/) documentation * The `/_ping` endpoint can now be accessed both using `GET` or `HEAD` requests. when accessed using a `HEAD` request, all headers are returned, but the body @@ -462,7 +462,7 @@ are not part of the underlying image's Config, and deprecated: ## V1.39 API changes -[Docker Engine API v1.39](https://docs.docker.com/engine/api/v1.39/) documentation +[Docker Engine API v1.39](https://docs.docker.com/reference/api/engine/version/v1.39/) documentation * `GET /info` now returns an empty string, instead of `` for `KernelVersion` and `OperatingSystem` if the daemon was unable to obtain this information. @@ -479,7 +479,7 @@ are not part of the underlying image's Config, and deprecated: ## V1.38 API changes -[Docker Engine API v1.38](https://docs.docker.com/engine/api/v1.38/) documentation +[Docker Engine API v1.38](https://docs.docker.com/reference/api/engine/version/v1.38/) documentation * `GET /tasks` and `GET /tasks/{id}` now return a `NetworkAttachmentSpec` field, @@ -488,7 +488,7 @@ are not part of the underlying image's Config, and deprecated: ## v1.37 API changes -[Docker Engine API v1.37](https://docs.docker.com/engine/api/v1.37/) documentation +[Docker Engine API v1.37](https://docs.docker.com/reference/api/engine/version/v1.37/) documentation * `POST /containers/create` and `POST /services/create` now supports exposing SCTP ports. * `POST /configs/create` and `POST /configs/{id}/create` now accept a `Templating` driver. @@ -498,14 +498,14 @@ are not part of the underlying image's Config, and deprecated: ## v1.36 API changes -[Docker Engine API v1.36](https://docs.docker.com/engine/api/v1.36/) documentation +[Docker Engine API v1.36](https://docs.docker.com/reference/api/engine/version/v1.36/) documentation * `Get /events` now return `exec_die` event when an exec process terminates. ## v1.35 API changes -[Docker Engine API v1.35](https://docs.docker.com/engine/api/v1.35/) documentation +[Docker Engine API v1.35](https://docs.docker.com/reference/api/engine/version/v1.35/) documentation * `POST /services/create` and `POST /services/(id)/update` now accepts an `Isolation` field on container spec to set the Isolation technology of the @@ -528,7 +528,7 @@ are not part of the underlying image's Config, and deprecated: ## v1.34 API changes -[Docker Engine API v1.34](https://docs.docker.com/engine/api/v1.34/) documentation +[Docker Engine API v1.34](https://docs.docker.com/reference/api/engine/version/v1.34/) documentation * `POST /containers/(name)/wait?condition=removed` now also also returns in case of container removal failure. A pointer to a structure named @@ -539,14 +539,14 @@ are not part of the underlying image's Config, and deprecated: ## v1.33 API changes -[Docker Engine API v1.33](https://docs.docker.com/engine/api/v1.33/) documentation +[Docker Engine API v1.33](https://docs.docker.com/reference/api/engine/version/v1.33/) documentation * `GET /events` now supports filtering 4 more kinds of events: `config`, `node`, `secret` and `service`. ## v1.32 API changes -[Docker Engine API v1.32](https://docs.docker.com/engine/api/v1.32/) documentation +[Docker Engine API v1.32](https://docs.docker.com/reference/api/engine/version/v1.32/) documentation * `POST /images/create` now accepts a `platform` parameter in the form of `os[/arch[/variant]]`. * `POST /containers/create` now accepts additional values for the @@ -560,7 +560,7 @@ are not part of the underlying image's Config, and deprecated: ## v1.31 API changes -[Docker Engine API v1.31](https://docs.docker.com/engine/api/v1.31/) documentation +[Docker Engine API v1.31](https://docs.docker.com/reference/api/engine/version/v1.31/) documentation * `DELETE /secrets/(name)` now returns status code 404 instead of 500 when the secret does not exist. * `POST /secrets/create` now returns status code 409 instead of 500 when creating an already existing secret. @@ -591,7 +591,7 @@ are not part of the underlying image's Config, and deprecated: ## v1.30 API changes -[Docker Engine API v1.30](https://docs.docker.com/engine/api/v1.30/) documentation +[Docker Engine API v1.30](https://docs.docker.com/reference/api/engine/version/v1.30/) documentation * `GET /info` now returns the list of supported logging drivers, including plugins. * `GET /info` and `GET /swarm` now returns the cluster-wide swarm CA info if the node is in a swarm: the cluster root CA certificate, and the cluster TLS @@ -614,7 +614,7 @@ are not part of the underlying image's Config, and deprecated: ## v1.29 API changes -[Docker Engine API v1.29](https://docs.docker.com/engine/api/v1.29/) documentation +[Docker Engine API v1.29](https://docs.docker.com/reference/api/engine/version/v1.29/) documentation * `DELETE /networks/(name)` now allows to remove the ingress network, the one used to provide the routing-mesh. * `POST /networks/create` now supports creating the ingress network, by specifying an `Ingress` boolean field. As of now this is supported only when using the overlay network driver. @@ -628,7 +628,7 @@ are not part of the underlying image's Config, and deprecated: ## v1.28 API changes -[Docker Engine API v1.28](https://docs.docker.com/engine/api/v1.28/) documentation +[Docker Engine API v1.28](https://docs.docker.com/reference/api/engine/version/v1.28/) documentation * `POST /containers/create` now includes a `Consistency` field to specify the consistency level for each `Mount`, with possible values `default`, `consistent`, `cached`, or `delegated`. * `GET /containers/create` now takes a `DeviceCgroupRules` field in `HostConfig` allowing to set custom device cgroup rules for the created container. @@ -646,19 +646,19 @@ are not part of the underlying image's Config, and deprecated: ## v1.27 API changes -[Docker Engine API v1.27](https://docs.docker.com/engine/api/v1.27/) documentation +[Docker Engine API v1.27](https://docs.docker.com/reference/api/engine/version/v1.27/) documentation * `GET /containers/(id or name)/stats` now includes an `online_cpus` field in both `precpu_stats` and `cpu_stats`. If this field is `nil` then for compatibility with older daemons the length of the corresponding `cpu_usage.percpu_usage` array should be used. ## v1.26 API changes -[Docker Engine API v1.26](https://docs.docker.com/engine/api/v1.26/) documentation +[Docker Engine API v1.26](https://docs.docker.com/reference/api/engine/version/v1.26/) documentation * `POST /plugins/(plugin name)/upgrade` upgrade a plugin. ## v1.25 API changes -[Docker Engine API v1.25](https://docs.docker.com/engine/api/v1.25/) documentation +[Docker Engine API v1.25](https://docs.docker.com/reference/api/engine/version/v1.25/) documentation * The API version is now required in all API calls. Instead of just requesting, for example, the URL `/containers/json`, you must now request `/v1.25/containers/json`. * `GET /version` now returns `MinAPIVersion`. diff --git a/_vendor/modules.txt b/_vendor/modules.txt index 5460f41e440..77efffc0e10 100644 --- a/_vendor/modules.txt +++ b/_vendor/modules.txt @@ -1,6 +1,6 @@ -# github.com/moby/moby v27.3.1+incompatible -# github.com/moby/buildkit v0.16.0 -# github.com/docker/buildx v0.17.1 -# github.com/docker/cli v27.3.2-0.20241008150905-cb3048fbebb1+incompatible -# github.com/docker/compose/v2 v2.30.1 -# github.com/docker/scout-cli v1.13.0 +# github.com/moby/moby v27.4.0+incompatible +# github.com/moby/buildkit v0.18.0 +# github.com/docker/buildx v0.19.2 +# github.com/docker/cli v27.4.0+incompatible +# github.com/docker/compose/v2 v2.32.0 +# github.com/docker/scout-cli v1.15.0 diff --git a/content/_index.md b/content/_index.md index 145635be974..5561dc158f3 100644 --- a/content/_index.md +++ b/content/_index.md @@ -80,17 +80,6 @@ grid: url: "/scout/quickstart/" - text: "Image analysis" url: "/scout/image-analysis/" - - title: Trusted content - icon: verified - description: | - High-quality, secure images from Docker and verified partners. - links: - - text: "Overview" - url: "/trusted-content/" - - text: "Official images" - url: "/trusted-content/official-images/" - - text: "Verified publisher program" - url: "/trusted-content/dvp-program/" - title: Subscription icon: card_membership description: | @@ -99,9 +88,9 @@ grid: - text: "Overview" url: "/subscription/" - text: "Subscriptions and features" - url: "/subscription/core-subscription/details/" - - text: "Upgrade" - url: "/subscription/core-subscription/upgrade/" + url: "/subscription/details/" + - text: "Change subscription" + url: "/subscription/change/" - title: Billing icon: payments description: | @@ -110,9 +99,9 @@ grid: - text: "Overview" url: "/billing/" - text: "Update payment method" - url: "/billing/core-billing/payment-method/" + url: "/billing/payment-method/" - text: "View billing history" - url: "/billing/core-billing/history/" + url: "/billing/history/" - title: Administration icon: admin_panel_settings description: | @@ -135,7 +124,7 @@ grid: url: "/security/for-admins/single-sign-on/" - text: "SCIM" url: "/security/for-admins/provisioning/scim/" - - title: Testcontainers cloud + - title: Testcontainers Cloud icon: cloud description: | Testcontainers Cloud lets you run heavy test workloads remotely. diff --git a/content/get-started/docker-concepts/building-images/multi-stage-builds.md b/content/get-started/docker-concepts/building-images/multi-stage-builds.md index e018690ff96..0de903ee206 100644 --- a/content/get-started/docker-concepts/building-images/multi-stage-builds.md +++ b/content/get-started/docker-concepts/building-images/multi-stage-builds.md @@ -57,9 +57,8 @@ In this hands-on guide, you'll unlock the power of multi-stage builds to create 1. [Download and install](https://www.docker.com/products/docker-desktop/) Docker Desktop. -2. [Download and install](https://www.oracle.com/java/technologies/downloads/) Java. -3. Open this [pre-initialized project](https://start.spring.io/#!type=maven-project&language=java&platformVersion=3.4.0-M3&packaging=jar&jvmVersion=21&groupId=com.example&artifactId=spring-boot-docker&name=spring-boot-docker&description=Demo%20project%20for%20Spring%20Boot&packageName=com.example.spring-boot-docker&dependencies=web) to generate a ZIP file. Here’s how that looks: +2. Open this [pre-initialized project](https://start.spring.io/#!type=maven-project&language=java&platformVersion=3.4.0-M3&packaging=jar&jvmVersion=21&groupId=com.example&artifactId=spring-boot-docker&name=spring-boot-docker&description=Demo%20project%20for%20Spring%20Boot&packageName=com.example.spring-boot-docker&dependencies=web) to generate a ZIP file. Here’s how that looks: ![A screenshot of Spring Initializr tool selected with Java 21, Spring Web and Spring Boot 3.4.0](images/multi-stage-builds-spring-initializer.webp?border=true) @@ -72,7 +71,7 @@ In this hands-on guide, you'll unlock the power of multi-stage builds to create For this demonstration, you’ve paired Maven build automation with Java, a Spring Web dependency, and Java 21 for your metadata. -4. Navigate the project directory. Once you unzip the file, you'll see the following project directory structure: +3. Navigate the project directory. Once you unzip the file, you'll see the following project directory structure: ```plaintext @@ -109,7 +108,7 @@ In this hands-on guide, you'll unlock the power of multi-stage builds to create contains most of the information needed to build a customized project. The POM is huge and can seem daunting. Thankfully, you don't yet need to understand every intricacy to use it effectively. -5. Create a RESTful web service that displays "Hello World!". +4. Create a RESTful web service that displays "Hello World!". Under the `src/main/java/com/example/spring_boot_docker/` directory, you can modify your @@ -232,7 +231,7 @@ Now that you have the project, you’re ready to create the `Dockerfile`. 1. Now that you have an image built, it's time to run the container. ```console - $ docker run -d -p 8080:8080 spring-helloworld + $ docker run -p 8080:8080 spring-helloworld ``` You'll then see output similar to the following in the container log: diff --git a/content/get-started/docker-concepts/running-containers/sharing-local-files.md b/content/get-started/docker-concepts/running-containers/sharing-local-files.md index 844a4cc4155..d8dacb66fcc 100644 --- a/content/get-started/docker-concepts/running-containers/sharing-local-files.md +++ b/content/get-started/docker-concepts/running-containers/sharing-local-files.md @@ -61,7 +61,7 @@ Read-only bind mounts let the container access the mounted files on the host for > **Synchronized File Share** > -> As your codebase grows larger, traditional methods of file sharing like bind mounts may become inefficient or slow, especially in development environments where frequent access to files is necessary. [Synchronized file shares](/desktop/synchronized-file-sharing/) improve bind mount performance by leveraging synchronized filesystem caches. This optimization ensures that file access between the host and virtual machine (VM) is fast and efficient. +> As your codebase grows larger, traditional methods of file sharing like bind mounts may become inefficient or slow, especially in development environments where frequent access to files is necessary. [Synchronized file shares](/manuals/desktop/features/synchronized-file-sharing.md) improve bind mount performance by leveraging synchronized filesystem caches. This optimization ensures that file access between the host and virtual machine (VM) is fast and efficient. ## Try it out diff --git a/content/get-started/docker-concepts/the-basics/what-is-a-registry.md b/content/get-started/docker-concepts/the-basics/what-is-a-registry.md index 8d61803fd48..f8731fdb563 100644 --- a/content/get-started/docker-concepts/the-basics/what-is-a-registry.md +++ b/content/get-started/docker-concepts/the-basics/what-is-a-registry.md @@ -52,7 +52,7 @@ The following diagram shows the relationship between a registry, repositories, a +---------------------------------------+ ``` ->**Note** +> [!NOTE] > > You can create one private repository and unlimited public repositories using the free version of Docker Hub. For more information, visit the [Docker Hub subscription page](https://www.docker.com/pricing/). @@ -112,7 +112,7 @@ Don't worry about the specifics of the Dockerfile, as you'll learn about that in docker build -t /docker-quickstart . ``` - >**Note** + > [!NOTE] > > Make sure you include the dot (.) at the end of the `docker build` command. This tells Docker where to find the Dockerfile. diff --git a/content/get-started/docker-concepts/the-basics/what-is-an-image.md b/content/get-started/docker-concepts/the-basics/what-is-an-image.md index fb31b9efb79..c3702a4c5fe 100644 --- a/content/get-started/docker-concepts/the-basics/what-is-an-image.md +++ b/content/get-started/docker-concepts/the-basics/what-is-an-image.md @@ -3,19 +3,18 @@ title: What is an image? weight: 20 keywords: concepts, build, images, container, docker desktop description: What is an image -aliases: - - /guides/docker-concepts/the-basics/what-is-an-image/ +aliases: + - /guides/docker-concepts/the-basics/what-is-an-image/ + - /get-started/run-docker-hub-images/ --- {{< youtube-embed NyvT9REqLe4 >}} ## Explanation -Seeing a [container](./what-is-a-container) is an isolated process, where does it get its files and configuration? How do you share those environments? +Seeing a [container](./what-is-a-container.md) is an isolated process, where does it get its files and configuration? How do you share those environments? -That's where container images come in! - -A container image is a standardized package that includes all of the files, binaries, libraries, and configurations to run a container. +That's where container images come in. A container image is a standardized package that includes all of the files, binaries, libraries, and configurations to run a container. For a [PostgreSQL](https://hub.docker.com/_/postgres) image, that image will package the database binaries, config files, and other dependencies. For a Python web app, it'll include the Python runtime, your app code, and all of its dependencies. @@ -23,7 +22,7 @@ There are two important principles of images: 1. Images are immutable. Once an image is created, it can't be modified. You can only make a new image or add changes on top of it. -2. Container images are composed of layers. Each layer represented a set of file system changes that add, remove, or modify files. +2. Container images are composed of layers. Each layer represents a set of file system changes that add, remove, or modify files. These two principles let you to extend or add to existing images. For example, if you are building a Python app, you can start from the [Python image](https://hub.docker.com/_/python) and add additional layers to install your app's dependencies and add your code. This lets you focus on your app, rather than Python itself. @@ -50,19 +49,18 @@ In this hands-on, you will learn how to search and pull a container image using 1. Open the Docker Desktop Dashboard and select the **Images** view in the left-hand navigation menu. - ![A screenshot of the Docker Desktop Dashboard showing the image view on the left sidebar](images/click-image.webp?border=true&w=1050&h=400) + ![A screenshot of the Docker Desktop Dashboard showing the image view on the left sidebar](images/click-image.webp?border=true&w=1050&h=400) 2. Select the **Search images to run** button. If you don't see it, select the _global search bar_ at the top of the screen. - ![A screenshot of the Docker Desktop Dashboard showing the search ta](images/search-image.webp?border) + ![A screenshot of the Docker Desktop Dashboard showing the search ta](images/search-image.webp?border) 3. In the **Search** field, enter "welcome-to-docker". Once the search has completed, select the `docker/welcome-to-docker` image. - ![A screenshot of the Docker Desktop Dashboard showing the search results for the docker/welcome-to-docker image](images/select-image.webp?border=true&w=1050&h=400) + ![A screenshot of the Docker Desktop Dashboard showing the search results for the docker/welcome-to-docker image](images/select-image.webp?border=true&w=1050&h=400) 4. Select **Pull** to download the image. - ### Learn about the image Once you have an image downloaded, you can learn quite a few details about the image either through the GUI or the CLI. @@ -71,13 +69,11 @@ Once you have an image downloaded, you can learn quite a few details about the i 2. Select the **docker/welcome-to-docker** image to open details about the image. - ![A screenshot of the Docker Desktop Dashboard showing the images view with an arrow pointing to the docker/welcome-to-docker image](images/pulled-image.webp?border=true&w=1050&h=400) + ![A screenshot of the Docker Desktop Dashboard showing the images view with an arrow pointing to the docker/welcome-to-docker image](images/pulled-image.webp?border=true&w=1050&h=400) 3. The image details page presents you with information regarding the layers of the image, the packages and libraries installed in the image, and any discovered vulnerabilities. - ![A screenshot of the image details view for the docker/welcome-to-docker image](images/image-layers.webp?border=true&w=1050&h=400) - - + ![A screenshot of the image details view for the docker/welcome-to-docker image](images/image-layers.webp?border=true&w=1050&h=400) {{< /tab >}} @@ -87,103 +83,101 @@ Follow the instructions to search and pull a Docker image using CLI to view its ### Search for and download an image -1. Open a terminal and search for images using the [`docker search`](/reference/cli/docker/search/) command: - - ```console - docker search docker/welcome-to-docker - ``` +1. Open a terminal and search for images using the [`docker search`](/reference/cli/docker/search.md) command: - You will see output like the following: + ```console + docker search docker/welcome-to-docker + ``` - ```console - NAME DESCRIPTION STARS OFFICIAL - docker/welcome-to-docker Docker image for new users getting started w… 20 - ``` + You will see output like the following: - This output shows you information about relevant images available on Docker Hub. + ```console + NAME DESCRIPTION STARS OFFICIAL + docker/welcome-to-docker Docker image for new users getting started w… 20 + ``` -2. Pull the image using the [`docker pull`](/reference/cli/docker/image/pull/) command. + This output shows you information about relevant images available on Docker Hub. - ```console - docker pull docker/welcome-to-docker - ``` +2. Pull the image using the [`docker pull`](/reference/cli/docker/image/pull.md) command. - You will see output like the following: + ```console + docker pull docker/welcome-to-docker + ``` - ```console - Using default tag: latest - latest: Pulling from docker/welcome-to-docker - 579b34f0a95b: Download complete - d11a451e6399: Download complete - 1c2214f9937c: Download complete - b42a2f288f4d: Download complete - 54b19e12c655: Download complete - 1fb28e078240: Download complete - 94be7e780731: Download complete - 89578ce72c35: Download complete - Digest: sha256:eedaff45e3c78538087bdd9dc7afafac7e110061bbdd836af4104b10f10ab693 - Status: Downloaded newer image for docker/welcome-to-docker:latest - docker.io/docker/welcome-to-docker:latest - ``` + You will see output like the following: - Each of line represents a different downloaded layer of the image. Remember that each layer is a set of filesystem changes and provides functionality of the image. + ```console + Using default tag: latest + latest: Pulling from docker/welcome-to-docker + 579b34f0a95b: Download complete + d11a451e6399: Download complete + 1c2214f9937c: Download complete + b42a2f288f4d: Download complete + 54b19e12c655: Download complete + 1fb28e078240: Download complete + 94be7e780731: Download complete + 89578ce72c35: Download complete + Digest: sha256:eedaff45e3c78538087bdd9dc7afafac7e110061bbdd836af4104b10f10ab693 + Status: Downloaded newer image for docker/welcome-to-docker:latest + docker.io/docker/welcome-to-docker:latest + ``` + Each of line represents a different downloaded layer of the image. Remember that each layer is a set of filesystem changes and provides functionality of the image. ### Learn about the image -1. List your downloaded images using the [`docker image ls`](/reference/cli/docker/image/ls/) command: - - ```console - docker image ls - ``` +1. List your downloaded images using the [`docker image ls`](/reference/cli/docker/image/ls.md) command: - You will see output like the following: + ```console + docker image ls + ``` - ```console - REPOSITORY TAG IMAGE ID CREATED SIZE - docker/welcome-to-docker latest eedaff45e3c7 4 months ago 29.7MB - ``` + You will see output like the following: - The command shows a list of Docker images currently available on your system. The `docker/welcome-to-docker` has a total size of approximately 29.7MB. + ```console + REPOSITORY TAG IMAGE ID CREATED SIZE + docker/welcome-to-docker latest eedaff45e3c7 4 months ago 29.7MB + ``` - > **Image size** - > - > The image size represented here reflects the uncompressed size of the image, not the download size of the layers. + The command shows a list of Docker images currently available on your system. The `docker/welcome-to-docker` has a total size of approximately 29.7MB. -2. List the image's layers using the [`docker image history`](/reference/cli/docker/image/history/) command: + > **Image size** + > + > The image size represented here reflects the uncompressed size of the image, not the download size of the layers. - ```console - docker image history docker/welcome-to-docker - ``` +2. List the image's layers using the [`docker image history`](/reference/cli/docker/image/history.md) command: - You will see output like the following: + ```console + docker image history docker/welcome-to-docker + ``` - ```console - IMAGE CREATED CREATED BY SIZE COMMENT - 648f93a1ba7d 4 months ago COPY /app/build /usr/share/nginx/html # buil… 1.6MB buildkit.dockerfile.v0 - 5 months ago /bin/sh -c #(nop) CMD ["nginx" "-g" "daemon… 0B - 5 months ago /bin/sh -c #(nop) STOPSIGNAL SIGQUIT 0B - 5 months ago /bin/sh -c #(nop) EXPOSE 80 0B - 5 months ago /bin/sh -c #(nop) ENTRYPOINT ["/docker-entr… 0B - 5 months ago /bin/sh -c #(nop) COPY file:9e3b2b63db9f8fc7… 4.62kB - 5 months ago /bin/sh -c #(nop) COPY file:57846632accc8975… 3.02kB - 5 months ago /bin/sh -c #(nop) COPY file:3b1b9915b7dd898a… 298B - 5 months ago /bin/sh -c #(nop) COPY file:caec368f5a54f70a… 2.12kB - 5 months ago /bin/sh -c #(nop) COPY file:01e75c6dd0ce317d… 1.62kB - 5 months ago /bin/sh -c set -x && addgroup -g 101 -S … 9.7MB - 5 months ago /bin/sh -c #(nop) ENV PKG_RELEASE=1 0B - 5 months ago /bin/sh -c #(nop) ENV NGINX_VERSION=1.25.3 0B - 5 months ago /bin/sh -c #(nop) LABEL maintainer=NGINX Do… 0B - 5 months ago /bin/sh -c #(nop) CMD ["/bin/sh"] 0B - 5 months ago /bin/sh -c #(nop) ADD file:ff3112828967e8004… 7.66MB - ``` + You will see output like the following: - This output shows you all of the layers, their sizes, and the command used to create the layer. + ```console + IMAGE CREATED CREATED BY SIZE COMMENT + 648f93a1ba7d 4 months ago COPY /app/build /usr/share/nginx/html # buil… 1.6MB buildkit.dockerfile.v0 + 5 months ago /bin/sh -c #(nop) CMD ["nginx" "-g" "daemon… 0B + 5 months ago /bin/sh -c #(nop) STOPSIGNAL SIGQUIT 0B + 5 months ago /bin/sh -c #(nop) EXPOSE 80 0B + 5 months ago /bin/sh -c #(nop) ENTRYPOINT ["/docker-entr… 0B + 5 months ago /bin/sh -c #(nop) COPY file:9e3b2b63db9f8fc7… 4.62kB + 5 months ago /bin/sh -c #(nop) COPY file:57846632accc8975… 3.02kB + 5 months ago /bin/sh -c #(nop) COPY file:3b1b9915b7dd898a… 298B + 5 months ago /bin/sh -c #(nop) COPY file:caec368f5a54f70a… 2.12kB + 5 months ago /bin/sh -c #(nop) COPY file:01e75c6dd0ce317d… 1.62kB + 5 months ago /bin/sh -c set -x && addgroup -g 101 -S … 9.7MB + 5 months ago /bin/sh -c #(nop) ENV PKG_RELEASE=1 0B + 5 months ago /bin/sh -c #(nop) ENV NGINX_VERSION=1.25.3 0B + 5 months ago /bin/sh -c #(nop) LABEL maintainer=NGINX Do… 0B + 5 months ago /bin/sh -c #(nop) CMD ["/bin/sh"] 0B + 5 months ago /bin/sh -c #(nop) ADD file:ff3112828967e8004… 7.66MB + ``` - > **Viewing the full command** - > - > If you add the `--no-trunc` flag to the command, you will see the full command. Note that, since the output is in a table-like format, longer commands will cause the output to be very difficult to navigate. + This output shows you all of the layers, their sizes, and the command used to create the layer. + > **Viewing the full command** + > + > If you add the `--no-trunc` flag to the command, you will see the full command. Note that, since the output is in a table-like format, longer commands will cause the output to be very difficult to navigate. {{< /tab >}} {{< /tabs >}} @@ -194,12 +188,9 @@ In this walkthrough, you searched and pulled a Docker image. In addition to pull The following resources will help you learn more about exploring, finding, and building images: -- [Docker Trusted Content](/trusted-content/) - - [Docker Official Images docs](/trusted-content/official-images/) - - [Docker Verified Publisher docs](/trusted-content/dvp-program/) - - [Docker-Sponsored Open Source Program docs](/trusted-content/dsos-program/) -- [Explore the Image view in Docker Desktop](/desktop/use-desktop/images/) -- [Packaging your software](/build/building/packaging/) +- [Docker trusted content](/manuals/docker-hub/image-library/trusted-content.md) +- [Explore the Image view in Docker Desktop](/manuals/desktop/use-desktop/images.md) +- [Docker Build overview](/manuals/build/concepts/overview.md) - [Docker Hub](https://hub.docker.com) ## Next steps diff --git a/content/get-started/get-docker.md b/content/get-started/get-docker.md index 321ea0dff90..17217e7654f 100644 --- a/content/get-started/get-docker.md +++ b/content/get-started/get-docker.md @@ -34,7 +34,7 @@ section and choose the best installation path for you. {{< card title="Docker Desktop for Mac" description="A native application using the macOS sandbox security model that delivers all Docker tools to your Mac." - link="/desktop/install/mac-install/" + link="/desktop/setup/install/mac-install/" icon="/assets/images/apple_48.svg" >}}
@@ -42,7 +42,7 @@ section and choose the best installation path for you. {{< card title="Docker Desktop for Windows" description="A native Windows application that delivers all Docker tools to your Windows computer." - link="/desktop/install/windows-install/" + link="/desktop/setup/install/windows-install/" icon="/assets/images/windows_48.svg" >}}
@@ -50,7 +50,7 @@ section and choose the best installation path for you. {{< card title="Docker Desktop for Linux" description="A native Linux application that delivers all Docker tools to your Linux computer." - link="/desktop/install/linux/" + link="/desktop/setup/install/linux/" icon="/assets/images/linux_48.svg" >}} > [!NOTE] diff --git a/content/get-started/introduction/build-and-push-first-image.md b/content/get-started/introduction/build-and-push-first-image.md index ce507efa716..69af604c805 100644 --- a/content/get-started/introduction/build-and-push-first-image.md +++ b/content/get-started/introduction/build-and-push-first-image.md @@ -33,7 +33,7 @@ If you’re new to container images, think of them as a standardized package tha To share your Docker images, you need a place to store them. This is where registries come in. While there are many registries, Docker Hub is the default and go-to registry for images. Docker Hub provides both a place for you to store your own images and to find images from others to either run or use as the bases for your own images. -In [Develop with containers](develop-with-containers.md), you used the following images that came from Docker Hub, each of which are [Docker Official Images](/trusted-content/official-images/): +In [Develop with containers](develop-with-containers.md), you used the following images that came from Docker Hub, each of which are [Docker Official Images](/manuals/docker-hub/image-library/trusted-content.md#docker-official-images): - [node](https://hub.docker.com/_/node) - provides a Node environment and is used as the base of your development efforts. This image is also used as the base for the final application image. - [mysql](https://hub.docker.com/_/mysql) - provides a MySQL database to store the to-do list items diff --git a/content/get-started/introduction/get-docker-desktop.md b/content/get-started/introduction/get-docker-desktop.md index eb796ff0fb4..123c0ef1cef 100644 --- a/content/get-started/introduction/get-docker-desktop.md +++ b/content/get-started/introduction/get-docker-desktop.md @@ -28,21 +28,21 @@ This guide will walk you through the installation process, enabling you to exper {{< card title="Docker Desktop for Mac" - description="[Download (Apple Silicon)](https://desktop.docker.com/mac/main/arm64/Docker.dmg?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-mac-arm64) | [Download (Intel)](https://desktop.docker.com/mac/main/amd64/Docker.dmg?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-mac-amd64) | [Install instructions](/desktop/install/mac-install)" + description="[Download (Apple Silicon)](https://desktop.docker.com/mac/main/arm64/Docker.dmg?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-mac-arm64) | [Download (Intel)](https://desktop.docker.com/mac/main/amd64/Docker.dmg?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-mac-amd64) | [Install instructions](/desktop/setup/install/mac-install)" icon="/assets/images/apple_48.svg" >}}
{{< card title="Docker Desktop for Windows" - description="[Download](https://desktop.docker.com/win/main/amd64/Docker%20Desktop%20Installer.exe?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-windows) | [Install instructions](/desktop/install/windows-install)" + description="[Download](https://desktop.docker.com/win/main/amd64/Docker%20Desktop%20Installer.exe?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-windows) | [Install instructions](/desktop/setup/install/windows-install)" icon="/assets/images/windows_48.svg" >}}
{{< card title="Docker Desktop for Linux" - description="[Install instructions](/desktop/install/linux/)" + description="[Install instructions](/desktop/setup/install/linux/)" icon="/assets/images/linux_48.svg" >}} Once it's installed, complete the setup process and you're all set to run a Docker container. diff --git a/content/get-started/workshop/02_our_app.md b/content/get-started/workshop/02_our_app.md index 0d01ca1744b..9d05ba5fc11 100644 --- a/content/get-started/workshop/02_our_app.md +++ b/content/get-started/workshop/02_our_app.md @@ -2,15 +2,17 @@ title: Containerize an application weight: 20 linkTitle: "Part 1: Containerize an application" -keywords: dockerfile example, Containerize an application, run docker file, running +keywords: | + dockerfile example, Containerize an application, run docker file, running docker file, how to run dockerfile, example dockerfile, how to create a docker container, create dockerfile, simple dockerfile, creating containers -description: Follow this step-by-step guide to learn how to create and run a containerized +description: | + Follow this step-by-step guide to learn how to create and run a containerized application using Docker aliases: - - /get-started/part2/ - - /get-started/02_our_app/ - - /guides/workshop/02_our_app/ + - /get-started/part2/ + - /get-started/02_our_app/ + - /guides/workshop/02_our_app/ --- For the rest of this guide, you'll be working with a simple todo @@ -49,68 +51,13 @@ Before you can run the application, you need to get the application source code To build the image, you'll need to use a Dockerfile. A Dockerfile is simply a text-based file with no file extension that contains a script of instructions. Docker uses this script to build a container image. -1. In the `getting-started-app` directory, the same location as the `package.json` file, create a file named `Dockerfile`. You can use the following commands to create a Dockerfile based on your operating system. - - {{< tabs >}} - {{< tab name="Mac / Linux / Windows (Git Bash)" >}} - - In the terminal, run the following commands. - - Make sure you're in the `getting-started-app` directory. Replace `/path/to/getting-started-app` with the path to your `getting-started-app` directory. - - ```console - $ cd /path/to/getting-started-app - ``` - - Create an empty file named `Dockerfile`. - - ```console - $ touch Dockerfile - ``` - - {{< /tab >}} - {{< tab name="Windows (Command Prompt)" >}} - - In the Windows Command Prompt, run the following commands. - - Make sure you're in the `getting-started-app` directory. Replace `\path\to\getting-started-app` with the path to your `getting-started-app` directory. - - ```console - $ cd \path\to\getting-started-app - ``` - - Create an empty file named `Dockerfile`. - - ```console - $ type nul > Dockerfile - ``` - - {{< /tab >}} - {{< tab name="Windows (PowerShell)" >}} - - In PowerShell, run the following commands. - - Make sure you're in the `getting-started-app` directory. Replace `\path\to\getting-started-app` with the path to your `getting-started-app` directory. - - ```console - $ cd \path\to\getting-started-app - ``` - - Create an empty file named `Dockerfile`. - - ```powershell - $ New-Item -Path . -Name Dockerfile -ItemType File - ``` - - {{< /tab >}} - {{< /tabs >}} - -2. Using a text editor or code editor, add the following contents to the Dockerfile: +1. In the `getting-started-app` directory, the same location as the + `package.json` file, create a file named `Dockerfile` with the following contents: ```dockerfile # syntax=docker/dockerfile:1 - - FROM node:18-alpine + + FROM node:lts-alpine WORKDIR /app COPY . . RUN yarn install --production @@ -118,7 +65,12 @@ To build the image, you'll need to use a Dockerfile. A Dockerfile is simply a te EXPOSE 3000 ``` -3. Build the image using the following commands: + This Dockerfile starts off with a `node:lts-alpine` base image, a + light-weight Linux image that comes with Node.js and the Yarn package + manager pre-installed. It copies all of the source code into the image, + installs the necessary dependencies, and starts the application. + +2. Build the image using the following commands: In the terminal, make sure you're in the `getting-started-app` directory. Replace `/path/to/getting-started-app` with the path to your `getting-started-app` directory. @@ -127,11 +79,12 @@ To build the image, you'll need to use a Dockerfile. A Dockerfile is simply a te ``` Build the image. + ```console $ docker build -t getting-started . ``` - The `docker build` command uses the Dockerfile to build a new image. You might have noticed that Docker downloaded a lot of "layers". This is because you instructed the builder that you wanted to start from the `node:18-alpine` image. But, since you didn't have that on your machine, Docker needed to download the image. + The `docker build` command uses the Dockerfile to build a new image. You might have noticed that Docker downloaded a lot of "layers". This is because you instructed the builder that you wanted to start from the `node:lts-alpine` image. But, since you didn't have that on your machine, Docker needed to download the image. After Docker downloaded the image, the instructions from the Dockerfile copied in your application and used `yarn` to install your application's dependencies. The `CMD` directive specifies the default command to run when starting a container from this image. @@ -146,30 +99,27 @@ Now that you have an image, you can run the application in a container using the 1. Run your container using the `docker run` command and specify the name of the image you just created: ```console - $ docker run -dp 127.0.0.1:3000:3000 getting-started + $ docker run -d -p 127.0.0.1:3000:3000 getting-started ``` The `-d` flag (short for `--detach`) runs the container in the background. This means that Docker starts your container and returns you to the terminal - prompt. You can verify that a container is running by viewing it in Docker - Dashboard under **Containers**, or by running `docker ps` in the terminal. + prompt. Also, it does not display logs in the terminal. - The `-p` flag (short for `--publish`) creates a port mapping between the host - and the container. The `-p` flag takes a string value in the format of - `HOST:CONTAINER`, where `HOST` is the address on the host, and `CONTAINER` is - the port on the container. The command publishes the container's port 3000 to - `127.0.0.1:3000` (`localhost:3000`) on the host. Without the port mapping, - you wouldn't be able to access the application from the host. + The `-p` flag (short for `--publish`) creates a port mapping between the + host and the container. The `-p` flag takes a string value in the format of + `HOST:CONTAINER`, where `HOST` is the address on the host, and `CONTAINER` + is the port on the container. The command publishes the container's port + 3000 to `127.0.0.1:3000` (`localhost:3000`) on the host. Without the port + mapping, you wouldn't be able to access the application from the host. 2. After a few seconds, open your web browser to [http://localhost:3000](http://localhost:3000). You should see your app. ![Empty todo list](images/todo-list-empty.webp) - 3. Add an item or two and see that it works as you expect. You can mark items as complete and remove them. Your frontend is successfully storing items in the backend. - At this point, you have a running todo list manager with a few items. If you take a quick look at your containers, you should see at least one container running that's using the `getting-started` image and on port `3000`. To see your containers, you can use the CLI or Docker Desktop's graphical interface. @@ -177,12 +127,14 @@ If you take a quick look at your containers, you should see at least one contain {{< tabs >}} {{< tab name="CLI" >}} -Run the following `docker ps` command in a terminal to list your containers. +Run the `docker ps` command in a terminal to list your containers. ```console $ docker ps ``` + Output similar to the following should appear. + ```console CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES df784548666d getting-started "docker-entrypoint.s…" 2 minutes ago Up 2 minutes 127.0.0.1:3000->3000/tcp priceless_mcclintock @@ -204,8 +156,8 @@ In this section, you learned the basics about creating a Dockerfile to build an Related information: - - [Dockerfile reference](/reference/dockerfile/) - - [docker CLI reference](/reference/cli/docker/) +- [Dockerfile reference](/reference/dockerfile/) +- [docker CLI reference](/reference/cli/docker/) ## Next steps diff --git a/content/get-started/workshop/03_updating_app.md b/content/get-started/workshop/03_updating_app.md index a4f688b6edd..50bce7e0133 100644 --- a/content/get-started/workshop/03_updating_app.md +++ b/content/get-started/workshop/03_updating_app.md @@ -72,9 +72,9 @@ To remove a container, you first need to stop it. Once it has stopped, you can r $ docker rm ``` ->**Note** +> [!NOTE] > ->You can stop and remove a container in a single command by adding the `force` flag to the `docker rm` command. For example: `docker rm -f ` +> You can stop and remove a container in a single command by adding the `force` flag to the `docker rm` command. For example: `docker rm -f ` {{< /tab >}} {{< tab name="Docker Desktop" >}} diff --git a/content/get-started/workshop/05_persisting_data.md b/content/get-started/workshop/05_persisting_data.md index 5e5864cde49..60b0e17c2b7 100644 --- a/content/get-started/workshop/05_persisting_data.md +++ b/content/get-started/workshop/05_persisting_data.md @@ -21,43 +21,37 @@ changes won't be seen in another container, even if they're using the same image ### See this in practice -To see this in action, you're going to start two containers. In one container, you'll create a file. In the other container, you'll verify the file exists. -What you'll see is that the file created in one container isn't available in another. +To see this in action, you're going to start two containers. In one container, +you'll create a file. In the other container, you'll check whether that same +file exists. -1. Start an Alpine container and access its shell. +1. Start an Alpine container and create a new file in it. ```console - $ docker run -ti --name=mytest alpine + $ docker run --rm alpine touch greeting.txt ``` -2. In the container, create a `greeting.txt` file with `hello` inside. + > [!TIP] + > Any commands you specify after the image name (in this case, `alpine`) + > are executed inside the container. In this case, the command `touch + > greeting.txt` puts a file named `greeting.txt` on the container's filesystem. - ```console - / # echo "hello" > greeting.txt - ``` - -3. Exit the container. - - ```console - / # exit - ``` - -4. Run a new Alpine container and use the `cat` command to verify that the - file does not exist. +2. Run a new Alpine container and use the `stat` command to check whether the file exists. ```console - $ docker run alpine cat greeting.txt + $ docker run --rm alpine stat greeting.txt ``` You should see output similar to the following that indicates the file does not exist in the new container. ```console - cat: can't open 'greeting.txt': No such file or directory + stat: can't stat 'greeting.txt': No such file or directory ``` -5. Go ahead and remove the containers using `docker ps --all` to get the IDs, - and then `docker rm -f ` to remove the containers. - +The `greeting.txt` file created by the first container did not exist in the +second container. That is because the writeable "top layer" of each container +is isolated. Even though both containers shared the same underlying layers that +make up the base image, the writable layer is unique to each container. ## Container volumes @@ -120,7 +114,7 @@ You can create the volume and start the container using the CLI or Docker Deskto > ``` > > For more details about Git Bash's syntax differences, see - > [Working with Git Bash](/desktop/troubleshoot/topics/#working-with-git-bash). + > [Working with Git Bash](/desktop/troubleshoot-and-support/troubleshoot/topics/#working-with-git-bash). {{< /tab >}} diff --git a/content/get-started/workshop/06_bind_mounts.md b/content/get-started/workshop/06_bind_mounts.md index 8a825759c73..70539a3e37d 100644 --- a/content/get-started/workshop/06_bind_mounts.md +++ b/content/get-started/workshop/06_bind_mounts.md @@ -50,7 +50,7 @@ work. 1. Verify that your `getting-started-app` directory is in a directory defined in Docker Desktop's file sharing setting. This setting defines which parts of your -filesystem you can share with containers. For details about accessing the setting, see [File sharing](/manuals/desktop/settings.md#file-sharing). +filesystem you can share with containers. For details about accessing the setting, see [File sharing](/manuals/desktop/settings-and-maintenance/settings.md#file-sharing). 2. Open a terminal and change directory to the `getting-started-app` directory. diff --git a/content/get-started/workshop/08_using_compose.md b/content/get-started/workshop/08_using_compose.md index 94f6e5e5a6c..c23e76a7cb1 100644 --- a/content/get-started/workshop/08_using_compose.md +++ b/content/get-started/workshop/08_using_compose.md @@ -268,12 +268,12 @@ quickly see what container is your app and which container is the mysql database When you're ready to tear it all down, simply run `docker compose down` or hit the trash can on the Docker Desktop Dashboard for the entire app. The containers will stop and the network will be removed. ->**Warning** +> [!WARNING] > ->By default, named volumes in your compose file are not removed when you run `docker compose down`. If you want to +> By default, named volumes in your compose file are not removed when you run `docker compose down`. If you want to >remove the volumes, you need to add the `--volumes` flag. > ->The Docker Desktop Dashboard does not remove volumes when you delete the app stack. +> The Docker Desktop Dashboard does not remove volumes when you delete the app stack. ## Summary diff --git a/content/get-started/workshop/09_image_best.md b/content/get-started/workshop/09_image_best.md index 2e91579a222..a84842d75f1 100644 --- a/content/get-started/workshop/09_image_best.md +++ b/content/get-started/workshop/09_image_best.md @@ -61,7 +61,7 @@ Look at the following Dockerfile you created for the getting started app. ```dockerfile # syntax=docker/dockerfile:1 -FROM node:18-alpine +FROM node:lts-alpine WORKDIR /app COPY . . RUN yarn install --production @@ -81,7 +81,7 @@ dependencies if there was a change to the `package.json`. ```dockerfile # syntax=docker/dockerfile:1 - FROM node:18-alpine + FROM node:lts-alpine WORKDIR /app COPY package.json yarn.lock ./ RUN yarn install --production @@ -103,10 +103,10 @@ dependencies if there was a change to the `package.json`. => => transferring dockerfile: 175B => [internal] load .dockerignore => => transferring context: 2B - => [internal] load metadata for docker.io/library/node:18-alpine + => [internal] load metadata for docker.io/library/node:lts-alpine => [internal] load build context => => transferring context: 53.37MB - => [1/5] FROM docker.io/library/node:18-alpine + => [1/5] FROM docker.io/library/node:lts-alpine => CACHED [2/5] WORKDIR /app => [3/5] COPY package.json yarn.lock ./ => [4/5] RUN yarn install --production @@ -127,10 +127,10 @@ dependencies if there was a change to the `package.json`. => => transferring dockerfile: 37B => [internal] load .dockerignore => => transferring context: 2B - => [internal] load metadata for docker.io/library/node:18-alpine + => [internal] load metadata for docker.io/library/node:lts-alpine => [internal] load build context => => transferring context: 450.43kB - => [1/5] FROM docker.io/library/node:18-alpine + => [1/5] FROM docker.io/library/node:lts-alpine => CACHED [2/5] WORKDIR /app => CACHED [3/5] COPY package.json yarn.lock ./ => CACHED [4/5] RUN yarn install --production @@ -182,7 +182,7 @@ for your production build. You can ship the static resources in a static nginx c ```dockerfile # syntax=docker/dockerfile:1 -FROM node:18 AS build +FROM node:lts AS build WORKDIR /app COPY package* yarn.lock ./ RUN yarn install @@ -194,7 +194,7 @@ FROM nginx:alpine COPY --from=build /app/build /usr/share/nginx/html ``` -In the previous Dockerfile example, it uses the `node:18` image to perform the build (maximizing layer caching) and then copies the output +In the previous Dockerfile example, it uses the `node:lts` image to perform the build (maximizing layer caching) and then copies the output into an nginx container. ## Summary diff --git a/content/guides/_index.md b/content/guides/_index.md index 4d10f38ead8..1aed59cd077 100644 --- a/content/guides/_index.md +++ b/content/guides/_index.md @@ -6,8 +6,9 @@ params: icon: developer_guide layout: landing aliases: - - /learning-paths/ + - /guides/language/ - /language/ + - /learning-paths/ --- Explore our collection of guides to learn how Docker can optimize your diff --git a/content/guides/admin-set-up/_index.md b/content/guides/admin-set-up/_index.md index 91e0e429b88..556c512a7c1 100644 --- a/content/guides/admin-set-up/_index.md +++ b/content/guides/admin-set-up/_index.md @@ -23,10 +23,8 @@ params: url: /security/for-admins/hardened-desktop/registry-access-management/ - title: Image Access Management url: /security/for-admins/hardened-desktop/image-access-management/ - - title: Docker Build Cloud subscription information - url: /subscription/build-cloud/build-details/ - - title: Docker Scout subscription information - url: /subscription/scout-details/ + - title: Docker subscription information + url: /subscription/details/ --- Docker's tools provide a scalable, secure platform that empowers your developers to create, ship, and run applications faster. As an administrator, you have the ability to streamline workflows, standardize development environments, and ensure smooth deployments across your organization. diff --git a/content/guides/admin-set-up/comms-and-info-gathering.md b/content/guides/admin-set-up/comms-and-info-gathering.md index a70f525ab16..1ad54fb855c 100644 --- a/content/guides/admin-set-up/comms-and-info-gathering.md +++ b/content/guides/admin-set-up/comms-and-info-gathering.md @@ -24,10 +24,10 @@ Some companies may have more than one [Docker organization](/manuals/admin/organ ## Step three: Gather requirements -Through [Settings Management](/manuals/security/for-admins/hardened-desktop/settings-management/_index.md), Docker provides numerous configuration parameters that can be preset. The Docker organization owner, development lead, and infosec representative should review these settings to establish the company’s baseline configuration, including security features and [enforcing sign-in](/manuals/security/for-admins/enforce-sign-in/_index.md) for Docker Desktop users. Additionally, they should decide whether to take advantage of free trials for other Docker products, such as [Docker Scout](/manuals/scout/_index.md), which is included in the subscription. +Through [Settings Management](/manuals/security/for-admins/hardened-desktop/settings-management/_index.md), Docker provides numerous configuration parameters that can be preset. The Docker organization owner, development lead, and infosec representative should review these settings to establish the company’s baseline configuration, including security features and [enforcing sign-in](/manuals/security/for-admins/enforce-sign-in/_index.md) for Docker Desktop users. Additionally, they should decide whether to take advantage of other Docker products, such as [Docker Scout](/manuals/scout/_index.md), which is included in the subscription. -To view the parameters that can be preset, see [Configure Settings Management](/manuals/security/for-admins/hardened-desktop/settings-management/configure.md#step-two-configure-the-settings-you-want-to-lock-in). +To view the parameters that can be preset, see [Configure Settings Management](/manuals/security/for-admins/hardened-desktop/settings-management/configure-json-file.md#step-two-configure-the-settings-you-want-to-lock-in). ## Optional step four: Meet with the Docker Implementation team -The Docker Implementation team can help you step through setting up your organization, configuring SSO, enforcing sign in, and configuring Docker. You can reach out to set up a meeting by emailing successteam@docker.com. +The Docker Implementation team can help you step through setting up your organization, configuring SSO, enforcing sign-in, and configuring Docker. You can reach out to set up a meeting by emailing successteam@docker.com. diff --git a/content/guides/admin-set-up/finalize-plans-and-setup.md b/content/guides/admin-set-up/finalize-plans-and-setup.md index 3f085fb1c55..b810d3dfbc0 100644 --- a/content/guides/admin-set-up/finalize-plans-and-setup.md +++ b/content/guides/admin-set-up/finalize-plans-and-setup.md @@ -6,9 +6,9 @@ weight: 20 ## Step one: Send finalized settings files to the MDM team -After reaching an agreement with the relevant teams on your baseline and security configurations as outlined in module one, follow the instructions in the [Settings Management](/manuals/security/for-admins/hardened-desktop/settings-management/_index.md) documentation to create the `admin-settings.json` file that captures these configurations. +After reaching an agreement with the relevant teams about your baseline and security configurations as outlined in module one, configure Settings Management using either the [Docker Admin Console](/manuals/security/for-admins/hardened-desktop/settings-management/configure-admin-console.md) or an [`admin-settings.json` file](/manuals/security/for-admins/hardened-desktop/settings-management/configure-json-file.md). -Once the file is ready, collaborate with your MDM team to deploy the `admin-settings.json` file, along with your chosen method for [enforcing sign-in](/manuals/security/for-admins/enforce-sign-in/_index.md). +Once the file is ready, collaborate with your MDM team to deploy your chosen settings, along with your chosen method for [enforcing sign-in](/manuals/security/for-admins/enforce-sign-in/_index.md). > [!IMPORTANT] > @@ -26,9 +26,9 @@ Single sign-on (SSO) lets developers authenticate using their identity providers You can also enable [SCIM](/manuals/security/for-admins/provisioning/scim.md) for further automation of provisioning and deprovisioning of users. -### Set up free tier Docker product entitlements included in the subscription +### Set up Docker product entitlements included in the subscription -[Docker Build Cloud](/manuals/build-cloud/_index.md) significantly reduces build times, both locally and in CI, by providing a dedicated remote builder and shared cache. Powered by the cloud, developer time and local resources are freed up so your team can focus on more important things, like innovation. To get started, [set up a cloud builder](http://build.docker.com). +[Docker Build Cloud](/manuals/build-cloud/_index.md) significantly reduces build times, both locally and in CI, by providing a dedicated remote builder and shared cache. Powered by the cloud, developer time and local resources are freed up so your team can focus on more important things, like innovation. To get started, [set up a cloud builder](https://app.docker.com/build/). [Docker Scout](manuals/scout/_index.md) is a solution for proactively enhancing your software supply chain security. By analyzing your images, Docker Scout compiles an inventory of components, also known as a Software Bill of Materials (SBOM). The SBOM is matched against a continuously updated vulnerability database to pinpoint security weaknesses. To get started, see [Quickstart](/manuals/scout/quickstart.md). diff --git a/content/guides/admin-set-up/testing.md b/content/guides/admin-set-up/testing.md index d4fd0b805cc..9ee6306764e 100644 --- a/content/guides/admin-set-up/testing.md +++ b/content/guides/admin-set-up/testing.md @@ -23,10 +23,10 @@ If you plan to use [Registry Access Management (RAM)](/manuals/security/for-admi Deploy the Docker settings and enforce sign-in for a small group of test users via MDM. Have this group test their development workflows with containers on Docker Desktop and Docker Hub to ensure all settings and the sign-in enforcement function as expected. -## Test Build Cloud capabilities +## Test Docker Build Cloud capabilities Have one of your Docker Desktop testers [connect to the cloud builder you created and use it to build](/manuals/build-cloud/usage.md). -## Verify Scout monitoring of repositories +## Verify Docker Scout monitoring of repositories Check the [Docker Scout dashboard](https://scout.docker.com/) to confirm that data is being properly received for the repositories where Docker Scout has been enabled. diff --git a/content/guides/bake/index.md b/content/guides/bake/index.md index ba42268f567..c099ec1c528 100644 --- a/content/guides/bake/index.md +++ b/content/guides/bake/index.md @@ -33,7 +33,7 @@ This guide assumes that you're familiar with: - You have a recent version of Docker installed on your machine. - You have Git installed for cloning repositories. -- You're using the [containerd](/manuals/desktop/containerd.md) image store. +- You're using the [containerd](/manuals/desktop/features/containerd.md) image store. ## Introduction diff --git a/content/guides/bun/configure-ci-cd.md b/content/guides/bun/configure-ci-cd.md index 0f614a9c387..b14e34d39bb 100644 --- a/content/guides/bun/configure-ci-cd.md +++ b/content/guides/bun/configure-ci-cd.md @@ -79,17 +79,16 @@ to Docker Hub. build: runs-on: ubuntu-latest steps: - - - name: Login to Docker Hub + - name: Login to Docker Hub uses: docker/login-action@v3 with: username: ${{ vars.DOCKER_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} - - - name: Set up Docker Buildx + + - name: Set up Docker Buildx uses: docker/setup-buildx-action@v3 - - - name: Build and push + + - name: Build and push uses: docker/build-push-action@v6 with: platforms: linux/amd64,linux/arm64 @@ -123,8 +122,10 @@ Save the workflow file and run the job. In this section, you learned how to set up a GitHub Actions workflow for your Bun application. Related information: - - [Introduction to GitHub Actions](/manuals/build/ci/github-actions/_index.md) - - [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions) + +- [Introduction to GitHub Actions](/guides/gha.md) +- [Docker Build GitHub Actions](/manuals/build/ci/github-actions/_index.md) +- [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions) ## Next steps diff --git a/content/guides/bun/deploy.md b/content/guides/bun/deploy.md index 7659c97fd91..7a8690941ef 100644 --- a/content/guides/bun/deploy.md +++ b/content/guides/bun/deploy.md @@ -11,7 +11,7 @@ aliases: ## Prerequisites - Complete all the previous sections of this guide, starting with [Containerize a Bun application](containerize.md). -- [Turn on Kubernetes](/desktop/kubernetes/#install-and-turn-on-kubernetes) in Docker Desktop. +- [Turn on Kubernetes](/manuals//desktop/features/kubernetes.md#install-and-turn-on-kubernetes) in Docker Desktop. ## Overview @@ -137,5 +137,5 @@ In this section, you learned how to use Docker Desktop to deploy your Bun applic Related information: - [Kubernetes documentation](https://kubernetes.io/docs/home/) - - [Deploy on Kubernetes with Docker Desktop](/manuals/desktop/kubernetes.md) + - [Deploy on Kubernetes with Docker Desktop](/manuals/desktop/features/kubernetes.md) - [Swarm mode overview](/manuals/engine/swarm/_index.md) diff --git a/content/guides/compose-bake/index.md b/content/guides/compose-bake/index.md new file mode 100644 index 00000000000..c6f4d312366 --- /dev/null +++ b/content/guides/compose-bake/index.md @@ -0,0 +1,402 @@ +--- +title: Building Compose projects with Bake +description: Learn how to build Docker Compose projects with Docker Buildx Bake +summary: | + This guide demonstrates how you can use Bake to build production-grade images for Docker Compose projects. +languages: [] +tags: [devops] +params: + time: 20 minutes +--- + +This guide explores how you can use Bake to build images for Docker Compose +projects with multiple services. + +[Docker Buildx Bake](/manuals/build/bake/_index.md) is a build orchestration +tool that enables declarative configuration for your builds, much like Docker +Compose does for defining runtime stacks. For projects where Docker Compose is +used to spin up services for local development, Bake offers a way of seamlessly +extending the project with a production-ready build configuration. + +## Prerequisites + +This guide assumes that you're familiar with + +- Docker Compose +- [Multi-stage builds](/manuals/build/building/multi-stage.md) +- [Multi-platform builds](/manuals/build/building/multi-platform.md) + +## Orientation + +This guide will use the +[dvdksn/example-voting-app](https://github.com/dvdksn/example-voting-app) +repository as an example of a monorepo using Docker Compose that can be +extended with Bake. + +```console +$ git clone https://github.com/dvdksn/example-voting-app.git +$ cd example-voting-app +``` + +This repository uses Docker Compose to define the runtime configurations for +running the application, in the `compose.yaml` file. This app consists of the +following services: + +| Service | Description | +| -------- | ---------------------------------------------------------------------- | +| `vote` | A front-end web app in Python which lets you vote between two options. | +| `result` | A Node.js web app which shows the results of the voting in real time. | +| `worker` | A .NET worker which consumes votes and stores them in the database. | +| `db` | A Postgres database backed by a Docker volume. | +| `redis` | A Redis instance which collects new votes. | +| `seed` | A utility container that seeds the database with mock data. | + +The `vote`, `result`, and `worker` services are built from code in this +repository, whereas `db` and `redis` use pre-existing Postgres and Redis images +from Docker Hub. The `seed` service is a utility that invokes requests against +the front-end service to populate the database, for testing purposes. + +## Build with Compose + +When you spin up a Docker Compose project, any services that define the `build` +property are automatically built before the service is started. Here's the +build configuration for the `vote` service in the example repository: + +```yaml {title="compose.yaml"} +services: + vote: + build: + context: ./vote # Build context + target: dev # Dockerfile stage +``` + +The `vote`, `result`, and `worker` services all have a build configuration +specified. Running `docker compose up` will trigger a build of these services. + +Did you know that you can also use Compose just to build the service images? +The `docker compose build` command lets you invoke a build using the build +configuration specified in the Compose file. For example, to build the `vote` +service with this configuration, run: + +```console +$ docker compose build vote +``` + +Omit the service name to build all services at once: + +```console +$ docker compose build +``` + +The `docker compose build` command is useful when you only need to build images +without running services. + +The Compose file format supports a number of properties for defining your +build's configuration. For example, to specify the tag name for the images, set +the `image` property on the service. + +```yaml +services: + vote: + image: username/vote + build: + context: ./vote + target: dev + #... + + result: + image: username/result + build: + context: ./result + #... + + worker: + image: username/worker + build: + context: ./worker + #... +``` + +Running `docker compose build` creates three service images with fully +qualified image names that you can push to Docker Hub. + +The `build` property supports a [wide range](/reference/compose-file/build.md) +of options for configuring builds. However, building production-grade images +are often different from images used in local development. To avoid cluttering +your Compose file with build configurations that might not be desirable for +local builds, consider separating the production builds from the local builds +by using Bake to build images for release. This approach separates concerns: +using Compose for local development and Bake for production-ready builds, while +still reusing service definitions and fundamental build configurations. + +## Build with Bake + +Like Compose, Bake parses the build definition for a project from a +configuration file. Bake supports HashiCorp Configuration Language (HCL), JSON, +and the Docker Compose YAML format. When you use Bake with multiple files, it +will find and merge all of the applicable configuration files into one unified +build configuration. The build options defined in your Compose file are +extended, or in some cases overridden, by options specified in the Bake file. + +The following section explores how you can use Bake to extend the build options +defined in your Compose file for production. + +### View the build configuration + +Bake automatically creates a build configuration from the `build` properties of +your services. Use the `--print` flag for Bake to view the build configuration +for a given Compose file. This flag evaluates the build configuration and +outputs the build definition in JSON format. + +```console +$ docker buildx bake --print +``` + +The JSON-formatted output shows the group that would be executed, and all the +targets of that group. A group is a collection of builds, and a target +represents a single build. + +```json +{ + "group": { + "default": { + "targets": [ + "vote", + "result", + "worker", + "seed" + ] + } + }, + "target": { + "result": { + "context": "result", + "dockerfile": "Dockerfile", + }, + "seed": { + "context": "seed-data", + "dockerfile": "Dockerfile", + }, + "vote": { + "context": "vote", + "dockerfile": "Dockerfile", + "target": "dev", + }, + "worker": { + "context": "worker", + "dockerfile": "Dockerfile", + } + } +} +``` + +As you can see, Bake has created a `default` group that includes four targets: + +- `seed` +- `vote` +- `result` +- `worker` + +This group is created automatically from your Compose file; it includes all of +your services containing a build configuration. To build this group of services +with Bake, run: + +```console +$ docker buildx bake +``` + +### Customize the build group + +Start by redefining the default build group that Bake executes. The current +default group includes a `seed` target — a Compose service used solely to +populate the database with mock data. Since this target doesn't produce a +production image, it doesn’t need to be included in the build group. + +To customize the build configuration that Bake uses, create a new file at the +root of the repository, alongside your `compose.yaml` file, named +`docker-bake.hcl`. + +```console +$ touch docker-bake.hcl +``` + +Open the Bake file and add the following configuration: + +```hcl {title=docker-bake.hcl} +group "default" { + targets = ["vote", "result", "worker"] +} +``` + +Save the file and print your Bake definition again. + +```console +$ docker buildx bake --print +``` + +The JSON output shows that the `default` group only includes the targets you +care about. + +```json +{ + "group": { + "default": { + "targets": ["vote", "result", "worker"] + } + }, + "target": { + "result": { + "context": "result", + "dockerfile": "Dockerfile", + "tags": ["username/result"] + }, + "vote": { + "context": "vote", + "dockerfile": "Dockerfile", + "tags": ["username/vote"], + "target": "dev" + }, + "worker": { + "context": "worker", + "dockerfile": "Dockerfile", + "tags": ["username/worker"] + } + } +} +``` + +Here, the build configuration for each target (context, tags, etc.) is picked +up from the `compose.yaml` file. The group is defined by the `docker-bake.hcl` +file. + +### Customize targets + +The Compose file currently defines the `dev` stage as the build target for the +`vote` service. That's appropriate for the image that you would run in local +development, because the `dev` stage includes additional development +dependencies and configurations. For the production image, however, you'll want +to target the `final` image instead. + +To modify the target stage used by the `vote` service, add the following +configuration to the Bake file: + +```hcl +target "vote" { + target = "final" +} +``` + +This overrides the `target` property specified in the Compose file with a +different value when you run the build with Bake. The other build options in +the Compose file (tag, context) remain unmodified. You can verify by inspecting +the build configuration for the `vote` target with `docker buildx bake --print +vote`: + +```json +{ + "group": { + "default": { + "targets": ["vote"] + } + }, + "target": { + "vote": { + "context": "vote", + "dockerfile": "Dockerfile", + "tags": ["username/vote"], + "target": "final" + } + } +} +``` + +### Additional build features + +Production-grade builds often have different characteristics from development +builds. Here are a few examples of things you might want to add for production +images. + +Multi-platform +: For local development, you only need to build images for your local platform, +since those images are just going to run on your machine. But for images that +are pushed to a registry, it's often a good idea to build for multiple +platforms, arm64 and amd64 in particular. + +Attestations +: [Attestations](/manuals/build/metadata/attestations/_index.md) are manifests +attached to the image that describe how the image was created and what +components it contains. Attaching attestations to your images helps ensure that +your images follow software supply chain best practices. + +Annotations +: [Annotations](/manuals/build/metadata/annotations.md) provide descriptive +metadata for images. Use annotations to record arbitrary information and attach +it to your image, which helps consumers and tools understand the origin, +contents, and how to use the image. + +> [!TIP] +> Why not just define these additional build options in the Compose file +> directly? +> +> The `build` property in the Compose file format does not support all build +> features. Additionally, some features, like multi-platform builds, can +> drastically increase the time it takes to build a service. For local +> development, you're better off keeping your build step simple and fast, +> saving the bells and whistles for release builds. + +To add these properties to the images you build with Bake, update the Bake file +as follows: + +```hcl +group "default" { + targets = ["vote", "result", "worker"] +} + +target "_common" { + annotations = ["org.opencontainers.image.authors=username"] + platforms = ["linux/amd64", "linux/arm64"] + attest = [ + "type=provenance,mode=max", + "type=sbom" + ] +} + +target "vote" { + inherits = ["_common"] + target = "final" +} + +target "result" { + inherits = ["_common"] +} + +target "worker" { + inherits = ["_common"] +} +``` + +This defines a new `_common` target that defines reusable build configuration +for adding multi-platform support, annotations, and attestations to your +images. The reusable target is inherited by the build targets. + +With these changes, building the project with Bake produces three sets of +multi-platform images for the `linux/amd64` and `linux/arm64` architectures. +Each image is decorated with an author annotation, and both SBOM and provenance +attestation records. + +## Conclusions + +The pattern demonstrated in this guide provides a useful approach for managing +production-ready Docker images in projects using Docker Compose. Using Bake +gives you access to all the powerful features of Buildx and BuildKit, and also +helps separate your development and build configuration in a reasonable way. + +### Further reading + +For more information about how to use Bake, check out these resources: + +- [Bake documentation](/manuals/build/bake/_index.md) +- [Building with Bake from a Compose file](/manuals/build/bake/compose-file.md) +- [Bake file reference](/manuals/build/bake/reference.md) +- [Mastering multi-platform builds, testing, and more with Docker Buildx Bake](/guides/bake/index.md) +- [Bake GitHub Action](https://github.com/docker/bake-action) diff --git a/content/guides/container-supported-development.md b/content/guides/container-supported-development.md index b76918ebdc1..5a2f142f923 100644 --- a/content/guides/container-supported-development.md +++ b/content/guides/container-supported-development.md @@ -51,6 +51,10 @@ With container-supported development, it's easy to run databases locally. In thi {{< youtube-embed VieWeXOwKLU >}} +> [!TIP] +> +> Learn more about running databases in containers in the [Use containerized databases](/guides/databases.md) guide. + ### Demo: mocking API endpoints Many APIs require data from other data endpoints. In development, this adds complexities such as the sharing of credentials, uptime/availability, and rate limiting. Instead of relying on those services directly, your application can interact with a mock API server. @@ -59,6 +63,10 @@ This demo will demonstrate how using WireMock can make it easy to develop and te {{< youtube-embed VXSmX6f8vo0 >}} +> [!TIP] +> +> Learn more about using WireMock to mock API in the [Mocking API services with WireMock](/guides/wiremock.md) guide. + ### Demo: developing the cloud locally When developing apps, it's often easier to outsource aspects of the application to cloud services, such as Amazon S3. However, connecting to those services in local development introduces IAM policies, networking constraints, and provisioning complications. While these requirements are important in a production setting, they complicate development environments significantly. @@ -67,6 +75,10 @@ With container-supported development, you can run local instances of these servi {{< youtube-embed JtwUMvR5xlY >}} +> [!TIP] +> +> Learn more about using LocalStack in the [Develop and test AWS Cloud applications using LocalStack](/guides/localstack.md) guide. + ### Demo: adding additional debug and troubleshooting tools Once you start using containers in your development environment, it becomes much easier to add additional containers to visualize the contents of the databases or message queues, seed document stores, or event publishers. In this demo, you'll see a few of these examples, as well as how you can connect multiple containers together to make testing even easier. diff --git a/content/guides/cpp/configure-ci-cd.md b/content/guides/cpp/configure-ci-cd.md index 57145b8e74d..6f0e9de6139 100644 --- a/content/guides/cpp/configure-ci-cd.md +++ b/content/guides/cpp/configure-ci-cd.md @@ -85,8 +85,10 @@ to Docker Hub. with: username: ${{ vars.DOCKER_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} + - name: Set up Docker Buildx uses: docker/setup-buildx-action@v3 + - name: Build and push uses: docker/build-push-action@v6 with: @@ -122,7 +124,8 @@ In this section, you learned how to set up a GitHub Actions workflow for your C+ Related information: -- [Introduction to GitHub Actions](/manuals/build/ci/github-actions/_index.md) +- [Introduction to GitHub Actions](/guides/gha.md) +- [Docker Build GitHub Actions](/manuals/build/ci/github-actions/_index.md) - [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions) ## Next steps diff --git a/content/guides/cpp/deploy.md b/content/guides/cpp/deploy.md index 2c3a1ef66ea..e023bdd5b12 100644 --- a/content/guides/cpp/deploy.md +++ b/content/guides/cpp/deploy.md @@ -12,7 +12,7 @@ aliases: ## Prerequisites - Complete all the previous sections of this guide, starting with [Containerize a C++ application](containerize.md). -- [Turn on Kubernetes](/desktop/kubernetes/#install-and-turn-on-kubernetes) in Docker Desktop. +- [Turn on Kubernetes](/manuals/desktop/features/kubernetes.md#install-and-turn-on-kubernetes) in Docker Desktop. ## Overview @@ -139,5 +139,5 @@ In this section, you learned how to use Docker Desktop to deploy your C++ applic Related information: - [Kubernetes documentation](https://kubernetes.io/docs/home/) -- [Deploy on Kubernetes with Docker Desktop](/manuals/desktop/kubernetes.md) +- [Deploy on Kubernetes with Docker Desktop](/manuals/desktop/features/kubernetes.md) - [Swarm mode overview](/manuals/engine/swarm/_index.md) diff --git a/content/guides/docker-build-cloud/_index.md b/content/guides/docker-build-cloud/_index.md index ba8c398c441..9d5aae132e9 100644 --- a/content/guides/docker-build-cloud/_index.md +++ b/content/guides/docker-build-cloud/_index.md @@ -20,7 +20,7 @@ params: - title: Docker Build Cloud overview url: /build-cloud/ - title: Subscriptions and features - url: /subscription/build-cloud/build-details/ + url: /subscription/details/ - title: Using Docker Build Cloud url: /build-cloud/usage/ --- diff --git a/content/guides/docker-build-cloud/common-questions.md b/content/guides/docker-build-cloud/common-questions.md index 8470a08d89a..c397987620b 100644 --- a/content/guides/docker-build-cloud/common-questions.md +++ b/content/guides/docker-build-cloud/common-questions.md @@ -38,12 +38,11 @@ Docker subscribers (Pro, Team, Business) receive a set number of minutes each month, shared across the account, to use Build Cloud. If you do not have a Docker subscription, you may sign up for a free Personal -account and get 50 minutes per month. Personal accounts are limited to a single -user. +account and start a trial of Docker Build Cloud. Personal accounts are limited to a +single user. For teams to receive the shared cache benefit, they must either be on a Docker -Team, Docker Business, or paid Build Cloud Team plan. You may buy a month of -Build Cloud Team for the number of seats testing. +Team or Docker Business plan. ### Does Docker Build Cloud support CI platforms? Does it work with GitHub Actions? diff --git a/content/guides/docker-scout/_index.md b/content/guides/docker-scout/_index.md index 3134c8e85a6..eaa39f527ae 100644 --- a/content/guides/docker-scout/_index.md +++ b/content/guides/docker-scout/_index.md @@ -14,7 +14,7 @@ aliases: params: featured: true image: images/learning-paths/scout.png - time: 10 minutes + time: 20 minutes resource_links: - title: Docker Scout overview url: /scout/ @@ -22,8 +22,6 @@ params: url: /scout/quickstart/ - title: Install Docker Scout url: /scout/install/ - - title: Software Bill of Materials - url: /scout/concepts/sbom/ --- When container images are insecure, significant risks can arise. Around 60% of diff --git a/content/guides/docker-scout/attestations.md b/content/guides/docker-scout/attestations.md new file mode 100644 index 00000000000..fb060e70336 --- /dev/null +++ b/content/guides/docker-scout/attestations.md @@ -0,0 +1,36 @@ +--- +title: Attestations +keywords: build, attestations, sbom, provenance, metadata +description: | + Introduction to SBOM and provenance attestations with Docker Build, + what they are, and why they exist +weight: 50 +--- + +{{< youtube-embed qOzcycbTs4o >}} + +[Build attestations](/manuals/build/metadata/attestations/_index.md) give you +detailed information about how an image was built and what it contains. These +attestations, generated by BuildKit during build-time, attach to the final +image as metadata, allowing you to inspect an image to see its origin, creator, +and contents. This information helps you make informed decisions about the +security and impact of the image on your supply chain. + +Docker Scout uses these attestations to evaluate the image's security and +supply chain posture, and to provide remediation recommendations for issues. If +issues are detected, such as missing or outdated attestations, Docker Scout can +guide you on how to add or update them, ensuring compliance and improving +visibility into the image's security status. + +There are two key types of attestations: + +- SBOM, which lists the software artifacts within the image. +- Provenance, which details how the image was built. + +You can create attestations by using `docker buildx build` with the +`--provenance` and `--sbom` flags. Attestations attach to the image index, +allowing you to inspect them without pulling the entire image. Docker Scout +leverages this metadata to give you more precise recommendations and better +control over your image's security. + +
diff --git a/content/guides/docker-scout/common-questions.md b/content/guides/docker-scout/common-questions.md index 65a98d737a2..21537ed80e4 100644 --- a/content/guides/docker-scout/common-questions.md +++ b/content/guides/docker-scout/common-questions.md @@ -1,7 +1,6 @@ --- title: Common challenges and questions description: Explore common challenges and questions related to Docker Scout. -weight: 30 --- diff --git a/content/guides/docker-scout/demo.md b/content/guides/docker-scout/demo.md index 2304b82d8fe..e1d07406698 100644 --- a/content/guides/docker-scout/demo.md +++ b/content/guides/docker-scout/demo.md @@ -1,9 +1,12 @@ --- title: Docker Scout demo +linkTitle: Demo description: Learn about Docker Scout's powerful features for enhanced supply chain security. weight: 20 --- +{{< youtube-embed "TkLwJ0p46W8" >}} + Docker Scout has powerful features for enhancing containerized application security and ensuring a robust software supply chain. @@ -15,6 +18,4 @@ security and ensuring a robust software supply chain. removing unnecessary packages - Verify and validate remediation efforts using Docker Scout -{{< youtube-embed "TkLwJ0p46W8" >}} -
diff --git a/content/guides/docker-scout/remediation.md b/content/guides/docker-scout/remediation.md new file mode 100644 index 00000000000..e485c9cd3cf --- /dev/null +++ b/content/guides/docker-scout/remediation.md @@ -0,0 +1,27 @@ +--- +title: Remediation +description: Learn how Docker Scout can help you improve your software quality automatically, using remediation +keywords: scout, supply chain, security, remediation, automation +weight: 60 +--- + +{{< youtube-embed jM9zLBf8M-8 >}} + +Docker Scout's [remediation feature](/manuals/scout/policy/remediation.md) +helps you address supply chain and security issues by offering tailored +recommendations based on policy evaluations. These recommendations guide you in +improving policy compliance or enhancing image metadata, allowing Docker Scout +to perform more accurate evaluations in the future. + +You can use this feature to ensure that your base images are up-to-date and +that your supply chain attestations are complete. When a violation occurs, +Docker Scout provides recommended fixes, such as updating your base image or +adding missing attestations. If there isn’t enough information to determine +compliance, Docker Scout suggests actions to help resolve the issue. + +In the Docker Scout Dashboard, you can view and act on these recommendations by +reviewing violations or compliance uncertainties. With integrations like +GitHub, you can even automate updates, directly fixing issues from the +dashboard. + +
diff --git a/content/manuals/scout/concepts/s3c.md b/content/guides/docker-scout/s3c.md similarity index 89% rename from content/manuals/scout/concepts/s3c.md rename to content/guides/docker-scout/s3c.md index 6c13291e2e2..df6eac67a7f 100644 --- a/content/manuals/scout/concepts/s3c.md +++ b/content/guides/docker-scout/s3c.md @@ -2,8 +2,13 @@ title: Software supply chain security description: Learn about software supply chain security (S3C), what it means, and why it is important. keywords: docker scout, secure, software, supply, chain, security, sssc, sscs, s3c +aliases: + - /scout/concepts/s3c/ +weight: 30 --- +{{< youtube-embed YzNK6E7APv0 >}} + The term "software supply chain" refers to the end-to-end process of developing and delivering software, from the development to deployment and maintenance. Software supply chain security, or "S3C" for short, is the practice for @@ -39,7 +44,7 @@ day where software is built using multiple components from different sources. Organizations need to have a clear understanding of the software components they use, and the security risks associated with them. -## Docker Scout +## How Docker Scout is different Docker Scout is a platform designed to help organizations secure their software supply chain. It provides tools and services for identifying and managing @@ -53,9 +58,11 @@ updated risk assessment is available within seconds, and earlier in the development process. Docker Scout works by analyzing the composition of your images to create a -[Software Bill of Materials (SBOM)](/manuals/scout/concepts/sbom.md). The SBOM is -cross-referenced against the security advisories to identify CVEs that affect -your images. Docker Scout integrates with [over 20 different security +Software Bill of Materials (SBOM). The SBOM is cross-referenced against the +security advisories to identify CVEs that affect your images. Docker Scout +integrates with [over 20 different security advisories](/manuals/scout/deep-dive/advisory-db-sources.md), and updates its vulnerability database in real-time. This ensures that your security posture is represented using the latest available information. + +
diff --git a/content/manuals/scout/concepts/sbom.md b/content/guides/docker-scout/sbom.md similarity index 81% rename from content/manuals/scout/concepts/sbom.md rename to content/guides/docker-scout/sbom.md index 69c80d5d040..c7c6e2fa8a3 100644 --- a/content/manuals/scout/concepts/sbom.md +++ b/content/guides/docker-scout/sbom.md @@ -2,8 +2,13 @@ title: Software Bill of Materials description: Learn about Software Bill of Materials (SBOM) and how Docker Scout uses it. keywords: scout, sbom, software bill of materials, analysis, composition +aliases: + - /scout/concepts/sbom/ +weight: 40 --- +{{< youtube-embed PbS4y7C7h4A >}} + A Bill of Materials (BOM) is a list of materials, parts, and the quantities of each needed to manufacture a product. For example, a BOM for a computer might list the motherboard, CPU, RAM, power supply, storage devices, case, and other @@ -35,16 +40,10 @@ An SBOM typically includes the following information: Docker Scout uses SBOMs to determine the components that are used in a Docker image. When you analyze an image, Docker Scout will either use the SBOM that is -attached to the image (using [attestations](/manuals/build/metadata/attestations/_index.md)), or -it will generate an SBOM on the fly by analyzing the contents of the image. +attached to the image as an attestation, or it will generate an SBOM on the fly +by analyzing the contents of the image. The SBOM is cross-referenced with the [advisory database](/manuals/scout/deep-dive/advisory-db-sources.md) to determine if any of the components in the image have known vulnerabilities. -## Additional resources - -To learn more about generating SBOMs and how SBOMs are used in Docker Scout, -see: - -- [Image analysis in Docker Scout](/manuals/scout/explore/analysis.md) -- [View and create SBOMs](/manuals/scout/how-tos/view-create-sboms.md) +
diff --git a/content/guides/docker-scout/why.md b/content/guides/docker-scout/why.md index bf84d26f682..3c63052fcb0 100644 --- a/content/guides/docker-scout/why.md +++ b/content/guides/docker-scout/why.md @@ -4,6 +4,8 @@ description: Learn how Docker Scout can help you secure your supply chain. weight: 10 --- +{{< youtube-embed "-omsQ7Uqyc4" >}} + Organizations face significant challenges from data breaches, including financial losses, operational disruptions, and long-term damage to brand reputation and customer trust. Docker Scout addresses critical problems @@ -22,6 +24,4 @@ development process. It also integrates with popular development tools like Docker Desktop and GitHub Actions, providing seamless security management and compliance checks within existing workflows. -{{< youtube-embed "-omsQ7Uqyc4" >}} -
diff --git a/content/guides/dotnet/configure-ci-cd.md b/content/guides/dotnet/configure-ci-cd.md index a01592e2fb5..3e667a30f28 100644 --- a/content/guides/dotnet/configure-ci-cd.md +++ b/content/guides/dotnet/configure-ci-cd.md @@ -93,13 +93,16 @@ to Docker Hub. with: username: ${{ vars.DOCKER_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} + - name: Set up Docker Buildx uses: docker/setup-buildx-action@v3 + - name: Build and test uses: docker/build-push-action@v6 with: target: build load: true + - name: Build and push uses: docker/build-push-action@v6 with: @@ -136,7 +139,8 @@ In this section, you learned how to set up a GitHub Actions workflow for your ap Related information: -- [Introduction to GitHub Actions](/manuals/build/ci/github-actions/_index.md) +- [Introduction to GitHub Actions](/guides/gha.md) +- [Docker Build GitHub Actions](/manuals/build/ci/github-actions/_index.md) - [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions) ## Next steps diff --git a/content/guides/dotnet/deploy.md b/content/guides/dotnet/deploy.md index 17a6f5f218d..ed1b464e954 100644 --- a/content/guides/dotnet/deploy.md +++ b/content/guides/dotnet/deploy.md @@ -13,7 +13,7 @@ aliases: - Complete all the previous sections of this guide, starting with [Containerize a .NET application](containerize.md). -- [Turn on Kubernetes](/desktop/kubernetes/#install-and-turn-on-kubernetes) in Docker +- [Turn on Kubernetes](/manuals/desktop/features/kubernetes.md#install-and-turn-on-kubernetes) in Docker Desktop. ## Overview @@ -220,5 +220,5 @@ In this section, you learned how to use Docker Desktop to deploy your applicatio Related information: - [Kubernetes documentation](https://kubernetes.io/docs/home/) -- [Deploy on Kubernetes with Docker Desktop](/manuals/desktop/kubernetes.md) +- [Deploy on Kubernetes with Docker Desktop](/manuals/desktop/features/kubernetes.md) - [Swarm mode overview](/manuals/engine/swarm/_index.md) diff --git a/content/guides/genai-pdf-bot/containerize.md b/content/guides/genai-pdf-bot/containerize.md index 57dac619b83..eae8f42ae2b 100644 --- a/content/guides/genai-pdf-bot/containerize.md +++ b/content/guides/genai-pdf-bot/containerize.md @@ -12,7 +12,7 @@ aliases: > [!NOTE] > -> GenAI applications can often benefit from GPU acceleration. Currently Docker Desktop supports GPU acceleration only on [Windows with the WSL2 backend](/manuals/desktop/gpu.md#using-nvidia-gpus-with-wsl2). Linux users can also access GPU acceleration using a native installation of the [Docker Engine](/manuals/engine/install/_index.md). +> GenAI applications can often benefit from GPU acceleration. Currently Docker Desktop supports GPU acceleration only on [Windows with the WSL2 backend](/manuals/desktop/features/gpu.md#using-nvidia-gpus-with-wsl2). Linux users can also access GPU acceleration using a native installation of the [Docker Engine](/manuals/engine/install/_index.md). - You have installed the latest version of [Docker Desktop](/get-started/get-docker.md) or, if you are a Linux user and are planning to use GPU acceleration, [Docker Engine](/manuals/engine/install/_index.md). Docker adds new features regularly and some parts of this guide may work only with the latest version of Docker Desktop. - You have a [git client](https://git-scm.com/downloads). The examples in this section use a command-line based git client, but you can use any client. diff --git a/content/guides/genai-pdf-bot/develop.md b/content/guides/genai-pdf-bot/develop.md index b8a5a9ba591..7a0dcae854e 100644 --- a/content/guides/genai-pdf-bot/develop.md +++ b/content/guides/genai-pdf-bot/develop.md @@ -107,7 +107,7 @@ To run Ollama in a container and provide GPU access: 1. Install the prerequisites. - For Docker Engine on Linux, install the [NVIDIA Container Toolkit](https://github.com/NVIDIA/nvidia-container-toolkit). - - For Docker Desktop on Windows 10/11, install the latest [NVIDIA driver](https://www.nvidia.com/Download/index.aspx) and make sure you are using the [WSL2 backend](/manuals/desktop/wsl/_index.md#turn-on-docker-desktop-wsl-2) + - For Docker Desktop on Windows 10/11, install the latest [NVIDIA driver](https://www.nvidia.com/Download/index.aspx) and make sure you are using the [WSL2 backend](/manuals/desktop/features/wsl/_index.md#turn-on-docker-desktop-wsl-2) 2. Add the Ollama service and a volume in your `compose.yaml`. The following is the updated `compose.yaml`: diff --git a/content/guides/gha.md b/content/guides/gha.md new file mode 100644 index 00000000000..04e7d497e3f --- /dev/null +++ b/content/guides/gha.md @@ -0,0 +1,255 @@ +--- +title: Introduction to GitHub Actions with Docker +linkTitle: GitHub Actions and Docker +summary: | + Learn how to automate image build and push with GitHub Actions. +params: + tags: [devops] + time: 10 minutes +--- + +This guide provides an introduction to building CI pipelines using Docker and +GitHub Actions. You will learn how to use Docker's official GitHub Actions to +build your application as a Docker image and push it to Docker Hub. By the end +of the guide, you'll have a simple, functional GitHub Actions configuration for +Docker builds. Use it as-is, or extend it further to fit your needs. + +## Prerequisites + +If you want to follow along with the guide, ensure you have the following: + +- A Docker account. +- Familiarity with Dockerfiles. + +This guide assumes basic knowledge of Docker concepts but provides explanations +for using Docker in GitHub Actions workflows. + +## Get the sample app + +This guide is project-agnostic and assumes you have an application with a +Dockerfile. + +If you need a sample project to follow along, you can use [this sample +application](https://github.com/dvdksn/rpg-name-generator.git), which includes +a Dockerfile for building a containerized version of the app. Alternatively, +use your own GitHub project or create a new repository from the template. + +{{% dockerfile.inline %}} + +{{ $data := resources.GetRemote "https://raw.githubusercontent.com/dvdksn/rpg-name-generator/refs/heads/main/Dockerfile" }} + +```dockerfile {collapse=true} +{{ $data.Content }} +``` + +{{% /dockerfile.inline %}} + +## Configure your GitHub repository + +The workflow in this guide pushes the image you build to Docker Hub. To do +that, you must authenticate with your Docker credentials (username and access +token) as part of the GitHub Actions workflow. + +For instructions on how to create a Docker access token, see +[Create and manage access tokens](/manuals/security/for-developers/access-tokens.md). + +Once you have your Docker credentials ready, add the credentials to your GitHub +repository so you can use them in GitHub Actions: + +1. Open your repository's **Settings**. +2. Under **Security**, go to **Secrets and variables > Actions**. +3. Under **Secrets**, create a new repository secret named `DOCKER_PASSWORD`, + containing your Docker access token. +4. Next, under **Variables**, create a `DOCKER_USERNAME` repository variable + containing your Docker Hub username. + +## Set up your GitHub Actions workflow + +GitHub Actions workflows define a series of steps to automate tasks, such as +building and pushing Docker images, in response to triggers like commits or +pull requests. In this guide, the workflow focuses on automating Docker builds +and testing, ensuring your containerized application works correctly before +publishing it. + +Create a file named `docker-ci.yml` in the `.github/workflows/` directory of +your repository. Start with the basic workflow configuration: + +```yaml +name: Build and Push Docker Image + +on: + push: + branches: + - main + pull_request: +``` + +This configuration runs the workflow on pushes to the main branch and on pull +requests. By including both triggers, you can ensure that the image builds +correctly for a pull request before it's merged. + +## Extract metadata for tags and annotations + +For the first step in your workflow, use the `docker/metadata-action` to +generate metadata for your image. This action extracts information about your +Git repository, such as branch names and commit SHAs, and generates image +metadata such as tags and annotations. + +Add the following YAML to your workflow file: + +```yaml +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Extract Docker image metadata + id: meta + uses: docker/metadata-action@v5 + with: + images: ${{ vars.DOCKER_USERNAME }}/my-image +``` + +These steps prepare metadata to tag and annotate your images during the build +and push process. + +- The **Checkout** step clones the Git repository. +- The **Extract Docker image metadata** step extracts Git metadata and + generates image tags and annotations for the Docker build. + +## Authenticate to your registry + +Before you build the image, authenticate to your registry to ensure that you +can push your built image to the registry. + +To authenticate with Docker Hub, add the following step to your workflow: + +```yaml + - name: Log in to Docker Hub + uses: docker/login-action@v3 + with: + username: ${{ vars.DOCKER_USERNAME }} + password: ${{ secrets.DOCKER_PASSWORD }} +``` + +This step uses the Docker credentials [configured in the repository settings](#configure-your-github-repository). + +## Build and push the image + +Finally, build the final production image and push it to your registry. The +following configuration builds the image and pushes it directly to a registry. + +```yaml + - name: Build and push Docker image + uses: docker/build-push-action@v6 + with: + push: ${{ github.event_name != 'pull_request' }} + tags: ${{ steps.meta.outputs.tags }} + annotations: ${{ steps.meta.outputs.annotations }} +``` + +In this configuration: + +- `push: ${{ github.event_name != 'pull_request' }}` ensures that images are + only pushed when the event is not a pull request. This way, the workflow + builds and tests images for pull requests but only pushes images for commits + to the main branch. +- `tags` and `annotations` use the outputs from the metadata action to apply + consistent tags and [annotations](/manuals/build/metadata/annotations.md) to + the image automatically. + +## Attestations + +SBOM (Software Bill of Materials) and provenance attestations improve security +and traceability, ensuring your images meet modern software supply chain +requirements. + +With a small amount of additional configuration, you can configure +`docker/build-push-action` to generate Software Bill of Materials (SBOM) and +provenance attestations for the image, at build-time. + +To generate this additional metadata, you need to make two changes to your +workflow: + +- Before the build step, add a step that uses `docker/setup-buildx-action`. + This action configures your Docker build client with additional capabilities + that the default client doesn't support. +- Then, update the **Build and push Docker image** step to also enable SBOM and + provenance attestations. + +Here's the updated snippet: + +```yaml + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + + - name: Build and push Docker image + uses: docker/build-push-action@v6 + with: + push: ${{ github.event_name != 'pull_request' }} + tags: ${{ steps.meta.outputs.tags }} + annotations: ${{ steps.meta.outputs.annotations }} + provenance: true + sbom: true +``` + +For more details about attestations, refer to +[the documentation](/manuals/build/metadata/attestations/_index.md). + +## Conclusion + +With all the steps outlined in the previous section, here's the full workflow +configuration: + +```yaml +name: Build and Push Docker Image + +on: + push: + branches: + - main + pull_request: + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Extract Docker image metadata + id: meta + uses: docker/metadata-action@v5 + with: + images: ${{ vars.DOCKER_USERNAME }}/my-image + + - name: Log in to Docker Hub + uses: docker/login-action@v3 + with: + username: ${{ vars.DOCKER_USERNAME }} + password: ${{ secrets.DOCKER_PASSWORD }} + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + + - name: Build and push Docker image + uses: docker/build-push-action@v6 + with: + push: ${{ github.event_name != 'pull_request' }} + tags: ${{ steps.meta.outputs.tags }} + annotations: ${{ steps.meta.outputs.annotations }} + provenance: true + sbom: true +``` + +This workflow implements best practices for building and pushing Docker images +using GitHub Actions. This configuration can be used as-is or extended with +additional features based on your project's needs, such as +[multi-platform](/manuals/build/building/multi-platform.md). + +### Further reading + +- Learn more about advanced configurations and examples in the [Docker Build GitHub Actions](/manuals/build/ci/github-actions/_index.md) section. +- For more complex build setups, you may want to consider [Bake](/manuals/build/bake/_index.md). (See also the [Mastering Buildx Bake guide](/guides/bake/index.md).) +- Learn about Docker's managed build service, designed for faster, multi-platform builds, see [Docker Build Cloud](/guides/docker-build-cloud/_index.md). diff --git a/content/guides/golang/configure-ci-cd.md b/content/guides/golang/configure-ci-cd.md index 09a2adbdc53..5ef7d63a19f 100644 --- a/content/guides/golang/configure-ci-cd.md +++ b/content/guides/golang/configure-ci-cd.md @@ -85,8 +85,10 @@ to Docker Hub. with: username: ${{ vars.DOCKER_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} + - name: Set up Docker Buildx uses: docker/setup-buildx-action@v3 + - name: Build and push uses: docker/build-push-action@v6 with: @@ -122,7 +124,8 @@ In this section, you learned how to set up a GitHub Actions workflow for your ap Related information: -- [Introduction to GitHub Actions](/manuals/build/ci/github-actions/_index.md) +- [Introduction to GitHub Actions](/guides/gha.md) +- [Docker Build GitHub Actions](/manuals/build/ci/github-actions/_index.md) - [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions) ## Next steps diff --git a/content/guides/golang/deploy.md b/content/guides/golang/deploy.md index 02c9e740c15..0b47f0ebc9c 100644 --- a/content/guides/golang/deploy.md +++ b/content/guides/golang/deploy.md @@ -13,7 +13,7 @@ aliases: - Complete all the previous sections of this guide, starting with [Build your Go image](build-images.md). -- [Turn on Kubernetes](/desktop/kubernetes/#install-and-turn-on-kubernetes) in Docker +- [Turn on Kubernetes](/manuals/desktop/features/kubernetes.md#install-and-turn-on-kubernetes) in Docker Desktop. ## Overview @@ -245,5 +245,5 @@ In this section, you learned how to use Docker Desktop to deploy your applicatio Related information: - [Kubernetes documentation](https://kubernetes.io/docs/home/) -- [Deploy on Kubernetes with Docker Desktop](/manuals/desktop/kubernetes.md) +- [Deploy on Kubernetes with Docker Desktop](/manuals/desktop/features/kubernetes.md) - [Swarm mode overview](/manuals/engine/swarm/_index.md) diff --git a/content/guides/images/c-sharp.webp b/content/guides/images/c-sharp.webp deleted file mode 100644 index 7f373ae1df7..00000000000 Binary files a/content/guides/images/c-sharp.webp and /dev/null differ diff --git a/content/guides/images/cpp.webp b/content/guides/images/cpp.webp deleted file mode 100644 index 0582cf58830..00000000000 Binary files a/content/guides/images/cpp.webp and /dev/null differ diff --git a/content/guides/images/golang.webp b/content/guides/images/golang.webp deleted file mode 100644 index 1c84f8a6b0b..00000000000 Binary files a/content/guides/images/golang.webp and /dev/null differ diff --git a/content/guides/images/java.webp b/content/guides/images/java.webp deleted file mode 100644 index 6aeda48d6ef..00000000000 Binary files a/content/guides/images/java.webp and /dev/null differ diff --git a/content/guides/images/nodejs.webp b/content/guides/images/nodejs.webp deleted file mode 100644 index 607b2b33968..00000000000 Binary files a/content/guides/images/nodejs.webp and /dev/null differ diff --git a/content/guides/images/php-logo.webp b/content/guides/images/php-logo.webp deleted file mode 100644 index 91ca4c16b82..00000000000 Binary files a/content/guides/images/php-logo.webp and /dev/null differ diff --git a/content/guides/images/python.webp b/content/guides/images/python.webp deleted file mode 100644 index 0f2a3ab8fdb..00000000000 Binary files a/content/guides/images/python.webp and /dev/null differ diff --git a/content/guides/images/ruby-on-rails.webp b/content/guides/images/ruby-on-rails.webp deleted file mode 100644 index c5c32ac545b..00000000000 Binary files a/content/guides/images/ruby-on-rails.webp and /dev/null differ diff --git a/content/guides/images/rust-logo.webp b/content/guides/images/rust-logo.webp deleted file mode 100644 index b66d6ff4e1e..00000000000 Binary files a/content/guides/images/rust-logo.webp and /dev/null differ diff --git a/content/guides/java/configure-ci-cd.md b/content/guides/java/configure-ci-cd.md index 370bf89b745..554a02f0670 100644 --- a/content/guides/java/configure-ci-cd.md +++ b/content/guides/java/configure-ci-cd.md @@ -88,13 +88,16 @@ to Docker Hub. with: username: ${{ vars.DOCKER_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} + - name: Set up Docker Buildx uses: docker/setup-buildx-action@v3 + - name: Build and test uses: docker/build-push-action@v6 with: target: test load: true + - name: Build and push uses: docker/build-push-action@v6 with: @@ -131,7 +134,8 @@ In this section, you learned how to set up a GitHub Actions workflow for your ap Related information: -- [Introduction to GitHub Actions](/manuals/build/ci/github-actions/_index.md) +- [Introduction to GitHub Actions](/guides/gha.md) +- [Docker Build GitHub Actions](/manuals/build/ci/github-actions/_index.md) - [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions) ## Next steps diff --git a/content/guides/java/deploy.md b/content/guides/java/deploy.md index 86e144c526c..092998d20b8 100644 --- a/content/guides/java/deploy.md +++ b/content/guides/java/deploy.md @@ -12,7 +12,7 @@ aliases: ## Prerequisites - Complete all the previous sections of this guide, starting with [Containerize your app](containerize.md). -- [Turn on Kubernetes](/desktop/kubernetes/#install-and-turn-on-kubernetes) in Docker Desktop. +- [Turn on Kubernetes](/manuals/desktop/features/kubernetes.md#install-and-turn-on-kubernetes) in Docker Desktop. ## Overview @@ -151,5 +151,5 @@ In this section, you learned how to use Docker Desktop to deploy your applicatio Related information: - [Kubernetes documentation](https://kubernetes.io/docs/home/) -- [Deploy on Kubernetes with Docker Desktop](/manuals/desktop/kubernetes.md) +- [Deploy on Kubernetes with Docker Desktop](/manuals/desktop/features/kubernetes.md) - [Swarm mode overview](/manuals/engine/swarm/_index.md) diff --git a/content/guides/jupyter.md b/content/guides/jupyter.md index 67ea349f21a..3f78c73a785 100644 --- a/content/guides/jupyter.md +++ b/content/guides/jupyter.md @@ -382,7 +382,7 @@ $ docker run --rm -p 8889:8888 YOUR-USER-NAME/my-jupyter-image start-notebook.py ### Share your volume -This example uses the Docker Desktop graphical user interface. Alternatively, in the command line interface you can [back up the volume](/engine/storage/volumes/#back-up-a-volume) and then [push it using the ORAS CLI](/manuals/docker-hub/oci-artifacts.md#push-a-volume). +This example uses the Docker Desktop graphical user interface. Alternatively, in the command line interface you can [back up the volume](/engine/storage/volumes/#back-up-a-volume) and then [push it using the ORAS CLI](/manuals/docker-hub/repos/manage/hub-images/oci-artifacts.md#push-a-volume). 1. Sign in to Docker Desktop. 2. In the Docker Dashboard, select **Volumes**. diff --git a/content/guides/language-translation.md b/content/guides/language-translation.md index f71c46e7a2a..64ad491c935 100644 --- a/content/guides/language-translation.md +++ b/content/guides/language-translation.md @@ -315,7 +315,7 @@ To run the application using Docker: > > For Windows users, you may get an error when running the container. Verify > that the line endings in the `entrypoint.sh` are `LF` (`\n`) and not `CRLF` (`\r\n`), - > then rebuild the image. For more details, see [Avoid unexpected syntax errors, use Unix style line endings for files in containers](/desktop/troubleshoot/topics/#avoid-unexpected-syntax-errors-use-unix-style-line-endings-for-files-in-containers). + > then rebuild the image. For more details, see [Avoid unexpected syntax errors, use Unix style line endings for files in containers](/desktop/troubleshoot-and-support/troubleshoot/topics/#avoid-unexpected-syntax-errors-use-unix-style-line-endings-for-files-in-containers). You will see the following in your console after the container starts. diff --git a/content/guides/localstack.md b/content/guides/localstack.md index aca2020ce88..856225f3de1 100644 --- a/content/guides/localstack.md +++ b/content/guides/localstack.md @@ -224,47 +224,47 @@ Now that you have learnt how to connect a non-containerized Node.js application ```yaml services: - backend: - build: - context: ./backend - dockerfile: Dockerfile - ports: - - 5000:5000 - depends_on: - - localstack - - mongodb - env_file: - - backend/.env - - frontend: - build: - context: ./frontend - dockerfile: Dockerfile - ports: - - 5173:5173 - depends_on: - - backend - environment: - - REACT_APP_API_URL=http://backend:5000/api - - mongodb: - image: mongo - container_name: mongodb - volumes: - - mongodbdata:/data/db - ports: - - 27017:27017 - - localstack: - image: localstack/localstack - container_name: localstack - ports: - - 4566:4566 - environment: - - SERVICES=s3 - - GATEWAY_LISTEN=0.0.0.0:4566 - volumes: - - ./localstack:/docker-entrypoint-initaws.d" + backend: + build: + context: ./backend + dockerfile: Dockerfile + ports: + - 5000:5000 + depends_on: + - localstack + - mongodb + env_file: + - backend/.env + + frontend: + build: + context: ./frontend + dockerfile: Dockerfile + ports: + - 5173:5173 + depends_on: + - backend + environment: + - REACT_APP_API_URL=http://backend:5000/api + + mongodb: + image: mongo + container_name: mongodb + volumes: + - mongodbdata:/data/db + ports: + - 27017:27017 + + localstack: + image: localstack/localstack + container_name: localstack + ports: + - 4566:4566 + environment: + - SERVICES=s3 + - GATEWAY_LISTEN=0.0.0.0:4566 + volumes: + - ./localstack:/docker-entrypoint-initaws.d" volumes: mongodbdata: diff --git a/content/guides/named-entity-recognition.md b/content/guides/named-entity-recognition.md index 916810166b0..8c5e087c072 100644 --- a/content/guides/named-entity-recognition.md +++ b/content/guides/named-entity-recognition.md @@ -318,7 +318,7 @@ To run the application using Docker: > > For Windows users, you may get an error when running the container. Verify > that the line endings in the `entrypoint.sh` are `LF` (`\n`) and not `CRLF` (`\r\n`), - > then rebuild the image. For more details, see [Avoid unexpected syntax errors, use Unix style line endings for files in containers](/desktop/troubleshoot/topics/#avoid-unexpected-syntax-errors-use-unix-style-line-endings-for-files-in-containers). + > then rebuild the image. For more details, see [Avoid unexpected syntax errors, use Unix style line endings for files in containers](/desktop/troubleshoot-and-support/troubleshoot/topics/#avoid-unexpected-syntax-errors-use-unix-style-line-endings-for-files-in-containers). You will see the following in your console after the container starts. diff --git a/content/guides/nodejs/configure-ci-cd.md b/content/guides/nodejs/configure-ci-cd.md index a71a62ad9a0..b1215aff478 100644 --- a/content/guides/nodejs/configure-ci-cd.md +++ b/content/guides/nodejs/configure-ci-cd.md @@ -85,17 +85,20 @@ to Docker Hub. with: username: ${{ vars.DOCKER_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} + - name: Set up Docker Buildx uses: docker/setup-buildx-action@v3 + - name: Build and test uses: docker/build-push-action@v6 with: target: test load: true + - name: Build and push uses: docker/build-push-action@v6 with: - platforms: linux/amd64,linux/arm64/v8 + platforms: linux/amd64,linux/arm64 push: true target: prod tags: ${{ vars.DOCKER_USERNAME }}/${{ github.event.repository.name }}:latest @@ -128,7 +131,8 @@ In this section, you learned how to set up a GitHub Actions workflow for your No Related information: -- [Introduction to GitHub Actions](/manuals/build/ci/github-actions/_index.md) +- [Introduction to GitHub Actions](/guides/gha.md) +- [Docker Build GitHub Actions](/manuals/build/ci/github-actions/_index.md) - [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions) ## Next steps diff --git a/content/guides/nodejs/deploy.md b/content/guides/nodejs/deploy.md index 3c6af6e61f2..5c6ca2960b8 100644 --- a/content/guides/nodejs/deploy.md +++ b/content/guides/nodejs/deploy.md @@ -12,7 +12,7 @@ aliases: ## Prerequisites - Complete all the previous sections of this guide, starting with [Containerize a Node.js application](containerize.md). -- [Turn on Kubernetes](/desktop/kubernetes/#install-and-turn-on-kubernetes) in Docker Desktop. +- [Turn on Kubernetes](/manuals/desktop/features/kubernetes.md#install-and-turn-on-kubernetes) in Docker Desktop. ## Overview @@ -139,5 +139,5 @@ In this section, you learned how to use Docker Desktop to deploy your applicatio Related information: - [Kubernetes documentation](https://kubernetes.io/docs/home/) -- [Deploy on Kubernetes with Docker Desktop](/manuals/desktop/kubernetes.md) +- [Deploy on Kubernetes with Docker Desktop](/manuals/desktop/features/kubernetes.md) - [Swarm mode overview](/manuals/engine/swarm/_index.md) diff --git a/content/guides/php/configure-ci-cd.md b/content/guides/php/configure-ci-cd.md index 0c94ff1bb13..ba6319e3767 100644 --- a/content/guides/php/configure-ci-cd.md +++ b/content/guides/php/configure-ci-cd.md @@ -93,13 +93,16 @@ to Docker Hub. with: username: ${{ vars.DOCKER_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} + - name: Set up Docker Buildx uses: docker/setup-buildx-action@v3 + - name: Build and test uses: docker/build-push-action@v6 with: target: test load: true + - name: Build and push uses: docker/build-push-action@v6 with: @@ -136,7 +139,8 @@ In this section, you learned how to set up a GitHub Actions workflow for your ap Related information: -- [Introduction to GitHub Actions](/manuals/build/ci/github-actions/_index.md) +- [Introduction to GitHub Actions](/guides/gha.md) +- [Docker Build GitHub Actions](/manuals/build/ci/github-actions/_index.md) - [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions) ## Next steps diff --git a/content/guides/php/deploy.md b/content/guides/php/deploy.md index b0f9e14bf9c..e6b96660db7 100644 --- a/content/guides/php/deploy.md +++ b/content/guides/php/deploy.md @@ -13,7 +13,7 @@ aliases: - Complete all the previous sections of this guide, starting with [Containerize a PHP application](containerize.md). -- [Turn on Kubernetes](/desktop/kubernetes/#install-and-turn-on-kubernetes) in Docker +- [Turn on Kubernetes](/manuals/desktop/features/kubernetes.md#install-and-turn-on-kubernetes) in Docker Desktop. ## Overview @@ -142,5 +142,5 @@ In this section, you learned how to use Docker Desktop to deploy your applicatio Related information: - [Kubernetes documentation](https://kubernetes.io/docs/home/) -- [Deploy on Kubernetes with Docker Desktop](/manuals/desktop/kubernetes.md) +- [Deploy on Kubernetes with Docker Desktop](/manuals/desktop/features/kubernetes.md) - [Swarm mode overview](/manuals/engine/swarm/_index.md) diff --git a/content/guides/python/configure-ci-cd.md b/content/guides/python/configure-ci-cd.md index 4d61495f0fa..e82d06945dc 100644 --- a/content/guides/python/configure-ci-cd.md +++ b/content/guides/python/configure-ci-cd.md @@ -85,8 +85,10 @@ to Docker Hub. with: username: ${{ vars.DOCKER_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} + - name: Set up Docker Buildx uses: docker/setup-buildx-action@v3 + - name: Build and push uses: docker/build-push-action@v6 with: @@ -122,7 +124,8 @@ In this section, you learned how to set up a GitHub Actions workflow for your Py Related information: -- [Introduction to GitHub Actions](/manuals/build/ci/github-actions/_index.md) +- [Introduction to GitHub Actions](/guides/gha.md) +- [Docker Build GitHub Actions](/manuals/build/ci/github-actions/_index.md) - [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions) ## Next steps diff --git a/content/guides/python/deploy.md b/content/guides/python/deploy.md index d071722d471..bec86653b92 100644 --- a/content/guides/python/deploy.md +++ b/content/guides/python/deploy.md @@ -12,7 +12,7 @@ aliases: ## Prerequisites - Complete all the previous sections of this guide, starting with [Use containers for python development](develop.md). -- [Turn on Kubernetes](/desktop/kubernetes/#install-and-turn-on-kubernetes) in Docker Desktop. +- [Turn on Kubernetes](/manuals/desktop/features/kubernetes.md#install-and-turn-on-kubernetes) in Docker Desktop. ## Overview @@ -115,7 +115,7 @@ spec: spec: containers: - name: fastapi-service - image: technox64/python-docker-dev-example-test:latest + image: DOCKER_USERNAME/REPO_NAME imagePullPolicy: Always env: - name: POSTGRES_PASSWORD @@ -253,5 +253,5 @@ In this section, you learned how to use Docker Desktop to deploy your applicatio Related information: - [Kubernetes documentation](https://kubernetes.io/docs/home/) -- [Deploy on Kubernetes with Docker Desktop](/manuals/desktop/kubernetes.md) +- [Deploy on Kubernetes with Docker Desktop](/manuals/desktop/features/kubernetes.md) - [Swarm mode overview](/manuals/engine/swarm/_index.md) diff --git a/content/guides/r/configure-ci-cd.md b/content/guides/r/configure-ci-cd.md index 2c7ebf6031c..8e2465d2712 100644 --- a/content/guides/r/configure-ci-cd.md +++ b/content/guides/r/configure-ci-cd.md @@ -85,8 +85,10 @@ to Docker Hub. with: username: ${{ vars.DOCKER_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} + - name: Set up Docker Buildx uses: docker/setup-buildx-action@v3 + - name: Build and push uses: docker/build-push-action@v6 with: @@ -122,7 +124,8 @@ In this section, you learned how to set up a GitHub Actions workflow for your R Related information: -- [Introduction to GitHub Actions](/manuals/build/ci/github-actions/_index.md) +- [Introduction to GitHub Actions](/guides/gha.md) +- [Docker Build GitHub Actions](/manuals/build/ci/github-actions/_index.md) - [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions) ## Next steps diff --git a/content/guides/r/deploy.md b/content/guides/r/deploy.md index e24e8350e81..6aa8c4aba51 100644 --- a/content/guides/r/deploy.md +++ b/content/guides/r/deploy.md @@ -12,7 +12,7 @@ aliases: ## Prerequisites - Complete all the previous sections of this guide, starting with [Containerize a R application](containerize.md). -- [Turn on Kubernetes](/desktop/kubernetes/#install-and-turn-on-kubernetes) in Docker Desktop. +- [Turn on Kubernetes](/manuals/desktop/features/kubernetes.md#install-and-turn-on-kubernetes) in Docker Desktop. ## Overview @@ -143,5 +143,5 @@ In this section, you learned how to use Docker Desktop to deploy your applicatio Related information: - [Kubernetes documentation](https://kubernetes.io/docs/home/) -- [Deploy on Kubernetes with Docker Desktop](/manuals/desktop/kubernetes.md) +- [Deploy on Kubernetes with Docker Desktop](/manuals/desktop/features/kubernetes.md) - [Swarm mode overview](/manuals/engine/swarm/_index.md) diff --git a/content/guides/rag-ollama/develop.md b/content/guides/rag-ollama/develop.md index 8d2ee554222..280da329577 100644 --- a/content/guides/rag-ollama/develop.md +++ b/content/guides/rag-ollama/develop.md @@ -81,7 +81,7 @@ To run Ollama in a container and provide GPU access: 1. Install the prerequisites. - For Docker Engine on Linux, install the [NVIDIA Container Toolkilt](https://github.com/NVIDIA/nvidia-container-toolkit). - - For Docker Desktop on Windows 10/11, install the latest [NVIDIA driver](https://www.nvidia.com/Download/index.aspx) and make sure you are using the [WSL2 backend](/manuals/desktop/wsl/_index.md#turn-on-docker-desktop-wsl-2) + - For Docker Desktop on Windows 10/11, install the latest [NVIDIA driver](https://www.nvidia.com/Download/index.aspx) and make sure you are using the [WSL2 backend](/manuals/desktop/features/wsl/_index.md#turn-on-docker-desktop-wsl-2) 2. The `docker-compose.yaml` file already contains the necessary instructions. In your own apps, you'll need to add the Ollama service in your `docker-compose.yaml`. The following is the updated `docker-compose.yaml`: diff --git a/content/guides/ruby/configure-ci-cd.md b/content/guides/ruby/configure-ci-cd.md index 9b81c5ec57d..b4a440519b7 100644 --- a/content/guides/ruby/configure-ci-cd.md +++ b/content/guides/ruby/configure-ci-cd.md @@ -85,12 +85,13 @@ to Docker Hub. with: username: ${{ vars.DOCKER_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} + - name: Set up Docker Buildx uses: docker/setup-buildx-action@v3 + - name: Build and push uses: docker/build-push-action@v6 with: - platforms: linux/amd64 push: true tags: ${{ vars.DOCKER_USERNAME }}/${{ github.event.repository.name }}:latest ``` @@ -122,7 +123,8 @@ In this section, you learned how to set up a GitHub Actions workflow for your Ru Related information: -- [Introduction to GitHub Actions](/manuals/build/ci/github-actions/_index.md) +- [Introduction to GitHub Actions](/guides/gha.md) +- [Docker Build GitHub Actions](/manuals/build/ci/github-actions/_index.md) - [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions) ## Next steps diff --git a/content/guides/ruby/deploy.md b/content/guides/ruby/deploy.md index 15041550849..d86ef14bd22 100644 --- a/content/guides/ruby/deploy.md +++ b/content/guides/ruby/deploy.md @@ -12,7 +12,7 @@ aliases: ## Prerequisites - Complete all the previous sections of this guide, starting with [Containerize a Ruby on Rails application](containerize.md). -- [Turn on Kubernetes](/desktop/kubernetes/#install-and-turn-on-kubernetes) in Docker Desktop. +- [Turn on Kubernetes](/manuals/desktop/features/kubernetes.md#install-and-turn-on-kubernetes) in Docker Desktop. ## Overview @@ -163,5 +163,5 @@ In this section, you learned how to use Docker Desktop to deploy your applicatio Related information: - [Kubernetes documentation](https://kubernetes.io/docs/home/) -- [Deploy on Kubernetes with Docker Desktop](/manuals/desktop/kubernetes.md) +- [Deploy on Kubernetes with Docker Desktop](/manuals/desktop/features/kubernetes.md) - [Swarm mode overview](/manuals/engine/swarm/_index.md) diff --git a/content/guides/rust/configure-ci-cd.md b/content/guides/rust/configure-ci-cd.md index 5efd4c31cce..027b0b8dcf4 100644 --- a/content/guides/rust/configure-ci-cd.md +++ b/content/guides/rust/configure-ci-cd.md @@ -85,8 +85,10 @@ to Docker Hub. with: username: ${{ vars.DOCKER_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} + - name: Set up Docker Buildx uses: docker/setup-buildx-action@v3 + - name: Build and push uses: docker/build-push-action@v6 with: @@ -121,7 +123,8 @@ In this section, you learned how to set up a GitHub Actions workflow for your Ru Related information: -- [Introduction to GitHub Actions](/manuals/build/ci/github-actions/_index.md) +- [Introduction to GitHub Actions](/guides/gha.md) +- [Docker Build GitHub Actions](/manuals/build/ci/github-actions/_index.md) - [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions) ## Next steps diff --git a/content/guides/rust/deploy.md b/content/guides/rust/deploy.md index 5c6cf703f56..ac48e760ace 100644 --- a/content/guides/rust/deploy.md +++ b/content/guides/rust/deploy.md @@ -12,7 +12,7 @@ aliases: ## Prerequisites - Complete the previous sections of this guide, starting with [Develop your Rust application](develop.md). -- [Turn on Kubernetes](/desktop/kubernetes/#install-and-turn-on-kubernetes) in Docker Desktop. +- [Turn on Kubernetes](/manuals/desktop/features/kubernetes.md#install-and-turn-on-kubernetes) in Docker Desktop. ## Overview @@ -234,5 +234,5 @@ In this section, you learned how to use Docker Desktop to deploy your applicatio Related information: - [Kubernetes documentation](https://kubernetes.io/docs/home/) -- [Deploy on Kubernetes with Docker Desktop](/manuals/desktop/kubernetes.md) +- [Deploy on Kubernetes with Docker Desktop](/manuals/desktop/features/kubernetes.md) - [Swarm mode overview](/manuals/engine/swarm/_index.md) diff --git a/content/guides/rust/develop.md b/content/guides/rust/develop.md index d1baae4c19b..462fc229deb 100644 --- a/content/guides/rust/develop.md +++ b/content/guides/rust/develop.md @@ -12,7 +12,7 @@ aliases: ## Prerequisites - You have installed the latest version of [Docker Desktop](/get-started/get-docker.md). -- You have completed the walkthroughs in the Docker Desktop [Learning Center](/manuals/desktop/get-started.md) to learn about Docker concepts. +- You have completed the walkthroughs in the Docker Desktop [Learning Center](/manuals/desktop/use-desktop/_index.md) to learn about Docker concepts. - You have a [git client](https://git-scm.com/downloads). The examples in this section use a command-line based git client, but you can use any client. ## Overview diff --git a/content/guides/sentiment-analysis.md b/content/guides/sentiment-analysis.md index 751b4c4cd22..ea6f5ab5a41 100644 --- a/content/guides/sentiment-analysis.md +++ b/content/guides/sentiment-analysis.md @@ -331,7 +331,7 @@ To run the application using Docker: > > For Windows users, you may get an error when running the container. Verify > that the line endings in the `entrypoint.sh` are `LF` (`\n`) and not `CRLF` (`\r\n`), - > then rebuild the image. For more details, see [Avoid unexpected syntax errors, use Unix style line endings for files in containers](/desktop/troubleshoot/topics/#avoid-unexpected-syntax-errors-use-unix-style-line-endings-for-files-in-containers). + > then rebuild the image. For more details, see [Avoid unexpected syntax errors, use Unix style line endings for files in containers](/desktop/troubleshoot-and-support/troubleshoot/topics/#avoid-unexpected-syntax-errors-use-unix-style-line-endings-for-files-in-containers). You will see the following in your console after the container starts. diff --git a/content/guides/text-classification.md b/content/guides/text-classification.md index a7fbe274920..6c3e6ee4a8f 100644 --- a/content/guides/text-classification.md +++ b/content/guides/text-classification.md @@ -390,7 +390,7 @@ To run the application using Docker: > > For Windows users, you may get an error when running the container. Verify > that the line endings in the `entrypoint.sh` are `LF` (`\n`) and not `CRLF` (`\r\n`), - > then rebuild the image. For more details, see [Avoid unexpected syntax errors, use Unix style line endings for files in containers](/desktop/troubleshoot/topics/#avoid-unexpected-syntax-errors-use-unix-style-line-endings-for-files-in-containers). + > then rebuild the image. For more details, see [Avoid unexpected syntax errors, use Unix style line endings for files in containers](/desktop/troubleshoot-and-support/troubleshoot/topics/#avoid-unexpected-syntax-errors-use-unix-style-line-endings-for-files-in-containers). You will see the following in your console after the container starts. diff --git a/content/guides/text-summarization.md b/content/guides/text-summarization.md index 4478fb6dd86..ef6cbd290df 100644 --- a/content/guides/text-summarization.md +++ b/content/guides/text-summarization.md @@ -324,7 +324,7 @@ To run the application using Docker: > > For Windows users, you may get an error when running the container. Verify > that the line endings in the `entrypoint.sh` are `LF` (`\n`) and not `CRLF` (`\r\n`), - > then rebuild the image. For more details, see [Avoid unexpected syntax errors, use Unix style line endings for files in containers](/desktop/troubleshoot/topics/#avoid-unexpected-syntax-errors-use-unix-style-line-endings-for-files-in-containers). + > then rebuild the image. For more details, see [Avoid unexpected syntax errors, use Unix style line endings for files in containers](/desktop/troubleshoot-and-support/troubleshoot/topics/#avoid-unexpected-syntax-errors-use-unix-style-line-endings-for-files-in-containers). You will see the following in your console after the container starts. diff --git a/content/guides/zscaler/index.md b/content/guides/zscaler/index.md new file mode 100644 index 00000000000..56c35463d53 --- /dev/null +++ b/content/guides/zscaler/index.md @@ -0,0 +1,141 @@ +--- +title: Using Docker with Zscaler +tags: [networking, admin] +summary: | + This guide explains how to embed Zscaler’s root certificate into Docker + images, allowing containers to operate securely with Zscaler proxies and + avoid SSL errors. +params: + time: 10 minutes +--- + +In many corporate environments, network traffic is intercepted and monitored +using HTTPS proxies, such as Zscaler. While Zscaler ensures security compliance +and network control, it can cause issues for developers using Docker, +particularly during build processes, where SSL certificate validation errors +might occur. This guide outlines how to configure Docker containers and builds +to properly handle Zscaler's custom certificates, ensuring smooth operation in +monitored environments. + +## The role of certificates in Docker + +When Docker builds or runs containers, it often needs to fetch resources from +the internet—whether it's pulling a base image from a registry, downloading +dependencies, or communicating with external services. In a proxied +environment, Zscaler intercepts HTTPS traffic and replaces the remote server's +certificate with its own. However, Docker doesn't trust this Zscaler +certificate by default, leading to SSL errors. + +```plaintext +x509: certificate signed by unknown authority +``` + +These errors occur because Docker cannot verify the validity of the certificate +presented by Zscaler. To avoid this, you must configure Docker to trust +Zscaler's certificate. + +## Configure Zscaler proxy for Docker Desktop + +Depending on how Zscaler is deployed, you may need to configure Docker Desktop +proxy settings manually to use the Zscaler proxy. + +If you're using Zscaler as a system-level proxy via the [Zscaler Client Connector](https://help.zscaler.com/zscaler-client-connector/what-is-zscaler-client-connector), +all traffic on the device is automatically routed through Zscaler, so Docker +Desktop uses the Zscaler proxy automatically with no additional configuration +necessary. + +If you are not using Zscaler as a system-level proxy, manually configure proxy +settings in Docker Desktop. Set up proxy settings for all clients in the +organization using [Settings Management](/manuals/security/for-admins/hardened-desktop/settings-management/_index.md), +or edit proxy configuration in the Docker Desktop GUI under [**Settings > Resources > Proxies**](/manuals/desktop/settings-and-maintenance/settings.md#proxies). + +## Install root certificates in Docker images + +To enable containers to use and trust the Zscaler proxy, embed the certificate +in the image and configure the image's trust store. Installing certificates at +image build time is the preferred approach, as it removes the need for +configuration during startup and provides an auditable, consistent environment. + +### Obtaining the root certificate + +The easiest way to obtain the root certificate is to export it from a machine +where an administrator has already installed it. You can use either a web +browser or the system's certificate management service (for example, Windows +Certificate Store). + +#### Example: Exporting the certificate using Google Chrome + +1. In Google Chrome, navigate to `chrome://certificate-manager/`. +2. Under **Local certificates**, select **View imported certificates**. +3. Find the Zscaler root certificate, often labeled **Zscaler Root CA**. +4. Open the certificate details and select **Export**. +5. Save the certificate in ASCII PEM format. +6. Open the exported file in a text editor to confirm it includes `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----`. + +When you have obtained the certificate, store it in an accessible repository, +such as JFrog Artifactory or a Git repository. Alternatively, use generic +storage like AWS S3. + +### Building with the certificate + +To install these certificates when building images, copy the certificate into +the build container and update the trust store. An example Dockerfile looks +like this: + +```dockerfile +FROM debian:bookworm +COPY zscaler-cert.pem /usr/local/share/ca-certificates/zscaler-cert.pem +RUN apt-get update && \ + apt-get install -y ca-certificates && \ + update-ca-certificates +``` + +Here, `zscaler-cert.pem` is the root certificate, located at the root of the +build context (often within the application's Git repository). + +If you use an artifact repository, you can fetch the certificate directly using +the `ADD` instruction. You can also use the `--checksum` flag to verify that +the content digest of the certificate is correct. + +```dockerfile +FROM debian:bookworm +ADD --checksum=sha256:24454f830cdb571e2c4ad15481119c43b3cafd48dd869a9b2945d1036d1dc68d \ + https://artifacts.example/certs/zscaler-cert.pem /usr/local/share/ca-certificates/zscaler-cert.pem +RUN apt-get update && \ + apt-get install -y ca-certificates && \ + update-ca-certificates +``` + +#### Using multi-stage builds + +For multi-stage builds where certificates are needed in the final runtime +image, ensure the certificate installation occurs in the final stage. + +```dockerfile +FROM debian:bookworm AS build +WORKDIR /build +RUN apt-get update && apt-get install -y \ + build-essential \ + cmake \ + curl \ + git +RUN --mount=target=. cmake -B output/ + +FROM debian:bookworm-slim AS final +ADD --checksum=sha256:24454f830cdb571e2c4ad15481119c43b3cafd48dd869a9b2945d1036d1dc68d \ + https://artifacts.example/certs/zscaler-cert.pem /usr/local/share/ca-certificates/zscaler-cert.pem +RUN apt-get update && \ + apt-get install -y ca-certificates && \ + update-ca-certificates +WORKDIR /app +COPY --from=build /build/output/bin . +ENTRYPOINT ["/app/bin"] +``` + +## Conclusion + +Embedding the Zscaler root certificate directly into your Docker images ensures +that containers run smoothly within Zscaler-proxied environments. By using this +approach, you reduce potential runtime errors and create a consistent, +auditable configuration that allows for smooth Docker operations within a +monitored network. diff --git a/content/includes/aci-ecs-eol.md b/content/includes/aci-ecs-eol.md index 514c11a0da0..b106ceb4386 100644 --- a/content/includes/aci-ecs-eol.md +++ b/content/includes/aci-ecs-eol.md @@ -1,3 +1,3 @@ ->**Important** +> [!IMPORTANT] > ->Docker Compose's integration for ECS and ACI is retiring in November 2023. +> Docker Compose's integration for ECS and ACI is retiring in November 2023. diff --git a/content/includes/admin-company-overview.md b/content/includes/admin-company-overview.md index 194c4bbd7d0..9595e947572 100644 --- a/content/includes/admin-company-overview.md +++ b/content/includes/admin-company-overview.md @@ -8,16 +8,15 @@ The following diagram depicts the setup of a company and how it relates to assoc With a company, administrators can: -- View and manage all nested organizations and configure settings centrally. -- Carefully control access to the company and company settings. -- Have up to ten unique users assigned the company owner role. -- Configure SSO and SCIM for all nested organizations. -- Enforce SSO for all users in the company. +- View and manage all nested organizations and configure settings centrally +- Carefully control access to the company and company settings +- Have up to ten unique users assigned the company owner role +- Configure SSO and SCIM for all nested organizations +- Enforce SSO for all users in the company ## Prerequisites Before you create a company, verify the following: - Any organizations you want to add to a company have a Docker Business subscription -- You're an organization owner -- You're an organization owner for any additional organizations you want to add to the company you create +- You're an organization owner for your organization and any additional organizations you want to add diff --git a/content/includes/deploy.md b/content/includes/deploy.md index 44d9ff2be0f..0512c4418de 100644 --- a/content/includes/deploy.md +++ b/content/includes/deploy.md @@ -25,4 +25,4 @@ To enable Kubernetes: This starts a Kubernetes single-node cluster when Docker Desktop starts. -For detailed information, see [Deploy on Kubernetes](/desktop/kubernetes/) and [Describing apps using Kubernetes YAML](/guides/deployment-orchestration/kube-deploy/#describing-apps-using-kubernetes-yaml). +For detailed information, see [Deploy on Kubernetes](/manuals/desktop/features/kubernetes.md) and [Describing apps using Kubernetes YAML](/guides/deployment-orchestration/kube-deploy/#describing-apps-using-kubernetes-yaml). diff --git a/content/includes/hub-categories.md b/content/includes/hub-categories.md new file mode 100644 index 00000000000..5b2b747b0c4 --- /dev/null +++ b/content/includes/hub-categories.md @@ -0,0 +1,34 @@ +The categories include: + +- **API Management**: Tools for creating, publishing, analyzing, and securing + APIs. +- **Content Management System:** Software applications to create and manage + digital content through templates, procedures, and standard formats. +- **Data Science:** Tools and software to support analyzing data and generating + actionable insights. +- **Databases & Storage:** Systems for storing, retrieving, and managing data. +- **Languages & Frameworks:** Programming language runtimes and frameworks. +- **Integrations & Delivery:** Tools for Continuous Integration (CI) and + Continuous Delivery (CD). +- **Internet of Things:** Tools supporting Internet of Things (IoT) + applications. +- **Machine Learning & AI:** Tools and frameworks optimized for artificial + intelligence and machine learning projects, such as pre-installed libraries + and frameworks for data analysis, model training, and deployment. +- **Message Queues:** Message queuing systems optimized for reliable, scalable, + and efficient message handling. +- **Monitoring & Observability:** Tools to track software and system performance + through metrics, logs, and traces, as well as observability to explore the + system’s state and diagnose issues. +- **Networking:** Repositories that support data exchange and connecting + computers and other devices to share resources. +- **Operating Systems:** Software that manages all other programs on a computer + and serves as an intermediary between users and the computer hardware, while + overseeing applications and system resources. +- **Security:** Tools to protect a computer system or network from theft, + unauthorized access, or damage to their hardware, software, or electronic + data, as well as from service disruption. +- **Web Servers:** Software to serve web pages, HTML files, and other assets to + users or other systems. +- **Web Analytics:** Tools to collect, measure, analyze, and report on web data + and website visitor engagement. \ No newline at end of file diff --git a/content/includes/hub-limits.md b/content/includes/hub-limits.md new file mode 100644 index 00000000000..69373200884 --- /dev/null +++ b/content/includes/hub-limits.md @@ -0,0 +1,8 @@ +--- +--- + +> [!NOTE] +> +> The Docker Hub plan limits will take effect on March 1, 2025. No charges on +> Docker Hub image pulls or storage will be incurred between December 10, 2024, +> and February 28, 2025. \ No newline at end of file diff --git a/content/includes/install-script.md b/content/includes/install-script.md index e0569e63f3a..c273505dbda 100644 --- a/content/includes/install-script.md +++ b/content/includes/install-script.md @@ -30,9 +30,9 @@ of the convenience script: using the script to update an existing installation, dependencies may not be updated to the expected version, resulting in outdated versions. -> **Tip: preview script steps before running** +> [!TIP] > -> You can run the script with the `--dry-run` option to learn what steps the +> Preview script steps before running. You can run the script with the `--dry-run` option to learn what steps the > script will run when invoked: > > ```console diff --git a/content/includes/new-plans.md b/content/includes/new-plans.md deleted file mode 100644 index dec253ec716..00000000000 --- a/content/includes/new-plans.md +++ /dev/null @@ -1,13 +0,0 @@ ---- ---- - -> [!IMPORTANT] -> -> Docker is introducing enhanced subscription plans. Our new plans are packed -> with more features, higher usage limits, and simplified pricing. The new -> subscription plans take effect at your next renewal date that occurs on or -> after November 15, 2024. No charges on Docker Hub image pulls or storage will -> be incurred between November 15, 2024, and January 31, 2025. See [Announcing -> Upgraded Docker -> Plans](https://www.docker.com/blog/november-2024-updated-plans-announcement/) -> for more details and learn how your usage fits into these updates. \ No newline at end of file diff --git a/content/includes/swarm-mode.md b/content/includes/swarm-mode.md index 7a9cc2e1a03..03202e0ee3b 100644 --- a/content/includes/swarm-mode.md +++ b/content/includes/swarm-mode.md @@ -7,4 +7,4 @@ > If you're not planning on deploying with Swarm, use > [Docker Compose](/compose/) instead. > If you're developing for a Kubernetes deployment, consider using the -> [integrated Kubernetes feature](/desktop/kubernetes/) in Docker Desktop. +> [integrated Kubernetes feature](/manuals/desktop/features/kubernetes.md) in Docker Desktop. diff --git a/content/includes/tax-compliance.md b/content/includes/tax-compliance.md index 21aa813db1b..fdada055f3c 100644 --- a/content/includes/tax-compliance.md +++ b/content/includes/tax-compliance.md @@ -1,5 +1,5 @@ > [!IMPORTANT] > -> Starting July 1, 2024, Docker will begin collecting sales tax on subscription fees in compliance with state regulations for customers in the United States. For our global customers subject to VAT, the implementation will start rolling out on July 1, 2024. Note that while the rollout begins on this date, VAT charges may not apply to all applicable subscriptions immediately. +> Starting July 1, 2024, Docker will begin collecting sales tax on subscription fees in compliance with state regulations for customers in the United States. For our global customers subject to VAT, the implementation will start rolling out on July 1, 2024. Note that while the roll out begins on this date, VAT charges may not apply to all applicable subscriptions immediately. > -> To ensure that tax assessments are correct, make sure that your [billing information](/billing/core-billing/details/) and VAT/Tax ID, if applicable, are updated. If you're exempt from sales tax, see [Register a tax certificate](/billing/tax-certificate/). +> To ensure that tax assessments are correct, make sure that your [billing information](/billing/details/) and VAT/Tax ID, if applicable, are updated. If you're exempt from sales tax, see [Register a tax certificate](/billing/tax-certificate/). diff --git a/content/manuals/_index.md b/content/manuals/_index.md index af786bfcf75..31252a51cae 100644 --- a/content/manuals/_index.md +++ b/content/manuals/_index.md @@ -7,16 +7,13 @@ url: /manuals/ layout: wide params: icon: description + sidebar: + groups: + - Open source + - Products + - Platform notoc: true - development: - - title: Docker Desktop - description: Your command center for container development. - icon: /assets/icons/Whale.svg - link: /desktop/ - - title: Docker Compose - description: Define and run multi-container applications. - icon: /assets/icons/Compose.svg - link: /compose/ + open-source: - title: Docker Build description: Build and ship any application anywhere. icon: build @@ -25,11 +22,19 @@ params: description: The industry-leading container runtime. icon: developer_board link: /engine/ - - title: Docker Extensions - description: Customize your Docker Desktop workflow. - icon: extension - link: /extensions/ - services: + - title: Docker Compose + description: Define and run multi-container applications. + icon: /assets/icons/Compose.svg + link: /compose/ + products: + - title: Docker Desktop + description: Your command center for container development. + icon: /assets/icons/Whale.svg + link: /desktop/ + - title: Build Cloud + description: Build your images faster in the cloud. + icon: /assets/images/logo-build-cloud.svg + link: /build-cloud/ - title: Docker Hub description: Discover, share, and integrate container images. icon: hub @@ -38,27 +43,35 @@ params: description: Image analysis and policy evaluation. icon: /assets/icons/Scout.svg link: /scout/ - - title: Trusted content - description: Curated, high-quality content from trusted sources. - icon: verified - link: /trusted-content/ - - title: Build Cloud - description: Build your images faster in the cloud. - icon: /assets/images/logo-build-cloud.svg - link: /build-cloud/ - admin: + - title: Docker for GitHub Copilot + description: Integrate Docker's capabilities with GitHub Copilot. + icon: chat + link: /copilot/ + - title: Docker Extensions + description: Customize your Docker Desktop workflow. + icon: extension + link: /extensions/ + - title: Testcontainers cloud + description: Run integration tests, with real dependencies, in the cloud. + icon: package_2 + link: https://testcontainers.com/cloud/docs/ + platform: - title: Administration description: Centralized observability for companies and organizations. icon: admin_panel_settings link: /admin/ - - title: Security - description: Security guardrails for both administrators and developers. - icon: lock - link: /security/ - title: Billing description: Manage billing and payment methods. icon: payments link: /billing/ + - title: Accounts + description: Manage your Docker account. + icon: account_circle + link: /accounts/ + - title: Security + description: Security guardrails for both administrators and developers. + icon: lock + link: /security/ - title: Subscription description: Commercial use licenses for Docker products. icon: card_membership @@ -68,20 +81,21 @@ params: This section contains user guides on how to install, set up, configure, and use Docker products. -## Developer tools +## Open source -Software development and containerization technologies. +Open source development and containerization technologies. -{{< grid items=development >}} +{{< grid items=open-source >}} -## Services +## Products -Artifact management and supply chain security. +End-to-end developer solutions for innovative teams. -{{< grid items=services >}} +{{< grid items=products >}} -## Administration and accounts +## Platform -Administration and subscription management for organizations. +Documentation related to the Docker platform, such as administration and +subscription management for organizations. -{{< grid items=admin >}} +{{< grid items=platform >}} diff --git a/content/manuals/accounts/_index.md b/content/manuals/accounts/_index.md index ae9594d7ba3..6da49ef20b4 100644 --- a/content/manuals/accounts/_index.md +++ b/content/manuals/accounts/_index.md @@ -1,9 +1,10 @@ --- -title: Docker account overview -linkTitle: Docker accounts -weight: 200 +title: Docker accounts description: Learn how to create and manage your Docker account. keywords: accounts, docker ID, account management, account settings, docker account, docker home +params: + sidebar: + group: Platform grid: - title: Create a Docker ID description: Get started with Docker and create an account. diff --git a/content/manuals/accounts/create-account.md b/content/manuals/accounts/create-account.md index 1780b4ec138..746c7f13277 100644 --- a/content/manuals/accounts/create-account.md +++ b/content/manuals/accounts/create-account.md @@ -15,7 +15,7 @@ Your Docker ID becomes your username for hosted Docker services, and [Docker for > [!TIP] > -> Explore [Docker's core subscriptions](https://www.docker.com/pricing/) to see what else Docker can offer you. +> Explore [Docker's subscriptions](https://www.docker.com/pricing/) to see what else Docker can offer you. ## Create a Docker ID @@ -25,27 +25,29 @@ Your Docker ID becomes your username for hosted Docker services, and [Docker for 2. Enter a unique, valid email address. -3. Enter a username. +3. Enter a username to use as your Docker ID. Once you create your Docker ID you can't reuse it in the future if you deactivate this account. - Your Docker ID must be between 4 and 30 characters long, and can only contain numbers and lowercase letters. Once you create your Docker ID you can't reuse it in the future if you deactivate this account. + Your username: + - Must be between 4 and 30 characters long + - Can only contain numbers and lowercase letters 4. Enter a password that's at least 9 characters long. 5. Select **Sign Up**. - Docker sends a verification email to the address you provided. +6. Open your email client. Docker sends a verification email to the address you provided. -6. Verify your email address to complete the registration process. +7. Verify your email address to complete the registration process. > [!NOTE] > -> You have limited actions available until you verify your email address. +> You must verify your email address before you have full access to Docker's features. ### Sign up with Google or GitHub > [!IMPORTANT] > -> To sign up with your social provider, make sure you verify your email address with your provider before you begin. +> To sign up with your social provider, you must verify your email address with your provider before you begin. 1. Go to the [Docker sign-up page](https://app.docker.com/signup/). @@ -53,34 +55,37 @@ Your Docker ID becomes your username for hosted Docker services, and [Docker for 3. Select the social account you want to link to your Docker account. -4. Select **Authorize Docker** to allow Docker to access your social account information and be re-routed to the sign-up page. +4. Select **Authorize Docker** to let Docker to access your social account information. You will be re-routed to the sign-up page. -5. Enter a username. +5. Enter a username to use as your Docker ID. - Your Docker ID must be between 4 and 30 characters long, and can only contain numbers and lowercase letters. Once you create your Docker ID you can't reuse it in the future if you deactivate this account. + Your username: + - Must be between 4 and 30 characters long + - Can only contain numbers and lowercase letters 6. Select **Sign up**. ## Sign in -Once you register and verify your Docker ID email address, you can sign in to [your Docker account](https://login.docker.com/u/login/). You can sign in with your email address (or username) and password. Or, you can sign in with your social provider. See [Sign in with your social provider](#sign-in-with-your-social-provider). - -You can also sign in through the CLI using the `docker login` command. For more information, see [`docker login`](/reference/cli/docker/login.md). +Once you register your Docker ID and verify your email address, you can sign in to [your Docker account](https://login.docker.com/u/login/). You can either: +- Sign in with your email address (or username) and password. +- Sign in with your social provider. For more information, see [Sign in with your social provider](#sign-in-with-your-social-provider). +- Sign in through the CLI using the `docker login` command. For more information, see [`docker login`](/reference/cli/docker/login.md). > [!WARNING] > > When you use the `docker login` command, your credentials are stored in your home directory in `.docker/config.json`. The password is base64-encoded in this file. > -> We recommend using one of the [Docker credential helpers](https://github.com/docker/docker-credential-helpers) for secure storage of passwords. For extra security, you can also use a [personal access token](../security/for-developers/access-tokens.md) to log in instead, which is still encoded in this file (without a Docker credential helper) but doesn't allow admin actions (such as changing the password). +> We recommend using one of the [Docker credential helpers](https://github.com/docker/docker-credential-helpers) for secure storage of passwords. For extra security, you can also use a [personal access token](../security/for-developers/access-tokens.md) to sign in instead, which is still encoded in this file (without a Docker credential helper) but doesn't permit administrator actions (such as changing the password). ### Sign in with your social provider > [!IMPORTANT] > -> To sign in with your social provider, make sure you verify your email address with your provider before you begin. +> To sign in with your social provider, you must verify your email address with your provider before you begin. -Optionally, you can sign in to an existing Docker account with your Google or GitHub account. If a Docker account exists with the same email address as the primary email for your social provider, your Docker account will automatically be linked to the social profile. This lets you sign in with your social provider. +You can also sign in to your Docker account with your Google or GitHub account. If a Docker account exists with the same email address as the primary email for your social provider, your Docker account will automatically be linked to the social profile. This lets you sign in with your social provider. If you try to sign in with your social provider and don't have a Docker account yet, a new account will be created for you. Follow the on-screen instructions to create a Docker ID using your social provider. @@ -90,4 +95,8 @@ To reset your password, enter your email address on the [Sign in](https://login. ## Troubleshooting -For support and troubleshooting information, see [Get support](../support.md). +If you have a paid Docker subscription, you can [contact the Support team](https://hub.docker.com/support/contact/) for assistance. + +All Docker users can seek troubleshooting information and support through the following resources, where Docker or the community respond on a best effort basis: + - [Docker Community Forums](https://forums.docker.com/) + - [Docker Community Slack](http://dockr.ly/comm-slack) diff --git a/content/manuals/accounts/deactivate-user-account.md b/content/manuals/accounts/deactivate-user-account.md index f1ed2ff44c5..8639c5c43c5 100644 --- a/content/manuals/accounts/deactivate-user-account.md +++ b/content/manuals/accounts/deactivate-user-account.md @@ -7,32 +7,28 @@ keywords: Docker Hub, delete, deactivate, account, account management You can deactivate an account at any time. This section describes the prerequisites and steps to deactivate a user account. For information on deactivating an organization, see [Deactivating an organization](../admin/deactivate-account.md). ->[!Warning] +>[!WARNING] > > All Docker products and services that use your Docker account will be inaccessible after deactivating your account. ## Prerequisites -Before deactivating your Docker account, ensure that you meet the following requirements: +Before deactivating your Docker account, ensure you meet the following requirements: - For owners, you must leave your organization or company before deactivating your Docker account. To do this: 1. Sign in to the [Docker Admin Console](https://app.docker.com/admin). - 2. Select the organization you need to leave from the top-left drop-down menu. + 2. Select the organization you need to leave from the **Choose profile** page. 3. Find your username in the **Members** tab. 4. Select the **More options** menu and then select **Leave organization**. - If you are the sole owner of an organization, you must assign the owner role to another member of the organization and then remove yourself from the organization, or deactivate the organization. Similarly, if you are the sole owner of a company, either add someone else as a company owner and then remove yourself, or deactivate the company. -- If you have an active Docker subscription, [downgrade it to a Docker Personal subscription](../subscription/core-subscription/downgrade.md). - -- If you have an active Docker Build Cloud Paid subscription, [downgrade it to a Docker Build Cloud Starter subscription](../billing/build-billing.md#downgrade-your-subscription). - -- If you have an active Docker Scout subscription, [downgrade it to a Docker Scout Free subscription](../billing/scout-billing.md#downgrade-your-subscription). +- If you have an active Docker subscription, [downgrade it to a Docker Personal subscription](../subscription/change.md). - Download any images and tags you want to keep. Use `docker pull -a :`. -- Unlink your [GitHub and Bitbucket accounts](../docker-hub/builds/link-source.md#unlink-a-github-user-account). +- Unlink your [GitHub and Bitbucket accounts](../docker-hub/repos/manage/builds/link-source.md#unlink-a-github-user-account). ## Deactivate diff --git a/content/manuals/accounts/manage-account.md b/content/manuals/accounts/manage-account.md index 554541f3bc7..9d28ded5cbc 100644 --- a/content/manuals/accounts/manage-account.md +++ b/content/manuals/accounts/manage-account.md @@ -5,11 +5,11 @@ description: Learn how to manage settings for your Docker account. keywords: accounts, docker ID, account settings, account management, docker home --- -You can centrally manage the settings for your Docker account. Here you can also take administrative actions for your account and manage your account security. +You can centrally manage the settings for your Docker account using Docker Home. Here you can also take administrative actions for your account and manage your account security. > [!TIP] > -> If your account is associated with an organization that enforces single sign-on (SSO), you may not have permissions to update your account settings. You need to contact your administrator to update your settings. +> If your account is associated with an organization that enforces single sign-on (SSO), you may not have permissions to update your account settings. You must contact your administrator to update your settings. ## Update general settings @@ -17,7 +17,7 @@ You can centrally manage the settings for your Docker account. Here you can also 2. In Docker Home, select your avatar in the top-right corner to open the drop-down. 3. Select **Account settings**. -From here, you can take any of the following actions. +From the Account settings page, you can take any of the following actions. ### Update account information @@ -57,12 +57,12 @@ You can manage the security settings for your account in Docker Home. For information on two-factor authentication (2FA) for your account, see [Enable two-factor authentication](../security/for-developers/2fa/_index.md) to get started. -For information on personal access tokens (PAT), see [Create and manage access tokens](../security/for-developers/access-tokens.md). +For information on personal access tokens, see [Create and manage access tokens](../security/for-developers/access-tokens.md). ## Account management You can take administrative actions for your account in Docker Home. -For more information on converting your account, see [Convert an account into an organization](../admin/convert-account.md). +For more information on converting your account, see [Convert an account into an organization](../admin/organization/convert-account.md). For information on deactivating your account, see [Deactivating a user account](./deactivate-user-account.md). diff --git a/content/manuals/admin/_index.md b/content/manuals/admin/_index.md index 591be8b4bab..72f14268db7 100644 --- a/content/manuals/admin/_index.md +++ b/content/manuals/admin/_index.md @@ -1,9 +1,10 @@ --- -title: Administration overview -linkTitle: Administration -weight: 200 +title: Administration description: Discover manuals on administration for accounts, organizations, and companies. keywords: admin, administration, company, organization, Admin Console, user accounts, account management +params: + sidebar: + group: Platform grid: - title: Company administration description: Explore how to manage a company. diff --git a/content/manuals/admin/company/new-company.md b/content/manuals/admin/company/new-company.md index 079081701d3..9100cf85629 100644 --- a/content/manuals/admin/company/new-company.md +++ b/content/manuals/admin/company/new-company.md @@ -6,7 +6,9 @@ aliases: - /docker-hub/new-company/ --- -You can create a new company in the Docker Admin Console. Before you begin, make sure you're the owner of the organization you want to add to the new company. The organization also needs to have a Docker Business subscription. +You can create a new company in the Docker Admin Console. Before you begin, you must: +- Be the owner of the organization you want to add to your company +- Have a Docker Business subscription {{< include "admin-early-access.md" >}} @@ -14,16 +16,17 @@ You can create a new company in the Docker Admin Console. Before you begin, make To create a new company: -1. In the Admin Console, navigate to the organization you want to place under a company. The organization must have a Business subscription, and you must be an owner of the organization. -2. Under **Organization settings**, select **Company management**. -3. Select **Create a company**. -4. Enter a unique name for your company, then select **Continue**. +1. Sign in to the [Admin Console](https://app.docker.com/admin). +2. Select your organization you want to add to your company from the **Choose profile** page. +3. Under **Organization settings**, select **Company management**. +4. Select **Create a company**. +5. Enter a unique name for your company, then select **Continue**. > [!TIP] > > The name for your company can't be the same as an existing user, organization, or company namespace. -5. Review the company migration details and then select **Create company**. +6. Review the company migration details and then select **Create company**. For more information on how you can add organizations to your company, see [Add organizations to a company](./organizations.md#add-organizations-to-a-company). diff --git a/content/manuals/admin/company/organizations.md b/content/manuals/admin/company/organizations.md index 5e2072b9a10..d5dba2d5c8f 100644 --- a/content/manuals/admin/company/organizations.md +++ b/content/manuals/admin/company/organizations.md @@ -1,7 +1,7 @@ --- -description: Learn how to manage organization in a company. +description: Learn how to manage organizations in a company. keywords: company, multiple organizations, manage organizations -title: Manage organizations +title: Manage company organizations --- You can manage the organizations in a company in the Docker Admin Console. @@ -11,40 +11,36 @@ You can manage the organizations in a company in the Docker Admin Console. ## View all organizations 1. Sign in to the [Admin Console](https://admin.docker.com). -2. In the left navigation, select your company in the drop-down menu. +2. Select your company on the **Choose profile** page. 3. Under **Organizations**, select **Overview**. +The organization overview page displays all organizations under your company. + ## Add seats to an organization -When you have a [self-serve](../../subscription/core-subscription/details.md#self-serve) subscription that has no pending subscription changes, you can add seats using the following steps. +When you have a [self-serve](../../subscription/details.md#self-serve) subscription that has no pending subscription changes, you can add seats using the following steps. If you have a sales-assisted subscription, you can contact Docker support or sales to add seats. -1. Sign in to the [Admin Console](https://admin.docker.com). -2. In the left navigation, select your company in the drop-down menu. -3. Under **Organizations**, select **Overview**. -4. Select the action icon in the organization's card, and then select **Get more seats**. +For more information about adding seats, see [Manage seats](/manuals/subscription/manage-seats.md#add-seats). ## Add organizations to a company ->[!IMPORTANT] -> -> You must be a company owner to add an organization to a company. You must also be an organization owner of the organization you want to add. - -There is no limit to the number of organizations you can have under a company layer. All organizations must have a Business subscription. +You must be a company owner to add an organization to a company. You must also be an organization owner of the organization you want to add. There is no limit to the number of organizations you can have under a company layer. All organizations must have a Business subscription. ->[!IMPORTANT] +> [!IMPORTANT] > > Once you add an organization to a company, you can't remove it from the company. 1. Sign in to the [Admin Console](https://admin.docker.com). -2. In the left navigation, select your company in the drop-down menu. -3. Select **Add organization**. -4. Choose the organization you want to add from the drop-down menu. -5. Select **Add organization** to confirm. +2. Select your company on the **Choose profile** page. +3. Select **Organizations**, then **Overview**. +4. Select **Add organization**. +5. Choose the organization you want to add from the drop-down menu. +6. Select **Add organization** to confirm. ## Manage an organization 1. Sign in to the [Admin Console](https://admin.docker.com). -2. In the left navigation, select your company in the drop-down menu. +2. Select your company on the **Choose profile** page. 3. Select the organization that you want to manage. For more details about managing an organization, see [Organization administration](../organization/_index.md). diff --git a/content/manuals/admin/company/owners.md b/content/manuals/admin/company/owners.md index fdacaa77c8f..ba028a727aa 100644 --- a/content/manuals/admin/company/owners.md +++ b/content/manuals/admin/company/owners.md @@ -18,7 +18,7 @@ member in an organization, they don't occupy a seat. ## Add a company owner 1. Sign in to the [Admin Console](https://admin.docker.com). -2. In the left navigation, select your company in the drop-down menu. +2. Select your company on the **Choose profile** page. 3. Select **Company owners**. 4. Select **Add owner**. 5. Specify the user's Docker ID to search for the user. @@ -27,7 +27,7 @@ member in an organization, they don't occupy a seat. ## Remove a company owner 1. Sign in to the [Admin Console](https://admin.docker.com). -2. In the left navigation, select your company in the drop-down menu. +2. Select your company on the **Choose profile** page. 3. Select **Company owners**. 4. Select the **Action** icon in the row of the company owner that your want to remove. 5. Select **Remove as company owner**. diff --git a/content/manuals/admin/company/users.md b/content/manuals/admin/company/users.md index 5144baa442a..9f7b6ec1294 100644 --- a/content/manuals/admin/company/users.md +++ b/content/manuals/admin/company/users.md @@ -4,12 +4,12 @@ keywords: company, company users, users, admin, Admin Console title: Manage company users --- -{{< include "admin-early-access.md" >}} - You can manage users at the company-level in the Docker Admin Console. {{% admin-users product="admin" layer="company" %}} +{{< include "admin-early-access.md" >}} + ## Manage members on a team Use Docker Hub to add a member to a team or remove a member from a team. For more details, see [Manage members in Docker Hub](../organization/members.md#manage-members-on-a-team). diff --git a/content/manuals/admin/deactivate-account.md b/content/manuals/admin/deactivate-account.md index 73f2b00d3e9..0aa4b64fe8c 100644 --- a/content/manuals/admin/deactivate-account.md +++ b/content/manuals/admin/deactivate-account.md @@ -1,5 +1,5 @@ --- -title: Deactivating an organization +title: Deactivate an organization description: Learn how to deactivate a Docker organization. keywords: Docker Hub, delete, deactivate organization, account, organization management aliases: @@ -8,7 +8,7 @@ aliases: You can deactivate an account at any time. This section describes the prerequisites and steps to deactivate an organization account. For information on deactivating a user account, see [Deactivate a user account](../accounts/deactivate-user-account.md). ->[!WARNING] +> [!WARNING] > > All Docker products and services that use your Docker account or organization account will be inaccessible after deactivating your account. @@ -19,13 +19,13 @@ Before deactivating an organization, complete the following: - Download any images and tags you want to keep: `docker pull -a :`. -- If you have an active Docker subscription, [downgrade it to a free subscription](../subscription/core-subscription/downgrade.md). - -- If you have an active Docker Scout subscription, [downgrade it to a Docker Scout Free subscription](../billing/scout-billing.md#downgrade-your-subscription). +- If you have an active Docker subscription, [downgrade it to a free subscription](../subscription/change.md). - Remove all other members within the organization. -- Unlink your [Github and Bitbucket accounts](../docker-hub/builds/link-source.md#unlink-a-github-user-account). +- Unlink your [Github and Bitbucket accounts](../docker-hub/repos/manage/builds/link-source.md#unlink-a-github-user-account). + +- For Business organizations, [remove your SSO connection](../security/for-admins/single-sign-on/manage/#remove-an-organization). ## Deactivate @@ -44,7 +44,7 @@ Once you have completed all the previous steps, you can deactivate your organiza 4. Select **Deactivate organization**. {{< /tab >}} -{{< tab name="Hub" >}} +{{< tab name="Docker Hub" >}} 1. On Docker Hub, select **Organizations**. 2. Choose the organization you want to deactivate. diff --git a/content/manuals/admin/faqs/company-faqs.md b/content/manuals/admin/faqs/company-faqs.md index 26170740863..9e8efcbc7f2 100644 --- a/content/manuals/admin/faqs/company-faqs.md +++ b/content/manuals/admin/faqs/company-faqs.md @@ -32,7 +32,7 @@ You can add a maximum of 10 company owners to a single company account. ### Do company owners occupy a subscription seat? -Company owners don't occupy a seat in any organization unless they are added as +Company owners don't occupy a seat in any organization unless they are added as a member of the organization. Since company owners have the same access as organization owners for all organizations associated with the company, it is not necessary to add company owners to an organization. @@ -43,7 +43,7 @@ you're an organization owner. ### What permissions does the company owner have in the associated/nested organizations? -Company owners can navigate to the **Organizations** page to view all their nested organizations in a single location. They can also view or edit organization members and change single sign-on (SSO) and System for Cross-domain Identity Management (SCIM) settings. Changes to company settings impact all users in each organization under the company. See [Roles and permissions](../../security/for-admins/roles-and-permissions.md). +Company owners can navigate to the **Organizations** page to view all their nested organizations in a single location. They can also view or edit organization members and change single sign-on (SSO) and System for Cross-domain Identity Management (SCIM) settings. Changes to company settings impact all users in each organization under the company. For more information, see [Roles and permissions](../../security/for-admins/roles-and-permissions.md). ### What features are supported at the company level? @@ -64,9 +64,9 @@ A company name must be unique to that of its child organization. If a child orga ### How does a company owner add an organization to the company? -You can add organizations to a company in the [Admin Console](../../admin/company/organizations.md#add-organizations-to-a-company.md). +You can add organizations to a company in the Admin Console. For more information, see [Add organizations to a company](../../admin/company/organizations.md#add-organizations-to-a-company.md). -### How does a company owner manage SSO/SCIM settings from a company? +### How does a company owner manage SSO/SCIM settings for a company? See your [SCIM](scim.md) and [SSO](../../security/for-admins/single-sign-on/configure/_index.md) settings. @@ -74,6 +74,6 @@ See your [SCIM](scim.md) and [SSO](../../security/for-admins/single-sign-on/conf See [SCIM](scim.md) and [group mapping](../../security/for-admins/provisioning/group-mapping.md) for more information. -### What's the definition of a company vs an organization? +### What's the definition of a company versus an organization? A company is a collection of organizations that are managed together. An organization is a collection of repositories and teams that are managed together. diff --git a/content/manuals/admin/faqs/general-faqs.md b/content/manuals/admin/faqs/general-faqs.md index 7a8152bac7a..28b6c0f3128 100644 --- a/content/manuals/admin/faqs/general-faqs.md +++ b/content/manuals/admin/faqs/general-faqs.md @@ -13,8 +13,7 @@ aliases: ### What is a Docker ID? -A Docker ID is a username for your Docker account that lets you access Docker products. All you need is an email address to create a Docker ID, or you can sign up with your Google or GitHub account. Your Docker ID must be between 4 and 30 characters long, and can only contain -numbers and lowercase letters. You can't use any special characters or spaces. +A Docker ID is a username for your Docker account that lets you access Docker products. To create a Docker ID, you need an email address or you can sign up with your social or GitHub accounts. Your Docker ID must be between 4 and 30 characters long, and can only contain numbers and lowercase letters. You can't use any special characters or spaces. For more information, see [Docker ID](/accounts/create-account/). If your administrator enforces [single sign-on (SSO)](../../security/for-admins/single-sign-on/_index.md), this provisions a Docker ID for new users. @@ -66,6 +65,10 @@ information, see [Configure SSO](../../security/for-admins/single-sign-on/config ### What is a service account? +> [!IMPORTANT] +> +> As of December 10, 2024, service accounts are no longer available. Existing Service Account agreements will be honored until their current term expires, but new purchases or renewals of service accounts no longer available and customers must renew under a new subscription plan. It is recommended to transition to Organization Access Tokens (OATs), which can provide similar functionality. For more information, see [Organization access tokens (Beta)](/manuals/security/for-admins/access-tokens.md). + A [service account](../../docker-hub/service-accounts.md) is a Docker ID used for automated management of container images or containerized applications. Service accounts are typically used in automated workflows, and don't share Docker IDs with the members in the Team or Business plan. Common use cases for service accounts include mirroring content on Docker Hub, or tying in image pulls from your CI/CD process. ### Can I delete or deactivate a Docker account for another user? @@ -76,4 +79,4 @@ If the user is a member of your organization, you can remove the user from your ### How do I manage settings for a user account? -You can manage your account settings any time when you sign in to your [Docker account](https://app.docker.com/login). In Docker Home, select your avatar in the top-right navigation, then select **My Account**. You can also access this menu from any Docker web applications when you're signed in to your account. See [Manage your Docker account](/accounts/manage-account). If your account is associated with an organization that uses SSO, you may have limited access to the settings that you can control. +You can manage your account settings anytime when you sign in to your [Docker account](https://app.docker.com/login). In Docker Home, select your avatar in the top-right navigation, then select **My Account**. You can also access this menu from any Docker web applications when you're signed in to your account. See [Manage your Docker account](/accounts/manage-account). If your account is associated with an organization that uses SSO, you may have limited access to the settings that you can control. diff --git a/content/manuals/admin/faqs/organization-faqs.md b/content/manuals/admin/faqs/organization-faqs.md index 027615cbbf7..0f6261fcb6b 100644 --- a/content/manuals/admin/faqs/organization-faqs.md +++ b/content/manuals/admin/faqs/organization-faqs.md @@ -12,7 +12,7 @@ aliases: ### What if the Docker ID I want for my organization or company is taken? -All Docker IDs are first-come, first-served except for companies that have a US Trademark on a username. If you have a trademark for your namespace, [Docker Support](https://hub.docker.com/support/contact/) can retrieve the Docker ID for you. +All Docker IDs are first-come, first-served except for companies that have a U.S. Trademark on a username. If you have a trademark for your namespace, [Docker Support](https://hub.docker.com/support/contact/) can retrieve the Docker ID for you. ### How do I add an organization owner? @@ -24,11 +24,11 @@ If your organization uses a Software Asset Management tool, you can use it to fi ### Do users first need to authenticate with Docker before an owner can add them to an organization? -No. Organization owners can invite users with their email address, and also assign them to a team during the invite process. +No. Organization owners can invite users with their email addresses, and also assign them to a team during the invite process. ### Can I force my organization's members to authenticate before using Docker Desktop and are there any benefits? -Yes. You can [enforce sign-in](../../security/for-admins/enforce-sign-in/_index.md) and some benefits are: +Yes. You can [enforce sign-in](../../security/for-admins/enforce-sign-in/_index.md). Some benefits of enforcing sign-in are: - Administrators can enforce features like [Image Access Management](/manuals/security/for-admins/hardened-desktop/image-access-management.md) and [Registry Access Management](../../security/for-admins/hardened-desktop/registry-access-management.md). - Administrators can ensure compliance by blocking Docker Desktop usage for users who don't sign in as members of the organization. @@ -46,9 +46,7 @@ revert it to a personal user account. For prerequisites and instructions, see ### Our users create Docker Hub accounts through self-service. How do we know when the total number of users for the requested licenses has been met? Is it possible to add more members to the organization than the total number of licenses? -There isn't any automatic notification when the total number of users for the requested licenses has been met. However, if the number of team -members exceed the number of licenses, you will receive an error informing you -to contact the administrator due to lack of seats. You can [add seats](/subscription/core-subscription/add-seats/) if needed. +There isn't any automatic notification when the total number of users for the requested licenses has been met. However, if the number of team members exceed the number of licenses, you will receive an error informing you to contact the administrator due to lack of seats. You can [add seats](../../subscription/manage-seats.md) if needed. ### How can I merge organization accounts? @@ -66,13 +64,13 @@ Yes. Organization owners will take up a seat. ### What is the difference between user, invitee, seat, and member? -User may refer to a Docker user with a Docker ID. +User refers to a Docker user with a Docker ID. -An invitee is a user that an administrator has invited to join an organization, but has not yet accepted their invitation. +An invitee is a user that an administrator has invited to join an organization but has not yet accepted their invitation. -Seats is the number of planned members within an organization. +Seats are the number of planned members within an organization. -Member may refer to a user that has received and accepted an invitation to join an organization. Member can also refer to a member of a team within an organization. +Member may refer to a user who has received and accepted an invitation to join an organization. Member can also refer to a member of a team within an organization. ### If there are two organizations and a user belongs to both organizations, do they take up two seats? diff --git a/content/manuals/admin/images/remove-owner.png b/content/manuals/admin/images/remove-owner.png deleted file mode 100644 index 8bda546ddb8..00000000000 Binary files a/content/manuals/admin/images/remove-owner.png and /dev/null differ diff --git a/content/manuals/admin/images/team-repo-permission.png b/content/manuals/admin/images/team-repo-permission.png deleted file mode 100644 index e5fab746671..00000000000 Binary files a/content/manuals/admin/images/team-repo-permission.png and /dev/null differ diff --git a/content/manuals/admin/convert-account.md b/content/manuals/admin/organization/convert-account.md similarity index 99% rename from content/manuals/admin/convert-account.md rename to content/manuals/admin/organization/convert-account.md index f259f171852..aaf8d5f3219 100644 --- a/content/manuals/admin/convert-account.md +++ b/content/manuals/admin/organization/convert-account.md @@ -2,6 +2,7 @@ description: Convert your Docker Hub user account into an organization title: Convert an account into an organization keywords: docker hub, hub, organization, convert account, migrate account +weight: 35 aliases: - /docker-hub/convert-account/ --- @@ -12,7 +13,7 @@ When you convert a user account to an organization, the account is migrated to a > [!IMPORTANT] > -> Once you convert your account to an organization, you can’t revert it to a user account. +> Once you convert your account to an organization, you can’t revert it to a user account. ## Prerequisites diff --git a/content/manuals/admin/organization/general-settings.md b/content/manuals/admin/organization/general-settings.md index 9b26bc8b0ef..ada92c672a6 100644 --- a/content/manuals/admin/organization/general-settings.md +++ b/content/manuals/admin/organization/general-settings.md @@ -11,7 +11,7 @@ This section describes how to manage organization settings in the Docker Admin C ## Configure general information -General organization information appears on your organization landing page in Docker Hub. +General organization information appears on your organization landing page in the Admin Console. This information includes: - Organization Name @@ -23,7 +23,7 @@ This information includes: To edit this information: 1. Sign in to the [Admin Console](https://admin.docker.com). -2. In the left navigation, select your organization in the drop-down menu. +2. Select your company on the **Choose profile** page. 3. Under **Organization settings**, select **General**. 4. Specify the organization information and select **Save**. diff --git a/content/manuals/admin/organization/insights.md b/content/manuals/admin/organization/insights.md index 5301d2aadbc..478f8101b47 100644 --- a/content/manuals/admin/organization/insights.md +++ b/content/manuals/admin/organization/insights.md @@ -5,11 +5,8 @@ title: Insights --- > [!NOTE] -> Insights requires a [Docker Business -> subscription](/subscription/core-subscription/details/#docker-business) and -> administrators must [enforce sign-in](/manuals/security/for-admins/enforce-sign-in/_index.md) -> to ensure that users sign in with an account associated with their -> organization. +> +> Insights requires a [Docker Business subscription](../../subscription/details.md#docker-business) and administrators must [enforce sign-in](/security/for-admins/enforce-sign-in/). This ensures users sign in with an account associated with their organization. Insights helps administrators visualize and understand how Docker is used within their organizations. With Insights, administrators can ensure their teams are @@ -18,37 +15,39 @@ productivity and efficiency across the organization. Key benefits include: -* Uniform working environment. Establish and maintain standardized +- Uniform working environment. Establish and maintain standardized configurations across teams. -* Best practices. Promote and enforce usage guidelines to ensure optimal +- Best practices. Promote and enforce usage guidelines to ensure optimal performance. -* Increased visibility. Monitor and drive adoption of organizational +- Increased visibility. Monitor and drive adoption of organizational configurations and policies. -* Optimized license use. Ensure that developers have access to advanced +- Optimized license use. Ensure that developers have access to advanced features provided by a Docker subscription. ## View Insights for organization users +{{< include "admin-early-access.md" >}} + 1. Go to the [Admin Console](https://app.docker.com/admin/) and sign in to an account that is an organization owner. -2. In the Admin Console, select your organization from the drop-down in the left - navigation. +2. Select your company on the **Choose profile** page. 3. Select **Insights**. 4. On the **Insights** page, select the period of time for the data. > [!NOTE] +> > Insights data is not real-time and is updated daily. At the top-right of the > Insights page, view the **Last updated** date to understand when the data was > last updated. You can view data in the following charts: - * [Docker Desktop users](#docker-desktop-users) - * [Builds](#builds) - * [Containers](#containers) - * [Docker Desktop usage](#docker-desktop-usage) - * [Docker Hub images](#docker-hub-images) - * [Extensions](#extensions) + - [Docker Desktop users](#docker-desktop-users) + - [Builds](#builds) + - [Containers](#containers) + - [Docker Desktop usage](#docker-desktop-usage) + - [Docker Hub images](#docker-hub-images) + - [Extensions](#extensions) ### Docker Desktop users @@ -60,13 +59,12 @@ counts. The chart contains the following data. -| Data | Description | +| Data | Description | |:-----------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Total active users | The number of users that have actively used Docker Desktop and either signed in with a Docker account that has a license in your organization or signed in to a Docker account with an email address from a domain associated with your organization.

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

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

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

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

When users opt out of sending analytics, you won't see any of their data in Insights. To ensure that the data includes all users, you can use [Settings Management](/desktop/hardened-desktop/settings-management/) to set `analyticsEnabled` for all your users. | +| Active users (graph) | The view over time for total active users. | ### Builds diff --git a/content/manuals/admin/organization/manage-a-team.md b/content/manuals/admin/organization/manage-a-team.md index 55fad01c3a6..efc865e0690 100644 --- a/content/manuals/admin/organization/manage-a-team.md +++ b/content/manuals/admin/organization/manage-a-team.md @@ -10,37 +10,36 @@ aliases: You can create teams for your organization in Docker Hub and the Docker Admin Console. You can [configure repository access for a team](#configure-repository-permissions-for-a-team) in Docker Hub. -A team is a group of Docker users that belong to an organization. An -organization can have multiple teams. An -organization owner can then create new teams and add members to an existing team -using their Docker ID or email address and by selecting a team the user should be part of. Members aren't required to be part of a team to be associated with an organization. +A team is a group of Docker users that belong to an organization. An organization can have multiple teams. An organization owner can then create new teams and add members to an existing team using their Docker ID or email address and by selecting a team the user should be part of. Members aren't required to be part of a team to be associated with an organization. The organization owner can add additional organization owners to help them manage users, teams, and repositories in the organization by assigning them the owner role. ## Organization owner -An organization owner is an administrator who is responsible to manage -repositories and add team members to the organization. They have full access to -private repositories, all teams, billing information, and org settings. An org -owner can also specify [permissions](#permissions-reference) for each team in -the organization. Only an org owner can enable [SSO](../../security/for-admins/single-sign-on/_index.md) -for -the organization. When SSO is enabled for your organization, the org owner can +An organization owner is an administrator who has the following permissions: + +- Manage repositories and add team members to the organization. +- Access private repositories, all teams, billing information, and organization settings. +- Specify [permissions](#permissions-reference) for each team in the organization. +- Enable [SSO](../../security/for-admins/single-sign-on/_index.md) for the organization. + +When SSO is enabled for your organization, the organization owner can also manage users. Docker can auto-provision Docker IDs for new end-users or users who'd like to have a separate Docker ID for company use through SSO enforcement. -The org owner can also add additional org owners to help them manage users, teams, and repositories in the organization. +The organization owner can also add additional organization owners to help them manage users, teams, and repositories in the organization. ## Create a team {{< tabs >}} {{< tab name="Docker Hub" >}} -1. Go to **Organizations** in Docker Hub, and select your organization. -2. Select the **Teams** tab and then select **Create Team**. -3. Fill out your team's information and select **Create**. -4. [Add members to your team](members.md#add-a-member-to-a-team). +1. Sign in to [Docker Hub](https://hub.docker.com). +2. Select **Organizations** and choose your organization. +3. Select the **Teams** tab and then select **Create Team**. +4. Fill out your team's information and select **Create**. +5. [Add members to your team](members.md#add-a-member-to-a-team). {{< /tab >}} {{< tab name="Admin Console" >}} @@ -61,19 +60,18 @@ The org owner can also add additional org owners to help them manage users, team Organization owners can configure repository permissions on a per-team basis. For example, you can specify that all teams within an organization have "Read and Write" access to repositories A and B, whereas only specific teams have "Admin" -access. Note that org owners have full administrative access to all repositories within the organization. +access. Note that organization owners have full administrative access to all repositories within the organization. -To give a team access to a repository +To give a team access to a repository: -1. Navigate to **Organizations** in Docker Hub, and select your organization. -2. Select the **Teams** tab and select the team that you'd like to configure repository access to. -3. Select the **Permissions** tab and select a repository from the +1. Sign in to [Docker Hub](https://hub.docker.com). +2. Select **Organizations** and choose your organization. +3. Select the **Teams** tab and select the team that you'd like to configure repository access to. +4. Select the **Permissions** tab and select a repository from the **Repository** drop-down. -4. Choose a permission from the **Permissions** drop-down list and select +5. Choose a permission from the **Permissions** drop-down list and select **Add**. - ![Team Repo Permissions](../images/team-repo-permission.png) - Organization owners can also assign members the editor role to grant partial administrative access. See [Roles and permissions](../../security/for-admins/roles-and-permissions.md) for more about the editor role. ### Permissions reference @@ -110,8 +108,10 @@ you automatically have "Read-only" permissions: To view a team's permissions across all repositories: -1. Open **Organizations** > **_Your Organization_** > **Teams** > **_Team Name_**. -2. Select the **Permissions** tab, where you can view the repositories this team can access. +1. Sign in to [Docker Hub](https://hub.docker.com). +2. Select **Organizations** and choose your organization. +3. Select **Teams** and choose your team name. +4. Select the **Permissions** tab, where you can view the repositories this team can access. ## Delete a team @@ -120,19 +120,20 @@ Organization owners can delete a team in Docker Hub or Admin Console. When you r {{< tabs >}} {{< tab name="Docker Hub" >}} -1. Go to **Organizations** in Docker Hub, and select your organization. -2. Select the **Teams** tab. -3. Select the name of the team that you want to delete. -4. Select **Settings**. -5. Select **Delete Team**. -6. Review the confirmation message, then select **Delete**. +1. Sign in to [Docker Hub](https://hub.docker.com). +2. Select **Organizations** and choose your organization. +3. Select the **Teams** tab. +4. Select the name of the team that you want to delete. +5. Select **Settings**. +6. Select **Delete Team**. +7. Review the confirmation message, then select **Delete**. {{< /tab >}} {{< tab name="Admin Console" >}} {{< include "admin-early-access.md" >}} -1. In Admin Console, select your organization. +1. In the [Admin Console](https://app.docker.com/admin), select your organization. 2. In the **User management** section, select **Teams**. 3. Select the **Actions** icon next to the name of the team you want to delete. 4. Select **Delete team**. diff --git a/content/manuals/admin/organization/manage-products.md b/content/manuals/admin/organization/manage-products.md new file mode 100644 index 00000000000..4cf0b98ad03 --- /dev/null +++ b/content/manuals/admin/organization/manage-products.md @@ -0,0 +1,107 @@ +--- +title: Manage Docker products +weight: 45 +description: Learn how to manage Docker products for your organization +keywords: organization, tools, products +--- + +In this section, learn how to manage access and view usage of the Docker +products for your organization. For more detailed information about each +product, including how to set up and configure them, see the following manuals: + +- [Docker Build Cloud](../../build-cloud/_index.md) +- [Docker Desktop](../../desktop/_index.md) +- [Docker Hub](../../docker-hub/_index.md) +- [Docker Scout](../../scout/_index.md) +- [Testcontainers Cloud](https://testcontainers.com/cloud/docs/#getting-started) + +## Manage access to Docker products + +Access to Docker products included in your subscription is enabled by default +for all users. The included products are: + +- Docker Hub +- Docker Build Cloud +- Docker Desktop +- Docker Scout + +Testcontainers Cloud is not enabled by default. To enable Testcontainers Cloud, see the Testcontainers [Getting Started](https://testcontainers.com/cloud/docs/#getting-started) guide. + +The following sections describe how to enable or disable access for these products. + +### Manage access to Docker Build Cloud + +To learn how to initially set up and configure Docker Build Cloud, sign in to +the [Docker Build Cloud Dashboard](https://app.docker.com/build) and follow the +on-screen instructions. + +To manage access to Docker Build Cloud, sign in to [Docker Build +Cloud](http://app.docker.com/build) as an organization owner, select **Account +settings**, and then manage access under **Lock Docker Build Cloud**. + +### Manage access to Docker Scout + +To learn how to initially set up and configure Docker Scout for remote +repositories, sign in to the [Docker Scout Dashboard](https://scout.docker.com/) +and follow the on-screen instructions. + +To manage access to Docker Scout for use on remote repositories, sign in to the +[Docker Scout Dashboard](https://scout.docker.com/) and configure +[integrations](../../scout/explore/dashboard.md#integrations) and [repository +settings](../../scout/explore/dashboard.md#repository-settings). + +To manage access to Docker Scout for use on local images with Docker Desktop, use +[Settings +Management](../../security/for-admins/hardened-desktop/settings-management/_index.md) +and set `sbomIndexing` to `false` to disable, or to `true` to enable. + +### Manage access to Docker Hub + +To manage access to Docker Hub, sign in to the [Docker Admin Console](https://app.docker.com/admin) and configure [Registry Access +Management](../../security/for-admins/hardened-desktop/registry-access-management.md) +or [Image Access +Management](../../security/for-admins/hardened-desktop/image-access-management.md). + +### Manage access to Testcontainers Cloud + +To learn how to initially set up and configure Testcontainers Cloud, sign in to +[Testcontainers Cloud](https://app.testcontainers.cloud/) and follow the +on-screen instructions. + +To manage access to Testcontainers Cloud, sign in to the [Testcontainers Cloud +Settings page](https://app.testcontainers.cloud/dashboard/settings) as +an organization owner, and then manage access under **Lock Testcontainers +Cloud**. + +### Manage access to Docker Desktop + +To manage access to Docker Desktop, you can [enforce +sign-in](../../security/for-admins/enforce-sign-in/_index.md), then and manage +members [manually](./members.md) or use +[provisioning](../../security/for-admins/provisioning/_index.md). With sign-in +enforced, only users who are a member of your organization can use Docker +Desktop after signing in. + +## View Docker product usage + +View usage for the products on the following pages: + +- Docker Build Cloud: View the **Build minutes** page in the [Docker Build Cloud + Dashboard](http://app.docker.com/build). + +- Docker Scout: View the [**Repository settings** + page](https://scout.docker.com/settings/repos) in the Docker Scout + Dashboard. + +- Docker Hub: View the [**Usage** page](https://hub.docker.com/usage) in Docker + Hub. + +- Testcontainers Cloud: View the [**Billing** + page](https://app.testcontainers.cloud/dashboard/billing) in the + Testcontainers Cloud Dashboard. + +- Docker Desktop: View the **Insights** page in the [Docker Admin Console](https://app.docker.com/admin). For more details, see + [Insights](./insights.md). + +If your usage exceeds your subscription amount, you can [scale your +subscription](../../subscription/scale.md) to meet your needs. \ No newline at end of file diff --git a/content/manuals/admin/organization/members.md b/content/manuals/admin/organization/members.md index 275e3069741..fdb1e19e14c 100644 --- a/content/manuals/admin/organization/members.md +++ b/content/manuals/admin/organization/members.md @@ -9,6 +9,8 @@ aliases: Learn how to manage members for your organization in Docker Hub and the Docker Admin Console. +## Invite members + {{< tabs >}} {{< tab name="Docker Hub" >}} @@ -24,18 +26,95 @@ Learn how to manage members for your organization in Docker Hub and the Docker A {{< /tab >}} {{< /tabs >}} +## Accept invitation + +When an invitation is to a user's email address, they receive +a link to Docker Hub where they can accept or decline the invitation. +To accept an invitation: + +1. Navigate to your email inbox and open the Docker email with an invitation to +join the Docker organization. +2. To open the link to Docker Hub, select the **click here** link. +3. The Docker create an account page will open. If you already have an account, select **Already have an account? Sign in**. +If you do not have an account yet, create an account using the same email +address you received the invitation through. +4. Optional. If you do not have an account and created one, you must navigate +back to your email inbox and verify your email address using the Docker verification +email. +5. Once you are signed in to Docker Hub, select **Organizations** from the top-level navigation menu. +6. The organizations page will display your invitation. Select **Accept**. + +After accepting an invitation, you are now a member of the organization. + +## Manage invitations + +After inviting members, you can resend or remove invitations as needed. + +### Resend an invitation + +{{< tabs >}} +{{< tab name="Docker Hub" >}} + +To resend an invitation from Docker Hub: + +1. Sign in to [Docker Hub](https://hub.docker.com/). +2. Select **Organizations**, your organization, and then **Members**. +3. In the table, locate the invitee, select the **Actions** icon, and then select +**Resend invitation**. +4. Select **Invite** to confirm. + +{{< /tab >}} +{{< tab name="Admin Console" >}} + +{{< include "admin-early-access.md" >}} + +To resend an invitation from the Admin Console: + +1. In the [Admin Console](https://app.docker.com/admin), select your organization. +2. Select **Members**. +3. Select the **action menu** next to the invitee and select **Resend invitation**. +4. Select **Invite** to confirm. + +{{< /tab >}} +{{< /tabs >}} + +### Remove an invitation + +{{< tabs >}} +{{< tab name="Docker Hub" >}} + +To remove a member's invitation from Docker Hub: + +1. Sign in to [Docker Hub](https://hub.docker.com/). +2. Select **Organizations**, your organization, and then **Members**. +3. In the table, select the **Action** icon, and then select **Remove member** or **Remove invitee**. +4. Follow the on-screen instructions to remove the member or invitee. + +{{< /tab >}} +{{< tab name="Admin Console" >}} + +{{< include "admin-early-access.md" >}} + +To remove an invitation from the Admin Console: + +1. In the [Admin Console](https://app.docker.com/admin), select your organization. +2. Select **Members**. +3. Select the **action menu** next to the invitee and select **Remove invitee**. +4. Select **Remove** to confirm. + +{{< /tab >}} +{{< /tabs >}} + ## Manage members on a team -Use Docker Hub to add a member to a team or remove a member from a team. +Use Docker Hub or the Admin Console to add or remove team members. Organization owners can add a member to one or more teams within an organization. ### Add a member to a team -Organization owners can add a member to one or more teams within an organization. - {{< tabs >}} {{< tab name="Docker Hub" >}} -To add a member to a team: +To add a member to a team with Docker Hub: 1. Sign in to [Docker Hub](https://hub.docker.com). 2. Select **Organizations**, your organization, and then **Members**. @@ -55,9 +134,9 @@ To add a member to a team: {{< include "admin-early-access.md" >}} -To add a member to a team: +To add a member to a team with the Admin Console: -1. In the Admin Console, select your organization. +1. In the [Admin Console](https://app.docker.com/admin), select your organization. 2. Select the team name. 3. Select **Add member**. You can add the member by searching for their email address or username. @@ -75,9 +154,7 @@ Organization owners can remove a member from a team in Docker Hub or Admin Conso {{< tabs >}} {{< tab name="Docker Hub" >}} -To add a member to a team: - -To remove a member from a specific team: +To remove a member from a specific team with Docker Hub: 1. Sign in to [Docker Hub](https://hub.docker.com). 2. Select **Organizations**, your organization, **Teams**, and then the team. @@ -89,12 +166,64 @@ To remove a member from a specific team: {{< include "admin-early-access.md" >}} -To remove a member from a specific team: +To remove a member from a specific team with the Admin Console: -1. In the Admin Console, select your organization. +1. In the [Admin Console](https://app.docker.com/admin), select your organization. 2. Select the team name. 3. Select the **X** next to the user's name to remove them from the team. 4. When prompted, select **Remove** to confirm. {{< /tab >}} {{< /tabs >}} + +### Update a member role + +Organization owners can manage [roles](/security/for-admins/roles-and-permissions/) +within an organization. If an organization is part of a company, +the company owner can also manage that organization's roles. If you have SSO enabled, you can use [SCIM for role mapping](/security/for-admins/provisioning/scim/). + +> [!NOTE] +> +> If you're the only owner of an organization, +> you need to assign a new owner before you can edit your role. + +To update a member role: + +1. Sign in to [Docker Hub](https://hub.docker.com). +2. Select **Organizations**, your organization, and then **Members**. +3. Find the username of the member whose role you want to edit. In the table, select the **Actions** icon. +4. Select **Edit role**. +5. Select their organization, select the role you want to assign, and then select **Save**. + +## Export members CSV file + +Owners can export a CSV file containing all members. The CSV file for a company contains the following fields: +- Name: The user's name +- Username: The user's Docker ID +- Email: The user's email address +- Member of Organizations: All organizations the user is a member of within a company +- Invited to Organizations: All organizations the user is an invitee of within a company +- Account Created: The time and date when the user account was created + +{{< tabs >}} +{{< tab name="Docker Hub" >}} + +To export a CSV file of your members: + +1. Sign in to [Docker Hub](https://hub.docker.com). +2. Select **Organizations**, your organization, and then **Members**. +3. Select the **Action** icon and then select **Export users as CSV**. + +{{< /tab >}} +{{< tab name="Admin Console" >}} + +{{< include "admin-early-access.md" >}} + +To export a CSV file of your members: + +1. In the [Admin Console](https://app.docker.com/admin), select your organization. +2. Select **Members**. +3. Select the **download** icon to export a CSV file of all members. + +{{< /tab >}} +{{< /tabs >}} \ No newline at end of file diff --git a/content/manuals/admin/organization/onboard.md b/content/manuals/admin/organization/onboard.md index 37d1d7c0fa5..74a31e69bea 100644 --- a/content/manuals/admin/organization/onboard.md +++ b/content/manuals/admin/organization/onboard.md @@ -15,9 +15,9 @@ aliases: Learn how to onboard your organization using Docker Hub or the Docker Admin Console. -Onboarding your organization lets you gain visibility into the activity of your users and enforce security settings. In addition, members of your organization receive increased pull limits and other organization wide benefits. For more details, see [Docker subscriptions and features](/subscription/core-subscription/details/). +Onboarding your organization lets administrators gain visibility into user activity and enforce security settings. In addition, members of your organization receive increased pull limits and other organization wide benefits. For more details, see [Docker subscriptions and features](../../subscription/details.md). -In this guide, you'll learn how to get started with the following: +In this guide, you'll learn how to do the following: - Identify your users to help you efficiently allocate your subscription seats - Invite members and owners to your organization @@ -27,7 +27,8 @@ In this guide, you'll learn how to get started with the following: ## Prerequisites Before you start to onboard your organization, ensure that you: -- Have a Docker Team or Business subscription. See [Pricing & Subscriptions](https://www.docker.com/pricing/) for details. + +- Have a Docker Team or Business subscription. See [Docker Pricing](https://www.docker.com/pricing/) for details. > [!NOTE] > @@ -35,24 +36,24 @@ Before you start to onboard your organization, ensure that you: - Familiarize yourself with Docker concepts and terminology in the [glossary](/glossary/) and [FAQs](/faq/admin/general-faqs/). -## Step 1: Identify your Docker users and their Docker accounts +## Step 1: Identify your Docker users Identifying your users will ensure that you allocate your subscription seats efficiently and that all your Docker users receive the benefits of your subscription. 1. Identify the Docker users in your organization. - - If your organization uses device management software, like MDM or JAMF, you may use the device management software to help identify Docker users. See your device management software's documentation for details. You can identify Docker users by checking if Docker Desktop is installed at the following location on each user's machine: + - If your organization uses device management software, like MDM or Jamf, you may use the device management software to help identify Docker users. See your device management software's documentation for details. You can identify Docker users by checking if Docker Desktop is installed at the following location on each user's machine: - Mac: `/Applications/Docker.app` - Windows: `C:\Program Files\Docker\Docker` - Linux: `/opt/docker-desktop` - If your organization doesn't use device management software or your users haven't installed Docker Desktop yet, you may survey your users. -2. Instruct all your Docker users in your organization to update their existing Docker account's email address to an address that's in your organization's domain, or to create a new account using an email address in your organization's domain. +2. Instruct all your organization's Docker users to update their existing Docker account's email address to an address that's in your organization's domain, or to create a new account using an email address in your organization's domain. - To update an account's email address, instruct your users to sign in to [Docker Hub](https://hub.docker.com), and update the email address to their email address in your organization's domain. - To create a new account, instruct your users to go [sign up](https://hub.docker.com/signup) using their email address in your organization's domain. 3. Ask your Docker sales representative or [contact sales](https://www.docker.com/pricing/contact-sales/) to get a list of Docker accounts that use an email address in your organization's domain. ## Step 2: Invite owners -When you create an organization, you are the only owner. You may optionally add additional owners. Owners can help you onboard and manage your organization. +When you create an organization, you are the only owner. It is optional to add additional owners. Owners can help you onboard and manage your organization. To add an owner, invite a user and assign them the owner role. For more details, see [Invite members](/admin/organization/members/). @@ -68,23 +69,22 @@ Configuring SSO and SCIM is optional and only available to Docker Business subsc You can manage your members in your identity provider and automatically provision them to your Docker organization with SSO and SCIM. See the following for more details. - [Configure SSO](/manuals/security/for-admins/single-sign-on/configure.md) to authenticate and add members when they sign in to Docker through your identity provider. - - Optional: [Enforce SSO](/manuals/security/for-admins/single-sign-on/connect.md) to ensure that when users sign in to Docker, they must use SSO. + - Optional. [Enforce SSO](/manuals/security/for-admins/single-sign-on/connect.md) to ensure that when users sign in to Docker, they must use SSO. + > [!NOTE] > > Enforcing single sign-on (SSO) and [Step 5: Enforce sign-in for Docker > Desktop](#step-5-enforce-sign-in-for-docker-desktop) are different > features. For more details, see > [Enforcing sign-in versus enforcing single sign-on (SSO)](/security/for-admins/enforce-sign-in/#enforcing-sign-in-versus-enforcing-single-sign-on-sso). + - [Configure SCIM](/security/for-admins/provisioning/scim/) to automatically provision, add, and de-provision members to Docker through your identity provider. ## Step 5: Enforce sign-in for Docker Desktop By default, members of your organization can use Docker Desktop without signing in. When users don’t sign in as a member of your organization, they don’t -receive the [benefits of your organization’s -subscription](/subscription/core-subscription/details/) and they can circumvent -[Docker’s security features](/security/for-admins/hardened-desktop/) for your -organization. +receive the [benefits of your organization’s subscription](../../subscription/details.md) and they can circumvent [Docker’s security features](/security/for-admins/hardened-desktop/). There are multiple ways you can enforce sign-in, depending on your company's set up and preferences: @@ -94,8 +94,7 @@ set up and preferences: ## What's next -- [Create](/docker-hub/repos/create/) and [manage](/docker-hub/repos/) repositories. -- Create [teams](/admin/organization/manage-a-team/) for fine-grained repository access. +- [Manage Docker products](./manage-products.md) to configure access and view usage. - Configure [Hardened Docker Desktop](/desktop/hardened-desktop/) to improve your organization’s security posture for containerized development. - [Audit your domains](/docker-hub/domain-audit/) to ensure that all Docker users in your domain are part of your organization. diff --git a/content/manuals/admin/organization/orgs.md b/content/manuals/admin/organization/orgs.md index 5ff6c32106e..426a2d80d1e 100644 --- a/content/manuals/admin/organization/orgs.md +++ b/content/manuals/admin/organization/orgs.md @@ -10,68 +10,95 @@ aliases: This section describes how to create an organization. Before you begin: -- You need a [Docker ID](/accounts/create-account/). -- Review the [Docker subscriptions and features](../../subscription/core-subscription/details.md) to determine what plan to choose for your organization. +- You need a [Docker ID](/accounts/create-account/) +- Review the [Docker subscriptions and features](../../subscription/details.md) to determine what plan to choose for your organization ## Create an organization -There are multiple ways to create an organization. You can create a brand new -organization using the **Create Organization** option in Docker Hub, or you can -convert an existing user account to an organization. The following section -contains instructions on how to create a new organization. For prerequisites and +There are multiple ways to create an organization. You can either: +- Create a new organization using the **Create Organization** option in Docker Hub +- Convert an existing user account to an organization + +The following section contains instructions on how to create a new organization. For prerequisites and detailed instructions on converting an existing user account to an organization, see -[Convert an account into an organization](../convert-account.md). +[Convert an account into an organization](/manuals/admin/organization/convert-account.md). -To create an organization: +{{< tabs >}} +{{< tab name="Docker Hub" >}} 1. Sign in to [Docker Hub](https://hub.docker.com/) using your Docker ID, your email address, or your social provider. -2. Select **Organizations** and then **Create Organization** to create a new - organization. -3. Choose a plan for your organization and select **Buy Now**. See -[Docker Pricing](https://www.docker.com/pricing/) -for details on the features offered in the Team and Business plan. +2. Select **Organizations** and then **Create Organization** to create a new organization. +3. Choose a plan for your organization, a billing cycle, and specify how many seats you need. See [Docker Pricing](https://www.docker.com/pricing/) for details on the features offered in the Team and Business plan. +4. Select **Continue to profile**. +5. Enter an **Organization namespace**. This is the official, unique name for +your organization in Docker Hub. It's not possible to change the name of the +organization after you've created it. > [!NOTE] > - > Selecting **Buy Now** isn't an obligation to pay. You can complete - > this step without incurring a payment. + > You can't use the same name for the organization and your Docker ID. If you want to use your Docker ID as the organization name, then you must first [convert your account into an organization](/manuals/admin/organization/convert-account.md). + +6. Enter your **Company name**. This is the full name of your company. Docker +displays the company name on your organization page and in the details of any +public images you publish. You can update the company name anytime by navigating +to your organization's **Settings** page. +7. Select **Continue to billing** to continue. +8. Enter your organization's billing information and select **Continue to payment** to continue to the billing portal. +9. Provide your card details and select **Purchase**. + +You've now created an organization. -4. Enter a name for your organization. This is the official, unique name for +{{< /tab >}} +{{< tab name="Admin Console" >}} + +{{< include "admin-early-access.md" >}} + +To create an organization: + +1. Sign in to [Docker Home](https://app.docker.com/). +2. Under Settings and administration, select **Go to Admin Console**. +3. Select the **Organization** drop-down in the left-hand navigation and then **Create Organization**. +4. Choose a plan for your organization, a billing cycle, and specify how many seats you need. See [Docker Pricing](https://www.docker.com/pricing/) for details on the features offered in the Team and Business plan. +5. Select **Continue to profile**. +6. Enter an **Organization namespace**. This is the official, unique name for your organization in Docker Hub. It's not possible to change the name of the organization after you've created it. > [!NOTE] > - > You can't use the same name for the organization and your Docker ID. If you want to use your Docker ID as the organization name, then you must first [convert your account into an organization](../convert-account.md). + > You can't use the same name for the organization and your Docker ID. If you want to use your Docker ID as the organization name, then you must first [convert your account into an organization](/manuals/admin/organization/convert-account.md). -5. Enter the name of your company. This is the full name of your company. Docker +7. Enter your **Company name**. This is the full name of your company. Docker displays the company name on your organization page and in the details of any public images you publish. You can update the company name anytime by navigating to your organization's **Settings** page. -6. Select **Purchase** to continue. -7. Enter the billing information for your organization. -8. Select **Submit** to continue to the billing portal. -9. In the billing portal, select **Qty** to update the number of seats you require, then select **Update**. -10. (Optional) Select annual or monthly billing cycle. -11. Follow the on-screen instructions to pay for your subscription. +8. Select **Continue to billing** to continue. +9. Enter your organization's billing information and select **Continue to payment** to continue to the billing portal. +10. Provide your card details and select **Purchase**. You've now created an organization. +{{< /tab >}} +{{< /tabs >}} + ## View an organization +{{< tabs >}} +{{< tab name="Docker Hub" >}} + To view an organization: -1. Sign in to Docker Hub with a user account that is a member of any team in the - organization. +1. Sign in to [Docker Hub](https://hub.docker.com) with a user account that is a member of any team in the + organization. > [!NOTE] > - > You can't _directly_ log in to an organization. This is especially + > You can't *directly* sign in to an organization. This is especially > important to note if you create an organization by - [converting a user account](../convert-account.md), as conversion means you lose the ability to log into that - > "account", since it no longer exists. To view the organization you - > need to log in with the new owner account assigned during the - > conversion or another account that was added as a member. If you + [converting a user account](/manuals/admin/organization/convert-account.md), as conversion means you lose the ability to log into that + > "account", since it no longer exists. To view the organization you + > need to sign in with the new owner account assigned during the + > conversion or another account that was added as a member. If you > don't see the organization after logging in, > then you are neither a member or an owner of it. An organization > administrator needs to add you as a member of the organization. @@ -79,7 +106,7 @@ To view an organization: 2. Select **Organizations** in the top navigation bar, then choose your organization from the list. -The organization landing page displays various options that allow you to +The organization landing page displays various options that let you to configure your organization. - **Members**: Displays a list of team members. You @@ -98,27 +125,65 @@ configure your organization. details. - **Settings**: Displays information about your - organization, and allows you to view and change your repository privacy + organization, and you to view and change your repository privacy settings, configure org permissions such as [Image Access Management](/manuals/security/for-admins/hardened-desktop/image-access-management.md), configure notification settings, and [deactivate](../deactivate-account.md#deactivate-an-organization) You can also update your organization name and company name that appear on your organization landing page. You must be an owner to access the organization's **Settings** page. - **Billing**: Displays information about your existing -[Docker subscription (plan)](../../subscription/_index.md), including the number of seats and next payment due date. For how to access the billing history and payment methods for your organization, see [View billing history](../../billing/core-billing/history.md). +[Docker subscription (plan)](../../subscription/_index.md), including the number of seats and next payment due date. For how to access the billing history and payment methods for your organization, see [View billing history](../../billing/history.md). + +{{< /tab >}} +{{< tab name="Admin Console" >}} + +{{< include "admin-early-access.md" >}} + +To view an organization in the Admin Console: + +1. Sign in to [Docker Home](https://app.docker.com). +2. Under Settings and administration, select **Go to Admin Console**. +3. Select your organization from the **Organization** drop-down in the left-hand navigation. + +The Admin Console displays various options that let you to +configure your organization. + +- **Members**: Displays a list of team members. You + can invite new members using the **Invite members** button. See [Manage members](./members.md) for details. + +- **Teams**: Displays a list of existing teams and the number of + members in each team. See [Create a team](./manage-a-team.md) for details. + +- **Activity** Displays the audit logs, a chronological list of activities that + occur at organization and repository levels. It provides the org owners a + report of all their team member activities. See [Audit logs](./activity-logs.md) for + details. + +- **Security and access**: Manage security settings. For more information, see [Security](/manuals/security/_index.md). + +- **Organization settings**: Update general settings, manage your company settings, or [deactivate your organization](/manuals/admin/deactivate-account.md). + +{{< /tab >}} +{{< /tabs >}} ## Merge organizations +> [!WARNING] +> +> If you are merging organizations, it is recommended to do so at the *end* of +> your billing cycle. When you merge an organization and downgrade another, you +> will lose seats on your downgraded organization. Docker does not offer +> refunds for downgrades. + If you have multiple organizations that you want to merge into one, complete the following: -1. Based on the number of seats from the secondary organization, [purchase additional seats](../../subscription/core-subscription/add-seats.md) for the primary organization account that you want to keep. +1. Based on the number of seats from the secondary organization, [purchase additional seats](../../subscription/manage-seats.md) for the primary organization account that you want to keep. 2. Manually add users to the primary organization and remove existing users from the secondary organization. 3. Manually move over your data, including all repositories. -4. Once you're done moving all of your users and data, [downgrade](../../subscription/core-subscription/downgrade.md) the secondary account to a free subscription. +4. Once you're done moving all of your users and data, [downgrade](../../subscription/change.md) the secondary account to a free subscription. Note that Docker does not offer refunds for downgrading organizations mid-billing cycle. > [!TIP] > -> If your organization has a Docker Core Business subscription with a purchase order, contact Support or your Account Manager at Docker. -> +> If your organization has a Docker Business subscription with a purchase order, contact Support or your Account Manager at Docker. ## More resources diff --git a/content/manuals/billing/3d-secure.md b/content/manuals/billing/3d-secure.md index d7e46e475f4..32f815c8768 100644 --- a/content/manuals/billing/3d-secure.md +++ b/content/manuals/billing/3d-secure.md @@ -7,16 +7,16 @@ weight: 40 > [!NOTE] > -> [Docker Core subscription](/billing/core-billing/get-started-core/) payments support 3D secure authentication. +> [Docker plan](../subscription/setup.md) payments support 3D secure authentication. 3D Secure (3DS) authentication incorporates an additional security layer for credit card transactions. If you’re making payments for your Docker billing in a region that requires 3DS, or using a payment method that requires 3DS, you’ll need to verify your identity to complete any transactions. The method used to verify your identity varies depending on your banking institution. The following transactions will use 3DS authentication if your payment method requires it. -- Starting a [new paid subscription](/billing/core-billing/get-started-core/) -- Changing your [billing cycle](/billing/core-billing/cycle/) from monthly to annual -- [Upgrading your subscription](/subscription/core-subscription/upgrade/) -- [Adding seats](/subscription/core-subscription/add-seats/) to an existing subscription +- Starting a [new paid subscription](../subscription/setup.md) +- Changing your [billing cycle](/billing/cycle/) from monthly to annual +- [Upgrading your subscription](../subscription/change.md) +- [Adding seats](../subscription/manage-seats.md) to an existing subscription ## Troubleshooting diff --git a/content/manuals/billing/_index.md b/content/manuals/billing/_index.md index 5a046e414a3..0c2d49073d7 100644 --- a/content/manuals/billing/_index.md +++ b/content/manuals/billing/_index.md @@ -1,36 +1,24 @@ --- title: Billing and payments linkTitle: Billing -weight: 200 description: Discover information on billing and payment processes for Docker subscriptions. keywords: billing, invoice, payment, subscription +params: + sidebar: + group: Platform grid_core: -- title: Get started - description: Learn how to set up a Docker Core subscription for a personal account or organization. - link: /billing/core-billing/get-started-core/ - icon: shopping_cart - title: Add or update a payment method description: Learn how to add or update a payment method for your personal account or organization. - link: /billing/core-billing/payment-method/ + link: /billing/payment-method/ icon: credit_score - title: Update the billing information description: Discover how to update the billing information for your personal account or organization. - link: /billing/core-billing/details/ + link: /billing/details/ icon: contract_edit - title: View billing history description: Learn how to view billing history and download past invoices. - link: /billing/core-billing/history/ + link: /billing/history/ icon: payments -grid_products: -- title: Docker Scout billing - description: Explore how to buy and manage a Docker Scout subscription. - link: /billing/scout-billing/ - icon: query_stats -- title: Docker Build Cloud billing - description: Learn how to buy and manage a Docker Build Cloud subscription. - link: /billing/build-billing/ - icon: build -grid_resources: - title: Billing FAQs description: Find the answers you need and explore common questions. link: /billing/faqs/ @@ -45,16 +33,6 @@ grid_resources: icon: wallet --- -Use the resources in this section to manage your billing and payment settings for your Docker subscriptions. - -## Docker Core +Use the resources in this section to manage your billing and payment settings for your Docker subscription plans. {{< grid items="grid_core" >}} - -## Docker products - -{{< grid items="grid_products" >}} - -## Resources - -{{< grid items="grid_resources" >}} diff --git a/content/manuals/billing/build-billing.md b/content/manuals/billing/build-billing.md deleted file mode 100644 index 1505ca4df81..00000000000 --- a/content/manuals/billing/build-billing.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: Docker Build Cloud billing -linkTitle: Docker Build Cloud -description: Learn how to get started with a Docker Build Cloud subscription. -keywords: payments, billing, subscription, build, cloud, Build Cloud, remote builder, buy docker build cloud -weight: 20 ---- - -{{< include "new-plans.md" >}} - -Build Cloud is a next-gen build tool that enables improved build speed, a shared build cache, and native multi-platform builds. Build Cloud is available for free with an existing Docker subscription. To get additional seats and increase your available build minutes, you can buy a subscription to enhance your builds. - -If you don’t have a Docker Core subscription, you can buy Docker Build Cloud Team and create a team in Docker Build Cloud. - -> [!TIP] -> -> You can create a free Docker Personal account and [try Docker Build Cloud for free](/subscription/build-cloud/build-details#docker-personal). Team benefits aren't included. - -In this section, learn how to set up and manage billing for your Build Cloud subscription. For more information about the subscription tiers, see [Build Cloud subscriptions and features](/subscription/build-cloud/build-details). To buy Docker Build Cloud Business, [contact sales](https://www.docker.com/products/build-cloud/#contact_sales). - -## Set up Docker Build Cloud Team subscription - -You can set up a Build Cloud subscription on a monthly or annual plan. To upgrade a Build Cloud Starter subscription, see [Upgrade your subscription](#upgrade-your-subscription). - -### Existing account or organization - -1. Sign in to [Docker Build Cloud](https://build.docker.com/). -2. Choose the user account you want to use to subscribe. This can be a personal account, or an organization account. To buy a subscription for an organization, you need to be an organization owner. -3. Review the plans, then select **Buy now**. -4. For organizations: Select the number of seats you want to buy, then select **Continue to payment**. -5. Review your order, then enter your payment information and select **Subscribe**. - -Subscription renewals charge to the default payment method. - -### New organization - -You can buy a Docker Build Cloud Team subscription if you haven’t created an organization yet. To do so, you can create a team in Docker Build Cloud. - -> [!NOTE] -> -> To create a new organization and start a Docker Build Cloud Team subscription, you need a personal Docker account. You can [sign up](https://hub.docker.com/signup) for free. - -1. Sign in to [Docker Build Cloud](https://build.docker.com/). -2. Select **Create a new team**. -3. On the **Build Cloud Team** card, select **Buy now**. -4. To create your team, enter an organization namespace, company name, and the number of seats you want to buy. -5. Select **Continue to payment**. -6. Follow the on-screen instructions to buy your subscription. - -When your payment is complete, you’ll be redirected to the dashboard for your new team in Docker Build Cloud. Here, you can [invite users](/subscription/build-cloud/manage-seats/) to your team. - -## Manage your subscription - -You can manage your subscription in the Build Cloud dashboard in the **Settings and billing** section. Here you can view your current plan, upgrade your plan, and review build minute usage. - -### View billing history and manage your billing information - -You can view your billing history at any time. - -1. Sign in to [Docker Build Cloud](https://build.docker.com/). -2. Select **Settings and billing**. -3. Select the **Payment methods and billing history** link to go to the billing portal. - -Here you can find your invoice history, download your invoices, and manage your billing information and payment methods. You can also find your next billing date. - -### Upgrade your subscription - -You can upgrade your Docker Build Cloud Starter subscription to a Docker Build Cloud Team subscription in the Build Cloud dashboard. - -1. Sign in to [Docker Build Cloud](https://build.docker.com/). -2. Select **Settings and billing**. -3. Next to the name of your current plan, select **Upgrade plan**. -4. Select **Upgrade now**. -5. Follow the on-screen instructions to buy your subscription. - -### Downgrade your subscription - -You can downgrade your subscription at any time. - -1. Sign in to [Docker Build Cloud](https://build.docker.com/). -2. Select **Settings and billing**. -3. Select **Change plan**. -4. Select **Downgrade**. -5. Follow the on-screen instructions then select **Confirm downgrade**. - -Your subscription remains active until your next billing cycle. diff --git a/content/manuals/billing/core-billing/_index.md b/content/manuals/billing/core-billing/_index.md deleted file mode 100644 index 579c66c2101..00000000000 --- a/content/manuals/billing/core-billing/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -build: - render: never -title: Docker Core billing -linkTitle: Docker Core -weight: 10 ---- diff --git a/content/manuals/billing/core-billing/cycle.md b/content/manuals/billing/core-billing/cycle.md deleted file mode 100644 index e853b6b9fbc..00000000000 --- a/content/manuals/billing/core-billing/cycle.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: Change your billing cycle -weight: 50 -description: Learn to change your billing cycle for your Docker subscription -keywords: billing, cycle, payments, subscription -aliases: -- /billing/cycle/ ---- - -You can pay for a Pro or Team subscription on a monthly or yearly billing cycle. You select your preferred billing cycle when you buy your subscription. - -If you have a monthly billing cycle, you can choose to switch to an annual billing cycle. Note that it's not possible to switch from an annual billing cycle to monthly. - -When you change the billing cycle's duration: -- The next billing date reflects the new cycle. To find your next billing date, see [View renewal date](history.md#view-renewal-date). -- The subscription's start date resets. For example, if the start date of the monthly subscription is March 1st and the end date is April 1st, then after switching the billing duration to March 15th, 2023 the new start date is March 15th, 2023, and the new end date is March 15th, 2024. -- Any unused monthly subscription is prorated and applied as credit towards the new annual period. For example, if you switch from a $10 monthly subscription to a $100 annual plan, deducting the unused monthly value (in this case $5), the migration cost becomes $95 ($100 - $5). The renewal cost after March 15, 2024 is $100. - -{{< include "tax-compliance.md" >}} - -## Personal account - -1. Select your avatar in the top-right corner of Docker Hub. -2. From the drop-down menu select **Billing**. -3. In the bottom-right of the **Plan** tab, select **Switch to annual billing**. -4. Review the information displayed on the **Change to an Annual subscription** page and select **Accept Terms and Purchase** to confirm. - -## Organization - -> [!NOTE] -> -> You must be an organization owner to make changes to the payment information. - -1. In Docker Hub, select **Organizations**. -2. Select the organization that you want to change the payment method for. -3. In the bottom-right of the **Plan** tab, select **Switch to annual billing**. -4. Review the information displayed on the **Change to an Annual subscription** page and select **Accept Terms and Purchase** to confirm. diff --git a/content/manuals/billing/core-billing/details.md b/content/manuals/billing/core-billing/details.md deleted file mode 100644 index f96e0883e44..00000000000 --- a/content/manuals/billing/core-billing/details.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: Update the billing information -weight: 30 -description: Learn how to update your billing information in Docker Hub -keywords: payments, billing, subscription, invoices -aliases: -- /billing/details/ ---- - -{{< include "tax-compliance.md" >}} - -You can update the billing information for your personal account or for an organization. When you update your billing information, these changes apply to future billing invoices. - -> [!IMPORTANT] -> -> You can't update an existing invoice, including paid and unpaid invoices. - -The billing information provided appears on all your billing invoices. The email address provided is where Docker sends all invoices and other [billing-related communication](#update-your-email-address-that-receives-billing-invoices). - -## Manage billing information - -### Personal account - -1. Select your avatar in the top-right corner of Docker Hub. -2. From the drop-down menu select **Billing**. -3. Select **Billing Address**. -4. Enter your updated billing information. -5. Select **Submit**. - -### Organization - -> [!NOTE] -> -> You must be an organization owner to make changes to the billing information. - -1. Select your avatar in the top-right corner of Docker Hub. -2. From the drop-down menu select **Billing**. -3. Select the organization that you want to change the payment method for. -4. Select **Billing Address**. -5. Enter your updated billing information. -6. Select **Submit**. - -## Update your email address that receives billing invoices - -Docker sends the following billing-related emails: - -- Confirmation of a new subscription. -- Confirmation of paid invoices. -- Notifications of credit or debit card payment failures. -- Notifications of credit or debit card expiration. -- Confirmation of a cancelled subscription -- Reminders of subscription renewals for annual subscribers. This is sent 14 days before the renewal date. - -You can update the email address that receives billing invoices at any time. - -### Personal account - -1. Select your avatar in the top-right corner of Docker Hub. -2. From the drop-down menu select **Billing**. -3. Select **Billing Address**. -4. Update the email address in the **Billing contact** section. -5. Select **Submit**. - -### Organizations - -1. Select your avatar in the top-right corner of Docker Hub. -2. From the drop-down menu select **Billing**. -3. Select the name of the organization. -4. Select **Billing Address**. -5. Update the email address in the **Billing contact** section. -6. Select **Submit**. diff --git a/content/manuals/billing/core-billing/get-started-core.md b/content/manuals/billing/core-billing/get-started-core.md deleted file mode 100644 index 123f026b271..00000000000 --- a/content/manuals/billing/core-billing/get-started-core.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: Get started with Docker Core -weight: 10 -description: Learn how to start your Docker Core subscription. -keywords: payments, billing, subscription, invoices, docker core, subscribe ---- - -{{< include "new-plans.md" >}} - -Docker Core subscriptions offer features and benefits to support both new and professional developers, as well as plans for individuals, teams, and enterprise businesses. To learn more about what's included with each tier, see [Docker Core subscriptions and features](../../subscription/core-subscription/details.md) and [Docker Pricing](https://www.docker.com/pricing/). - -In this section, learn how to get started with a Docker Core subscription for individuals or for organizations. Before you begin, make sure you have a [Docker ID](/accounts/create-account/). - -{{< include "tax-compliance.md" >}} - -## Set up Docker Core subscription for personal account - -1. Sign in to your Docker account. -2. Select your avatar in the top-right corner then select **Billing**. -3. In **Billing Details**, select your personal account. -4. Select **Buy now**. -5. To continue to use [**Docker Core Personal**](/manuals/subscription/core-subscription/details.md#docker-personal), select **Continue with Personal**. To buy [**Docker Core Pro**](/manuals/subscription/core-subscription/details.md#docker-pro), select **Buy Now** on the **Pro** card. -6. Enter your billing information, then select **Submit**. -7. Follow the on-screen instructions to confirm monthly or annual billing cycle and enter your payment information. -8. Select **Subscribe**. - -This routes you back to the **Billing Details** section. Your subscription entitles you right away to the features available for your plan. You can review your plan here at any time. - -## Set up Docker Core subscription for organizations - -You can subscribe a new or existing organization to a Docker Core plan. Only organization owners can manage billing for the organization. - -To learn how to start a Docker Core subscription for a new organization, see [Create your organization](../../admin/organization/orgs.md). - -To learn how to upgrade a Docker Core subscription for an existing organization, see [Upgrade your subscription](../../subscription/core-subscription/upgrade.md). diff --git a/content/manuals/billing/core-billing/history.md b/content/manuals/billing/core-billing/history.md deleted file mode 100644 index 94d19d1d436..00000000000 --- a/content/manuals/billing/core-billing/history.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: View billing history -weight: 40 -description: Discover how to view your billing history in Docker Hub -keywords: payments, billing, subscription, invoices, renewals, invoice management, billing administration -aliases: -- /billing/history/ ---- - -In this section, learn how you can view your billing history, manage your invoices, and verify your renewal date. All monthly and annual subscriptions are automatically renewed at the end of the term using the original form of payment. - -{{< include "tax-compliance.md" >}} - -## Invoices - -Your invoice includes the following: - -- Invoice number -- Date of issue -- Date due -- Your bill to information -- Amount due -- Description of your order, quantity if applicable, unit price, and amount - -Amounts are in USD. - -The information listed in the **Bill** to section is based on your billing information. Not all fields are required. The billing information includes the following: - -- Name (required) - the name of the administrator or company. -- Email address (required) - the email address that receives all billing-related emails for the account. -- Address (required) -- Phone number -- Tax ID or VAT - -You can’t make changes to a paid or unpaid billing invoice. When you update your billing information, this change won't update an existing invoice. If you need to update your billing information, make sure you do so before your subscription renewal date when your invoice is finalized. For more information, see [Update the billing information](details.md). - -### View renewal date - -You receive your invoice when the subscription renews. To verify your renewal date, sign in to Hub, then: - -1. Select your user avatar to open the drop-down menu. -2. Select **Billing**. -3. Select the user or organization account to view the billing details. Here you can find your renewal date and the renewal amount. - -### Include your VAT number on your invoice - -Update your billing information to include your VAT number: - -1. Sign in to Docker Hub. -2. For user accounts, Select your avatar in the top-right corner, then **Billing**. For organizations, select the name of the organization. -3. Select the **Payment methods and billing history** link. -4. In the **Billing Information** section, select **Update information**. -5. In the **Tax ID** section, select the ID type and enter your VAT number. -6. Select **Save**. - -Your VAT number will be included on your next invoice. - -## View billing history - -You can view the billing history and download past invoices for a personal account or organization. - -### Personal account - -1. Select your avatar in the top-right corner of Docker Hub. -2. From the drop-down menu select **Billing**. -3. Select the **Payment methods and billing history** link. - You can find your past invoices in the **Invoice History** section. - -From here you can download an invoice. - -### Organization - -> [!NOTE] -> -> You must be an owner of the organization to view the billing history. - -1. Select your avatar in the top-right corner of Docker Hub. -2. From the drop-down menu select **Billing**. -3. Select the organization that you want to change the payment method for. -4. Select the **Payment methods and billing history** link. - You can find your past invoices in the **Invoice History** section. - -From here you can download an invoice. diff --git a/content/manuals/billing/cycle.md b/content/manuals/billing/cycle.md new file mode 100644 index 00000000000..9e461d054cb --- /dev/null +++ b/content/manuals/billing/cycle.md @@ -0,0 +1,88 @@ +--- +title: Change your billing cycle +weight: 50 +description: Learn to change your billing cycle for your Docker subscription +keywords: billing, cycle, payments, subscription +--- + +You can pay for a subscription plan on a monthly or yearly billing cycle. You select your preferred billing cycle when you buy your subscription. + +> [!NOTE] +> +> Business plan is available only on yearly billing cycle. + +If you have a monthly billing cycle, you can choose to switch to an annual billing cycle. + +> [!NOTE] +> +> You can't switch from an annual billing cycle to a monthly cycle. + +When you change the billing cycle's duration: + +- The next billing date reflects the new cycle. To find your next billing date, see [View renewal date](history.md#view-renewal-date). +- The subscription's start date resets. For example, if the start date of the monthly subscription is March 1st and the end date is April 1st, then after switching the billing duration to March 15th, 2024 the new start date is March 15th, 2024, and the new end date is March 15th, 2025. +- Any unused monthly subscription is prorated and applied as credit towards the new annual period. For example, if you switch from a $10 monthly subscription to a $100 annual plan, deducting the unused monthly value (in this case $5), the migration cost becomes $95 ($100 - $5). The renewal cost after March 15, 2025 is $100. + +{{< include "tax-compliance.md" >}} + +## Personal account + +{{< tabs >}} +{{< tab name="Docker plan" >}} + +To change your billing cycle: + +1. Sign in to [Docker Home](https://app.docker.com/). +2. Under Settings and administration, select **Billing**. +3. On the plans and usage page, select **Switch to annual billing**. +4. Verify your billing information. +5. Select **Continue to payment**. +6. Verify payment information and select **Upgrade subscription**. + +The billing plans and usage page will now reflect your new annual plan details. + +{{< /tab >}} +{{< tab name="Legacy Docker plan" >}} + +To change your billing cycle: + +1. Sign in to [Docker Hub](https://hub.docker.com). +2. Select your avatar in the top-right corner. +3. From the drop-down menu select **Billing**. +4. In the bottom-right of the **Plan** tab, select **Switch to annual billing**. +5. Review the information displayed on the **Change to an Annual subscription** page and select **Accept Terms and Purchase** to confirm. + +{{< /tab >}} +{{< /tabs >}} + +## Organization + +> [!NOTE] +> +> You must be an organization owner to make changes to the payment information. + +{{< tabs >}} +{{< tab name="Docker plan" >}} + +To change your organization's billing cycle: + +1. Sign in to [Docker Home](https://app.docker.com/). +2. Under Settings and administration, select **Billing**. +3. On the plans and usage page, select **Switch to annual billing**. +4. Verify your billing information. +5. Select **Continue to payment**. +6. Verify payment information and select **Upgrade subscription**. + +{{< /tab >}} +{{< tab name="Legacy Docker plan" >}} + +To change your organization's billing cycle: + +1. Sign in to [Docker Hub](https://hub.docker.com). +2. Select **Organizations** from the top-level navigation. +3. Select the organization that you want to change the payment method for. +4. In the bottom-right of the **Plan** tab, select **Switch to annual billing**. +5. Review the information displayed on the **Change to an Annual subscription** page and select **Accept Terms and Purchase** to confirm. + +{{< /tab >}} +{{< /tabs >}} \ No newline at end of file diff --git a/content/manuals/billing/details.md b/content/manuals/billing/details.md new file mode 100644 index 00000000000..d3cee9477e6 --- /dev/null +++ b/content/manuals/billing/details.md @@ -0,0 +1,144 @@ +--- +title: Update billing information +weight: 30 +description: Learn how to update your billing information in Docker Hub +keywords: payments, billing, subscription, invoices +--- + +You can update the billing information for your personal account or for an organization. When you update your billing information, these changes apply to future billing invoices. Note that you can't update an existing invoice, including paid and unpaid invoices. + +The billing information provided appears on all your billing invoices. The email address provided is where Docker sends all invoices and other [billing-related communication](#update-your-billing-invoice-email-address). + +{{< include "tax-compliance.md" >}} + +## Manage billing information + +### Personal account + +{{< tabs >}} +{{< tab name="Docker plan" >}} + +To update your billing information: + +1. Sign in to [Docker Home](https://app.docker.com/). +2. Under Settings and administration, select **Billing**. +3. Select **Billing information** from the left-hand navigation. +4. On your billing information card, select **Change**. +5. Update your billing contact and billing address information, then select **Update**. + +{{< /tab >}} +{{< tab name="Legacy Docker plan" >}} + +To update your billing information: + +1. Sign in to [Docker Hub](https://hub.docker.com). +2. Select your avatar in the top-right corner. +3. From the drop-down menu, select **Billing**. +4. Select **Billing Address** and enter your updated billing information. +5. Select **Submit**. + +{{< /tab >}} +{{< /tabs >}} + +### Organization + +> [!NOTE] +> +> You must be an organization owner to make changes to the billing information. + +{{< tabs >}} +{{< tab name="Docker plan" >}} + +To update your billing information: + +1. Sign in to [Docker Home](https://app.docker.com/). +2. Under Settings and administration, select **Billing**. +3. Select **Billing information** from the left-hand navigation. +4. On your billing information card, select **Change**. +5. Update your billing contact and billing address information, then select **Update**. + +{{< /tab >}} +{{< tab name="Legacy Docker plan" >}} + +To update your billing information: + +1. Sign in to [Docker Hub](https://hub.docker.com). +2. Select your avatar in the top-right corner. +3. From the drop-down menu select **Billing**. +4. Select the organization that you want to change the payment method for. +5. Select **Billing Address**. +6. Enter your updated billing information. +7. Select **Submit**. + +{{< /tab >}} +{{< /tabs >}} + +## Update your billing invoice email address + +Docker sends the following billing-related emails: + +- Confirmation of a new subscription. +- Confirmation of paid invoices. +- Notifications of credit or debit card payment failures. +- Notifications of credit or debit card expiration. +- Confirmation of a cancelled subscription +- Reminders of subscription renewals for annual subscribers. This is sent 14 days before the renewal date. + +You can update the email address that receives billing invoices at any time. + +### Personal account + +{{< tabs >}} +{{< tab name="Docker plan" >}} + +To update your billing email address: + +1. Sign in to [Docker Home](https://app.docker.com/). +2. Under Settings and administration, select **Billing**. +3. Select **Billing information** from the left-hand navigation. +4. On your billing information card, select **Change**. +5. Update your billing contact information and select **Update**. + +{{< /tab >}} +{{< tab name="Legacy Docker plan" >}} + +To update your billing email address: + +1. Sign in to [Docker Hub](https://hub.docker.com). +2. Select your avatar in the top-right corner. +3. From the drop-down menu select **Billing**. +4. Select **Billing Address**. +5. Update the email address in the **Billing contact** section. +6. Select **Submit**. + +{{< /tab >}} +{{< /tabs >}} + +### Organizations + +{{< tabs >}} +{{< tab name="Docker plan" >}} + +To update your billing email address: + +1. Sign in to [Docker Home](https://app.docker.com/). +2. Under Settings and administration, select **Billing**. +3. Select **Billing information** from the left-hand navigation. +4. On your billing information card, select **Change**. +5. Update your billing contact information and select **Update**. + +{{< /tab >}} +{{< tab name="Legacy Docker plan" >}} + +To update your billing email address: + +1. Sign in to [Docker Hub](https://hub.docker.com). +2. Select your avatar in the top-right corner. +3. From the drop-down menu select **Billing**. +4. Select the name of the organization. +5. Select **Billing Address**. +6. Update the email address in the **Billing contact** section. +7. Select **Submit**. + +{{< /tab >}} +{{< /tabs >}} diff --git a/content/manuals/billing/docker-hub-pricing.md b/content/manuals/billing/docker-hub-pricing.md new file mode 100644 index 00000000000..9b97802cde7 --- /dev/null +++ b/content/manuals/billing/docker-hub-pricing.md @@ -0,0 +1,116 @@ +--- +title: Docker Hub storage pricing +description: Learn how Docker Hub storage pricing is calculated +keywords: docker hub, storage, payments, billing, subscription +weight: 55 +--- + +This guide explains how Docker Hub storage is measured, calculated, and billed +to help you understand your storage consumption and costs. + +> [!NOTE] +> +> Docker Hub plan limits will take effect on March 1, 2025. No charge on Docker Hub image pulls +or storage will be incurred from December 10, 2024 and February 28, 2025. + +## How storage is measured + +Docker Hub measures storage using: +- Hourly measurement: Storage usage is recorded every hour and expressed in **GB-hours**. This value represents the total storage your repositories consume during each hour. +- Monthly aggregation: At the end of each month, hourly storage usage is divided by the number of hours in that month. + + For example, 900 GB-hours of storage in a 30-day month (720 hours) equates to 900 / 720 = 1.25 gigabytes of monthly storage (GB-month). + +## How storage is calculated + +Docker subscription plans include a specific amount of allocated +private repository storage: + +- Personal plan: Includes up to 2GB of storage. +- Pro plan: Includes up to 5GB of storage. +- Team plan: Includes up to 50GB of storage. +- Business plan: Includes up to 500GB of storage. + +Docker Hub determines additional charges based on your average monthly usage of private repository storage. + +If you go over your allocated private repository storage, you will incur overage +costs. To calculate overage costs the included storage for your plan is subtracted from your average monthly +usage. + +## Docker Hub consumption pricing + +At the end of the month, Docker calculates your total storage usage +and compares it to your plan's included amount. If applicable, the overage cost +is billed to your account as an overage invoice. + +There are two billing models for paying for additional Docker Hub storage: + +- Pre-pay: Pay in advance for a specified amount of storage. + + > [!NOTE] + > + > Pre-purchased storage expires at the end of your subscription period. + +- Post-pay: Receive an overage invoice for storage usage that exceeds your subscription plan's included amount +at the end of your billing cycle. + +### Storage carryover + +If you pre-pay for storage, your purchased storage is valid for the entire subscription period. You can use it any time during that period, and any unused portion will roll over to the next month until the subscription period ends. + +In the following example, a customer with an annual Business plan pre-pays for 500GB of storage for the year. Their plan includes a base allocation of 500GB of storage per month. +- In January, they use 510 GB-month, exceed their base allocation, and use 10GB from their pre-paid storage. Their remaining pre-paid +storage is 490GB. +- In February, they use 450 GB-month, and do not exceed their base allocation. They do not use any of their pre-paid storage, so it remains at 490GB. +- In March, they use 600 GB-month, exceed their base allocation, and use 100GB from their pre-paid storage. Their remaining pre-paid storage is 390GB. + +| | January | February | March | +|---------------------------------|----------|----------|---------| +| Included GB-month | 500 | 500 | 500 | +| Used storage in month | 510 | 450 | 600 | +| Overage in GB-month | 10 | 0 | 100 | +| Remaining pre-purchased storage | 490 | 490 | 390 | + +At the end of March, the customer has 390GB of pre-purchased storage left to use for the rest of the year. + +## Examples + +### Business plan with pre-pay + +In the following example, a customer with a Business plan has 500GB included in their subscription plan. They pre-pay +for 1700 GB. +- In January, they use 100 GB-month, meaning they did not use any of their pre-pay storage. Their pre-pay storage rolls over to the next month. +- In February, they use 650 GB-month, exceed their base allocation, and use 150GB from their pre-pay storage. +- In March, they use 1800 GB-month, exceed their base allocation, and use 1300GB from their pre-pay storage. +- In April, they use 950 GB-month, exceed their base allocation, and going over their pre-pay storage. This results in an invoice of $14.00 for the storage overage. + +| | January | February | March | April | +|--------------------------|---------|----------|-------|--------| +| Included GB-month | 500 | 500 | 500 | 500 | +| Pre-purchased GB | 1700 | 1700 | 1700 | 1700 | +| Used storage in month | 100 | 650 | 1800 | 950 | +| Remaining pre-purchased | 1700 | 1550 | 250 | -200 | +| Overage invoice | $0.00 | $0.00 | $0.00 | $14.00 | + +For information on storage pricing, see the [Docker Pricing](https://www.docker.com/pricing/) page. + +### Business plan with post-pay + +In the following example, a customer with a Business plan has 500GB included in their subscription plan. They do +not pre-pay for additional storage consumption. +- In January, they use 100 GB-month and do not exceed their base allocation. +- In February, they use 650 GB-month, going over their base allocation by 150 GB-month. They are sent +an overage invoice for $10.50. +- In March, they use 1800 GB-month, going over their base allocation by 1300 GB-month. They are sent +an overage invoice for $91.00. +- In April, they use 950 GB-month, going over their base allocation by 450 GB-month. They are sent an +overage invoice for $31.50. + +| | January | February | March | April | +|-----------------------------------|---------|----------|---------|--------| +| Included GB-month | 500 | 500 | 500 | 500 | +| Used storage in month | 100 | 650 | 1800 | 950 | +| Overage in GB-month | 0 | 150 | 1300 | 450 | +| Overage invoice | $0.00 | $10.50 | $130.00 | $45.00 | + +For information on storage pricing, see the [Docker Pricing](https://www.docker.com/pricing/) page. \ No newline at end of file diff --git a/content/manuals/billing/faqs.md b/content/manuals/billing/faqs.md index 6a5204f4727..623b33e7dff 100644 --- a/content/manuals/billing/faqs.md +++ b/content/manuals/billing/faqs.md @@ -37,7 +37,7 @@ Once the grace period is over and the invoice is still not paid, the subscriptio Starting July 1, 2024, Docker will begin collecting sales tax on subscription fees in compliance with state regulations for customers in the United States. For global customers subject to VAT, the implementation will start rolling out on July 1, 2024. Note that while the rollout begins on this date, VAT charges may not apply to all applicable subscriptions immediately. -To ensure that tax assessments are correct, make sure that your billing information and VAT/Tax ID, if applicable, are updated. See [Update the billing information](/billing/core-billing/details/). +To ensure that tax assessments are correct, make sure that your billing information and VAT/Tax ID, if applicable, are updated. See [Update the billing information](/billing/details/). ### How do I certify my tax exempt status? diff --git a/content/manuals/billing/history.md b/content/manuals/billing/history.md new file mode 100644 index 00000000000..534c7fb7d8f --- /dev/null +++ b/content/manuals/billing/history.md @@ -0,0 +1,156 @@ +--- +title: View billing history +weight: 40 +description: Discover how to view your billing history in Docker Hub +keywords: payments, billing, subscription, invoices, renewals, invoice management, billing administration +--- + +In this section, learn how you can view your billing history, manage your invoices, and verify your renewal date. All monthly and annual subscriptions are automatically renewed at the end of the term using the original form of payment. + +{{< include "tax-compliance.md" >}} + +## Invoices + +Your invoice includes the following: + +- Invoice number +- Date of issue +- Date due +- Your "Bill to" information +- Amount due (in USD) +- Description of your order, quantity if applicable, unit price, and amount (in USD) + +The information listed in the **Bill to** section of your invoice is based on your billing information. Not all fields are required. The billing information includes the following: + +- Name (required): The name of the administrator or company +- Email address (required): The email address that receives all billing-related emails for the account +- Address (required) +- Phone number +- Tax ID or VAT + +You can’t make changes to a paid or unpaid billing invoice. When you update your billing information, this change won't update an existing invoice. If you need to update your billing information, make sure you do so before your subscription renewal date when your invoice is finalized. For more information, see [Update the billing information](details.md). + +### View renewal date + +{{< tabs >}} +{{< tab name="Docker plan" >}} + +You receive your invoice when the subscription renews. To verify your renewal date, sign in to the [Docker Home Billing](https://app.docker.com/billing). Your renewal date and amount are displayed on your subscription plan card. + + +{{< /tab >}} +{{< tab name="Legacy Docker plan" >}} + +You receive your invoice when the subscription renews. To verify your renewal date: + +1. Sign in to [Docker Hub](https://hub.docker.com). +2. Select your user avatar to open the drop-down menu. +3. Select **Billing**. +4. Select the user or organization account to view the billing details. Here you can find your renewal date and the renewal amount. + +{{< /tab >}} +{{< /tabs >}} + +### Include your VAT number on your invoice + +> [!NOTE] +> +> If the VAT number field is not available, complete the [Contact Support form](https://hub.docker.com/support/contact/). This field may need to be manually added. + +{{< tabs >}} +{{< tab name="Docker plan" >}} + +To add or update your VAT number: + +1. Sign in to [Docker Home](https://app.docker.com/). +2. Under Settings and administration, select **Billing**. +3. Select **Billing information** from the left-hand menu. +4. Select **Change** on your billing information card. +5. Ensure the **I'm purchasing as a business** checkbox is checked. +6. Enter your VAT number in the Tax ID section. +7. Select **Update**. + +Your VAT number will be included on your next invoice. + +{{< /tab >}} +{{< tab name="Legacy Docker plan" >}} + +To add or update your VAT number: + +1. Sign in to [Docker Hub](https://hub.docker.com). +2. For user accounts, Select your avatar in the top-right corner, then **Billing**. For organizations, select the name of the organization. +3. Select the **Billing address** link. +4. In the **Billing Information** section, select **Update information**. +5. Enter your VAT number in the Tax ID section. +6. Select **Save**. + +Your VAT number will be included on your next invoice. + +{{< /tab >}} +{{< /tabs >}} + +## View billing history + +You can view the billing history and download past invoices for a personal account or organization. + +### Personal account + +{{< tabs >}} +{{< tab name="Docker plan" >}} + +To view billing history: + +1. Sign in to [Docker Home](https://app.docker.com/). +2. Under Settings and administration, select **Billing**. +3. Select **Invoices** from the left-hand menu. +4. Optional. Select the **Invoice number** to open invoice details. +5. Optional. Select the **Download** button to download an invoice. + +{{< /tab >}} +{{< tab name="Legacy Docker plan" >}} + +To view billing history: + +1. Sign in to [Docker Hub](https://hub.docker.com). +2. Select your avatar in the top-right corner. +3. From the drop-down menu select **Billing**. +4. Select the **Payment methods and billing history** link. + You can find your past invoices in the **Invoice History** section. + +From here you can download an invoice. + +{{< /tab >}} +{{< /tabs >}} + +### Organization + +> [!NOTE] +> +> You must be an owner of the organization to view the billing history. + +{{< tabs >}} +{{< tab name="Docker plan" >}} + +To view billing history: + +1. Sign in to [Docker Home](https://app.docker.com/). +2. Under Settings and administration, select **Billing**. +3. Select **Invoices** from the left-hand menu. +4. Optional. Select the **invoice number** to open invoice details. +5. Optional. Select the **download** button to download an invoice. + +{{< /tab >}} +{{< tab name="Legacy Docker plan" >}} + +To view billing history: + +1. Sign in to [Docker Hub](https://hub.docker.com). +2. Select your avatar in the top-right corner. +3. From the drop-down menu select **Billing**. +4. Select the **Payment methods and billing history** link. + You can find your past invoices in the **Invoice History** section. + +From here you can download an invoice. + +{{< /tab >}} +{{< /tabs >}} diff --git a/content/manuals/billing/core-billing/payment-method.md b/content/manuals/billing/payment-method.md similarity index 53% rename from content/manuals/billing/core-billing/payment-method.md rename to content/manuals/billing/payment-method.md index 3c07357e597..8c9dc7eb439 100644 --- a/content/manuals/billing/core-billing/payment-method.md +++ b/content/manuals/billing/payment-method.md @@ -4,7 +4,7 @@ weight: 20 description: Learn how to add or update a payment method in Docker Hub keywords: payments, billing, subscription, supported payment methods, failed payments, coupons billing: -- /billing/payment-method/ +- /billing/core-billing/payment-method/ --- This page describes how to add or update a payment method for your personal account or for an organization. @@ -13,7 +13,7 @@ You can add a payment method or update your account's existing payment method at > [!IMPORTANT] > -> If you want to remove all payment methods, you must first downgrade your subscription to a free plan. See [Downgrade](../../subscription/core-subscription/downgrade.md). +> If you want to remove all payment methods, you must first downgrade your subscription to a free plan. See [Downgrade](../subscription/change.md). The following payment methods are supported: @@ -33,29 +33,76 @@ All currency, for example the amount listed on your billing invoice, is in Unite ### Personal account -1. Select your avatar in the top-right corner of Docker Hub. -2. From the drop-down menu select **Billing**. -3. Select the **Payment methods and billing history** link. -4. In the **Payment method** section, select **Add payment method**. -5. Enter your new payment information, then select **Add**. -6. Select the **Actions** icon, then select **Make default** to ensure that your new payment method applies to all purchases and subscriptions. -7. Optional. You can remove non-default payment methods by selecting the **Actions** icon. Then, select **Delete**. +{{< tabs >}} +{{< tab name="Docker plan" >}} -### Organization +To add a payment method: -> [!NOTE] -> -> You must be an organization owner to make changes to the payment information. +1. Sign in to [Docker Home](https://app.docker.com/). +2. Under Settings and administration, select **Billing**. +3. Select **Payment methods** from the left-hand menu. +4. Select **Add payment method**. +5. Enter your new payment information. +6. Select **Add**. +7. Optional. You can set a new default payment method by selecting the **Set as default** action. +8. Optional. You can remove non-default payment methods by selecting the **Delete** action. + +{{< /tab >}} +{{< tab name="Legacy Docker plan" >}} -1. Select your avatar in the top-right corner of Docker Hub. -2. From the drop-down menu select **Billing**. -3. Select the organization account you want to update. +To add a payment method: + +1. Sign in to [Docker Hub](https://hub.docker.com). +2. Select your avatar in the top-right corner. +3. From the drop-down menu select **Billing**. 4. Select the **Payment methods and billing history** link. -5. In the **Payment Method** section, select **Add payment method**. +5. In the **Payment method** section, select **Add payment method**. 6. Enter your new payment information, then select **Add**. 7. Select the **Actions** icon, then select **Make default** to ensure that your new payment method applies to all purchases and subscriptions. 8. Optional. You can remove non-default payment methods by selecting the **Actions** icon. Then, select **Delete**. +{{< /tab >}} +{{< /tabs >}} + +### Organization + +> [!NOTE] +> +> You must be an organization owner to make changes to the payment information. + +{{< tabs >}} +{{< tab name="Docker plan" >}} + +To add a payment method: + +1. Sign in to [Docker Home](https://app.docker.com/). +2. Under Settings and administration, select **Billing**. +3. Choose your organization from the top-left drop-down. +4. Select **Payment methods** from the left-hand menu. +5. Select **Add payment method**. +6. Enter your new payment information. +7. Select **Add**. +8. Optional. You can set a new default payment method by selecting the **Set as default** action. +9. Optional. You can remove non-default payment methods by selecting the **Delete** action. + +{{< /tab >}} +{{< tab name="Legacy Docker plan" >}} + +To add a payment method: + +1. Sign in to [Docker Hub](https://hub.docker.com). +2. Select your avatar in the top-right corner. +3. From the drop-down menu select **Billing**. +4. Select the organization account you want to update. +5. Select the **Payment methods and billing history** link. +6. In the **Payment Method** section, select **Add payment method**. +7. Enter your new payment information, then select **Add**. +8. Select the **Actions** icon, then select **Make default** to ensure that your new payment method applies to all purchases and subscriptions. +9. Optional. You can remove non-default payment methods by selecting the **Actions** icon. Then, select **Delete**. + +{{< /tab >}} +{{< /tabs >}} + ## Failed payments If your subscription payment fails, there is a grace period of 15 days, including the due date. Docker retries to collect the payment 3 times using the following schedule: @@ -64,7 +111,7 @@ If your subscription payment fails, there is a grace period of 15 days, includin - 5 days after the previous attempt - 7 days after the previous attempt -Docker also sends an email notification `Action Required - Credit Card Payment Failed` with an attached unpaid invoice after each failed payment attempt. +Docker also sends an email notification `Action Required - Credit Card Payment Failed` with an attached unpaid invoice after each failed payment attempt. Once the grace period is over and the invoice is still not paid, the subscription downgrades to a free plan and all paid features are disabled. diff --git a/content/manuals/billing/scout-billing.md b/content/manuals/billing/scout-billing.md deleted file mode 100644 index 7376f3cf0a4..00000000000 --- a/content/manuals/billing/scout-billing.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: Docker Scout billing -linkTitle: Docker Scout -description: Learn how to get started with and manage you Docker Scout subscription. -keywords: payments, billing, subscription, scout, buy docker scout, subscribe to docker scout -weight: 30 ---- - -{{< include "new-plans.md" >}} - -Docker Scout lets users secure their software supply chain and continuously observe and improve their security posture. Docker Scout is free for up to 3 repositories. You can buy Docker Scout Team or Docker Scout Business to turn on Docker Scout for additional repositories. See [Docker Scout subscription and features](../subscription/scout-details.md) to select the plan that works for you. - -In this section, learn how to buy and manage a Docker Scout Team subscription for your personal account or for an organization. If you're an organization with multiple teams, a Docker Scout Business plan may be better. To buy Docker Scout Business, [contact sales](https://www.docker.com/products/docker-scout/#contact-sales). - -> [!NOTE] -> -> You need to be an owner to manage billing for an organization. -> - -## Set up Docker Scout Team subscription - -1. Go to [Billing settings](https://scout.docker.com/settings/billing) in the Docker Scout Dashboard. -2. The default plan is Docker Scout Free. Next to the plan name, select **Change plan**. -3. Select **Purchase Scout Team**. -4. Choose annual or monthly billing cycle, then select the number of Scout-enabled repositories you want from the repository quantity drop-down. You can select groups of five. -5. Select **Continue to payment**. -6. This redirects you to the payment processing page. Enter your email if this field isn't pre-populated. Then, enter your payment information. -7. Select **Subscribe**. - -Subscribing redirects you back to the billing page in Docker Scout, where you can find your active Docker Scout plan. Once your purchase is complete, you receive a confirmation email and a copy of your invoice. - -## Manage your subscription - -To access your subscription details, sign in to [Docker Scout](https://scout.docker.com/) with your Docker ID. Select **Settings**, then **Billing** for your personal account or organization that's subscribed. - -Here you can find: - -- The type of billing cycle you have, annual or monthly -- How many repositories are Scout-enabled -- Your subscription renewal date - -Renewals charge to the original credit card used to buy Docker Scout Team. Select the **Payment methods and billing history** link to update your payment information or view past invoices. - -### Update number of repositories for your subscription - -On a Docker Scout Team plan, you can add or remove the number of repositories associated with your subscription. The number of repositories you can add or remove are bundled in groups of five. - -To add repositories: - -1. Go to [Billing settings](https://scout.docker.com/settings/billing) in the Docker Scout Dashboard. -2. Select **Add repositories**. -3. Select the number of repositories you want to add, then select **Purchase**. - -This purchase charges your default payment method. - -To remove repositories: - -1. Go to [Billing settings](https://scout.docker.com/settings/billing) in the Docker Scout Dashboard. -2. Select **Remove repositories**. -3. Select the number of repositories you want to remove, then select **Remove**. - -The number of repositories updates on your next billing cycle. - -> [!NOTE] -> -> You can't add repositories while repository removal is pending. You can add repositories again during the next billing cycle. -> - -### Downgrade your subscription - -You can downgrade from Docker Scout Team or Docker Scout Business to a Docker Scout Free subscription at anytime before the renewal date. Your subscription features remain available until the end of your billing cycle. - -> [!TIP] -> -> To downgrade from Docker Scout Business to Docker Scout Team, [contact](https://hub.docker.com/support/contact) your account manager to cancel so you can start a Docker Scout Team subscription. -> - -1. Go to [Billing settings](https://scout.docker.com/settings/billing) in the Docker Scout Dashboard. -2. Find your Docker Scout plan, then select **Change plan**. -3. On the Docker Scout Free card, select **Downgrade to this plan**, then review the warning message. -4. To confirm the downgrade, select **Continue to Downgrade**. - -### Cancel your subscription downgrade - -You can cancel a subscription downgrade at anytime before the end of the billing cycle. You can find this date in the details for your current plan. - -1. Go to [Billing settings](https://scout.docker.com/settings/billing) in the Docker Scout Dashboard. -2. Select **Cancel the downgrade** in the top-right corner of your billing details page. diff --git a/content/manuals/billing/tax-certificate.md b/content/manuals/billing/tax-certificate.md index 3e5d8d84617..ecac453404a 100644 --- a/content/manuals/billing/tax-certificate.md +++ b/content/manuals/billing/tax-certificate.md @@ -5,7 +5,7 @@ keywords: billing, renewal, payments, tax weight: 50 --- -If you're a customer in the United States and you're exempt from sales tax, you can register a valid tax exemption certificate with Docker's Support team. If you're a global customer subject to VAT, make sure that you provide your [VAT number](/billing/core-billing/history/#include-your-vat-number-on-your-invoice). +If you're a customer in the United States and you're exempt from sales tax, you can register a valid tax exemption certificate with Docker's Support team. If you're a global customer subject to VAT, make sure that you provide your [VAT number](/billing/history/#include-your-vat-number-on-your-invoice). {{< include "tax-compliance.md" >}} @@ -31,7 +31,7 @@ Palo Alto, CA 94306 1. [Submit a Docker Support ticket](https://hub.docker.com/support/contact?topic=Billing&subtopic=Tax%20information) to initiate the process to register a tax certificate. 2. Enter the required information. -3. In the **Additional Information** field, list the Docker ID/namespace(s) of the accounts that you want to apply the tax exemption certificate to. +3. In the **Additional Information** field, list the Docker ID/namespace(s) of the accounts that you want to apply the tax exemption certificate to. > [!TIP] > diff --git a/content/manuals/build-cloud/_index.md b/content/manuals/build-cloud/_index.md index adca1293e9b..04600233b8c 100644 --- a/content/manuals/build-cloud/_index.md +++ b/content/manuals/build-cloud/_index.md @@ -1,8 +1,11 @@ --- title: Docker Build Cloud -weight: 100 +weight: 20 description: Find documentation on Docker Build Cloud to help you build your container images faster, both locally and in CI keywords: build, cloud, cloud build, remote builder +params: + sidebar: + group: Products aliases: - /build/cloud/faq/ - /build/cloud/ @@ -52,19 +55,16 @@ data between cloud builders. ## Get Docker Build Cloud To get started with Docker Build Cloud, -[create a Docker account](/accounts/create-account/) -and sign up for the starter plan on the -[Docker Build Cloud Dashboard](https://build.docker.com/). +[create a Docker account](/accounts/create-account/). There are two options +to get access to Docker Build Cloud: -If your organization isn't already on a paid Docker subscription, you will -need to provide a payment method to sign up for Docker Build Cloud. If you -select the starter plan, there will be no charges on the provided payment -method, it's only required for verification purposes. +- Users with a free Personal account can opt-in to a 7-day free trial, with the option +to subscribe for access. To start your free trial, sign in to [Docker Build Cloud Dashboard](https://app.docker.com/build/) and follow the on-screen instructions. +- All users with a paid Docker subscription have access to Docker Build Cloud included +with their Docker suite of products. See [Docker subscriptions and features](/manuals/subscription/details.md) for more information. Once you've signed up and created a builder, continue by [setting up the builder in your local environment](./setup.md). -For more information about the available subscription plans, see -[Docker Build Cloud subscriptions and features](/manuals/subscription/build-cloud/build-details.md). For information about roles and permissions related to Docker Build Cloud, see [Roles and Permissions](/manuals/security/for-admins/roles-and-permissions.md#docker-build-cloud). diff --git a/content/manuals/build-cloud/ci.md b/content/manuals/build-cloud/ci.md index f38ebdc40ca..bd66ec53f42 100644 --- a/content/manuals/build-cloud/ci.md +++ b/content/manuals/build-cloud/ci.md @@ -65,18 +65,19 @@ jobs: docker: runs-on: ubuntu-latest steps: - - name: Log in to Docker Hub + - name: Login to Docker Hub uses: docker/login-action@v3 with: username: ${{ vars.DOCKER_USER }} password: ${{ secrets.DOCKER_PAT }} + - name: Set up Docker Buildx uses: docker/setup-buildx-action@v3 with: - version: "lab:latest" driver: cloud endpoint: "/default" install: true + - name: Build and push uses: docker/build-push-action@v6 with: diff --git a/content/manuals/build-cloud/setup.md b/content/manuals/build-cloud/setup.md index 9d8ef75ab08..57c2e366314 100644 --- a/content/manuals/build-cloud/setup.md +++ b/content/manuals/build-cloud/setup.md @@ -16,7 +16,7 @@ environment. To get started with Docker Build Cloud, you need to: - Download and install Docker Desktop version 4.26.0 or later. -- Sign up for a Docker Build Cloud subscription in the [Docker Build Cloud Dashboard](https://build.docker.com/). +- Sign up for a Docker Build Cloud subscription in the [Docker Build Cloud Dashboard](https://app.docker.com/build/). ### Use Docker Build Cloud without Docker Desktop diff --git a/content/manuals/build/_index.md b/content/manuals/build/_index.md index 5fbdec6cfe8..c4af3ceb1af 100644 --- a/content/manuals/build/_index.md +++ b/content/manuals/build/_index.md @@ -1,9 +1,11 @@ --- -title: Overview of Docker Build -linkTitle: Docker Build -weight: 100 +title: Docker Build +weight: 20 description: Get an overview of Docker Build to package and bundle your code and ship it anywhere keywords: build, buildx, buildkit +params: + sidebar: + group: Open source grid: - title: Packaging your software description: 'Build and package your application to run it anywhere: locally or diff --git a/content/manuals/build/bake/contexts.md b/content/manuals/build/bake/contexts.md index 8bace45ad23..276939cefc3 100644 --- a/content/manuals/build/bake/contexts.md +++ b/content/manuals/build/bake/contexts.md @@ -93,14 +93,14 @@ multiple Dockerfiles that can't be easily merged into one. ## Deduplicate context transfer -> **Note** +> [!NOTE] > -> As of Buildx version 0.17.0 and later, Bake automatically deduplicates +> As of Buildx version 0.17.0 and later, Bake automatically de-duplicates > context transfer for targets that share the same context. In addition to > Buildx version 0.17.0, the builder must be running BuildKit version 0.16.0 or > later, and the Dockerfile syntax must be `docker/dockerfile:1.10` or later. > -> If you meet these requirements, you don't need to manually deduplicate +> If you meet these requirements, you don't need to manually de-duplicate > context transfer as described in this section. > > - To check your Buildx version, run `docker buildx version`. diff --git a/content/manuals/build/bake/overrides.md b/content/manuals/build/bake/overrides.md index 2028650f16a..c4fc5bb2a77 100644 --- a/content/manuals/build/bake/overrides.md +++ b/content/manuals/build/bake/overrides.md @@ -288,43 +288,63 @@ which is the short commit hash generated by `git rev-parse --short HEAD`. Overriding non-string variables with environment variables is supported. Values passed as environment variables are coerced into suitable types first. -The following example defines a `PORT` variable with a default value of `8080`. -The `default` target uses a [ternary operator](expressions.md#ternary-operators) -to set the `PORT` variable to the value of the environment variable `PORT` -if it is greater than `1024`, otherwise it uses the default value. - -In this case, the `PORT` variable is coerced to an integer before the ternary -operator is evaluated. +The following example defines a `PORT` variable. The `backend` target uses the +`PORT` variable as-is, and the `frontend` target uses the value of `PORT` +incremented by one. ```hcl -default_port = 8080 - variable "PORT" { - default = default_port + default = 3000 } -target "default" { +group "default" { + targets = ["backend", "frontend"] +} + +target "backend" { args = { - PORT = PORT > 1024 ? PORT : default_port + PORT = PORT + } +} + +target "frontend" { + args = { + PORT = add(PORT, 1) } } ``` -Attempting to set the `PORT` variable with a value less than `1024` will result -in the default value being used. +Overriding `PORT` using an environment variable will first coerce the value +into the expected type, an integer, before the expression in the `frontend` +target runs. ```console -$ PORT=80 docker buildx bake --print +$ PORT=7070 docker buildx bake --print ``` ```json { - "target": { + "group": { "default": { + "targets": [ + "backend", + "frontend" + ] + } + }, + "target": { + "backend": { + "context": ".", + "dockerfile": "Dockerfile", + "args": { + "PORT": "7070" + } + }, + "frontend": { "context": ".", "dockerfile": "Dockerfile", "args": { - "PORT": "8080" + "PORT": "7071" } } } diff --git a/content/manuals/build/bake/remote-definition.md b/content/manuals/build/bake/remote-definition.md index b3caab8f57f..89e454e2453 100644 --- a/content/manuals/build/bake/remote-definition.md +++ b/content/manuals/build/bake/remote-definition.md @@ -173,8 +173,7 @@ remote definition and the local "metadata-only" Bake file, specify both files and use the `cwd://` prefix for the metadata Bake file: ```yml - - - name: Build + - name: Build uses: docker/bake-action@v4 with: source: "${{ github.server_url }}/${{ github.repository }}.git#${{ github.ref }}" diff --git a/content/manuals/build/bake/variables.md b/content/manuals/build/bake/variables.md index b584cc1483a..0db49d53718 100644 --- a/content/manuals/build/bake/variables.md +++ b/content/manuals/build/bake/variables.md @@ -78,6 +78,94 @@ $ docker buildx bake --print } ``` +## Validating variables + +To verify that the value of a variable conforms to an expected type, value +range, or other condition, you can define custom validation rules using the +`validation` block. + +In the following example, validation is used to enforce a numeric constraint on +a variable value; the `PORT` variable must be 1024 or higher. + +```hcl +# Define a variable `PORT` with a default value and a validation rule +variable "PORT" { + default = 3000 # Default value assigned to `PORT` + + # Validation block to ensure `PORT` is a valid number within the acceptable range + validation { + condition = PORT >= 1024 # Ensure `PORT` is at least 1024 + error_message = "The variable 'PORT' must be 1024 or higher." # Error message for invalid values + } +} +``` + +If the `condition` expression evaluates to `false`, the variable value is +considered invalid, whereby the build invocation fails and `error_message` is +emitted. For example, if `PORT=443`, the condition evaluates to `false`, and +the error is raised. + +Values are coerced into the expected type before the validation is set. This +ensures that any overrides set with environment variables work as expected. + +### Validate multiple conditions + +To evaluate more than one condition, define multiple `validation` blocks for +the variable. All conditions must be `true`. + +Here’s an example: + +```hcl +# Define a variable `VAR` with multiple validation rules +variable "VAR" { + # First validation block: Ensure the variable is not empty + validation { + condition = VAR != "" + error_message = "The variable 'VAR' must not be empty." + } + + # Second validation block: Ensure the value contains only alphanumeric characters + validation { + # VAR and the regex match must be identical: + condition = VAR == regex("[a-zA-Z0-9]+", VAR) + error_message = "The variable 'VAR' can only contain letters and numbers." + } +} +``` + +This example enforces: + +- The variable must not be empty. +- The variable must match a specific character set. + +For invalid inputs like `VAR="hello@world"`, the validation would fail. + +### Validating variable dependencies + +You can reference other Bake variables in your condition expression, enabling +validations that enforce dependencies between variables. This ensures that +dependent variables are set correctly before proceeding. + +Here’s an example: + +```hcl +# Define a variable `FOO` +variable "FOO" {} + +# Define a variable `BAR` with a validation rule that references `FOO` +variable "BAR" { + # Validation block to ensure `FOO` is set if `BAR` is used + validation { + condition = FOO != "" # Check if `FOO` is not an empty string + error_message = "The variable 'BAR' requires 'FOO' to be set." + } +} +``` + +This configuration ensures that the `BAR` variable can only be used if `FOO` +has been assigned a non-empty value. Attempting to build without setting `FOO` +will trigger the validation error. + ## Escape variable interpolation If you want to bypass variable interpolation when parsing the Bake definition, diff --git a/content/manuals/build/builders/_index.md b/content/manuals/build/builders/_index.md index e1a9334eabe..c926822df0e 100644 --- a/content/manuals/build/builders/_index.md +++ b/content/manuals/build/builders/_index.md @@ -65,6 +65,48 @@ To switch between builders, use the `docker buildx use ` command. After running this command, the builder you specify is automatically selected when you invoke builds. +### Difference between `docker build` and `docker buildx build` + +Even though `docker build` is an alias for `docker buildx build`, there are +subtle differences between the two commands. With Buildx, the build client and +the and daemon (BuildKit) are decoupled. This means you can use multiple +builders from a single client, even remote ones. + +The `docker build` command always defaults to using the default builder that +comes bundled with the Docker Engine, for ensuring backwards compatibility with +older versions of the Docker CLI. The `docker buildx build` command, on the +other hand, checks whether you've set a different builder as the default +builder before it sends your build to BuildKit. + +To use the `docker build` command with a non-default builder, you must either: + +- Specify the builder explicitly, using the `--builder` flag or the `BUILDX_BUILDER` environment variable: + + ```console + $ BUILDX_BUILDER=my_builder docker build . + $ docker build --builder my_builder . + ``` + +- Configure Buildx as the default client by running the following command: + + ```console + $ docker buildx install + ``` + + This updates your [Docker CLI configuration file](/reference/cli/docker/_index.md#configuration-files) + to ensure all of your build-related commands are routed via Buildx. + + > [!TIP] + > To undo this change, run `docker buildx uninstall`. + + + +In general, we recommend that you use the `docker buildx build` command when +you want to use custom builders. This ensures that your [selected +builder](#selected-builder) configuration is interpreted correctly. + + + ## Additional information - For information about how to interact with and manage builders, diff --git a/content/manuals/build/builders/drivers/kubernetes.md b/content/manuals/build/builders/drivers/kubernetes.md index 12da0a79ce4..f15f83f9ebe 100644 --- a/content/manuals/build/builders/drivers/kubernetes.md +++ b/content/manuals/build/builders/drivers/kubernetes.md @@ -43,7 +43,7 @@ can pass to `--driver-opt`: | `limits.memory` | Memory size | | Sets the limit memory value specified in bytes or with a valid suffix. For example `requests.memory=500Mi` or `requests.memory=4G` | | `limits.ephemeral-storage` | Storage size | | Sets the limit ephemeral-storage value specified in bytes or with a valid suffix. For example `requests.ephemeral-storage=100M` | | `nodeselector` | CSV string | | Sets the pod's `nodeSelector` label(s). See [node assignment][2]. | -| `annotation` | CSV string | | Sets additional annotations on the deployments and pods. | +| `annotations` | CSV string | | Sets additional annotations on the deployments and pods. | | `labels` | CSV string | | Sets additional labels on the deployments and pods. | | `tolerations` | CSV string | | Configures the pod's taint toleration. See [node assignment][2]. | | `serviceaccount` | String | | Sets the pod's `serviceAccountName`. | diff --git a/content/manuals/build/builders/manage.md b/content/manuals/build/builders/manage.md index 306ed098df4..5039fa18e5e 100644 --- a/content/manuals/build/builders/manage.md +++ b/content/manuals/build/builders/manage.md @@ -123,4 +123,4 @@ It only removes your connection to the builder. If you have turned on the [Docker Desktop Builds view](/manuals/desktop/use-desktop/builds.md), -you can inspect builders in [Docker Desktop settings](/manuals/desktop/settings.md#builders). +you can inspect builders in [Docker Desktop settings](/manuals/desktop/settings-and-maintenance/settings.md#builders). diff --git a/content/manuals/build/building/base-images.md b/content/manuals/build/building/base-images.md index 96174bd03d1..32ae78d8c46 100644 --- a/content/manuals/build/building/base-images.md +++ b/content/manuals/build/building/base-images.md @@ -20,10 +20,12 @@ FROM debian For most cases, you don't need to create your own base image. Docker Hub contains a vast library of Docker images that are suitable for use as a base -image in your build. [Docker Official Images](../../trusted-content/official-images/_index.md) +image in your build. [Docker Official +Images](../../docker-hub/image-library/trusted-content.md#docker-official-images) are specifically designed as a set of hardened, battle-tested images that support a wide variety of platforms, languages, and frameworks. There are also -[Docker Verified Publisher](https://hub.docker.com/search?q=&image_filter=store) +[Docker Verified +Publisher](../../docker-hub/image-library/trusted-content.md#verified-publisher-images) images, created by trusted publishing partners, verified by Docker. ## Create a base image @@ -123,4 +125,4 @@ For more information about building images and writing Dockerfiles, see: * [Dockerfile reference](/reference/dockerfile.md) * [Dockerfile best practices](/manuals/build/building/best-practices.md) -* [Docker Official Images](../../trusted-content/official-images/_index.md) +* [Docker Official Images](../../docker-hub/image-library/trusted-content.md#docker-official-images) diff --git a/content/manuals/build/building/best-practices.md b/content/manuals/build/building/best-practices.md index c3d7e783a50..343c42b62c5 100644 --- a/content/manuals/build/building/best-practices.md +++ b/content/manuals/build/building/best-practices.md @@ -57,7 +57,7 @@ it small. - [Docker-Sponsored Open Source](https://hub.docker.com/search?image_filter=open_source) are published and maintained by open source projects sponsored by Docker - through an [open source program](../../trusted-content/dsos-program). + through an [open source program](../../docker-hub/image-library/trusted-content.md#docker-sponsored-open-source-software-images). When you pick your base image, look out for the badges indicating that the image is part of these programs. @@ -98,7 +98,7 @@ download of base images and dependencies. ```dockerfile # syntax=docker/dockerfile:1 FROM ubuntu:24.04 -RUN apt-get -y update && apt-get install -y python +RUN apt-get -y update && apt-get install -y --no-install-recommends python3 ``` Also consider [pinning base image versions](#pin-base-image-versions). @@ -145,7 +145,7 @@ database, and an in-memory cache in a decoupled manner. Limiting each container to one process is a good rule of thumb, but it's not a hard and fast rule. For example, not only can containers be -[spawned with an init process](/manuals/engine/containers/run.md#specify-an-init-process), +[spawned with an init process](/manuals/engine/containers/multi-service_container.md), some programs might spawn additional processes of their own accord. For instance, [Celery](https://docs.celeryproject.org/) can spawn multiple worker processes, and [Apache](https://httpd.apache.org/) can create one process per @@ -165,7 +165,7 @@ review. Adding a space before a backslash (`\`) helps as well. Here’s an example from the [buildpack-deps image](https://github.com/docker-library/buildpack-deps): ```dockerfile -RUN apt-get update && apt-get install -y \ +RUN apt-get update && apt-get install -y --no-install-recommends \ bzr \ cvs \ git \ @@ -319,10 +319,10 @@ backslashes to make your Dockerfile more readable, understandable, and maintainable. For example, you can chain commands with the `&&` operator, and use -use escape characters to break long commands into multiple lines. +escape characters to break long commands into multiple lines. ```dockerfile -RUN apt-get update && apt-get install -y \ +RUN apt-get update && apt-get install -y --no-install-recommends \ package-bar \ package-baz \ package-foo @@ -337,7 +337,7 @@ with a pipeline operator: ```dockerfile RUN < \ --platform linux/amd64,linux/arm64 \ - --output ./bin + --output ./bin . ``` This command builds the image using the cloud builder and exports the diff --git a/content/manuals/build/building/variables.md b/content/manuals/build/building/variables.md index 93a23ba2116..d3f4093f6c0 100644 --- a/content/manuals/build/building/variables.md +++ b/content/manuals/build/building/variables.md @@ -304,24 +304,26 @@ Note that these variables aren't used to configure the build container; they aren't available inside the build and they have no relation to the `ENV` instruction. They're used to configure the Buildx client, or the BuildKit daemon. -| Variable | Type | Description | -| --------------------------------------------------------------------------- | ----------------- | ---------------------------------------------------- | -| [BUILDKIT_COLORS](#buildkit_colors) | String | Configure text color for the terminal output. | -| [BUILDKIT_HOST](#buildkit_host) | String | Specify host to use for remote builders. | -| [BUILDKIT_PROGRESS](#buildkit_progress) | String | Configure type of progress output. | -| [BUILDKIT_TTY_LOG_LINES](#buildkit_tty_log_lines) | String | Number of log lines (for active steps in TTY mode). | -| [BUILDX_BAKE_GIT_AUTH_HEADER](#buildx_bake_git_auth_header) | String | HTTP authentication scheme for remote Bake files. | -| [BUILDX_BAKE_GIT_AUTH_TOKEN](#buildx_bake_git_auth_token) | String | HTTP authentication token for remote Bake files. | -| [BUILDX_BAKE_GIT_SSH](#buildx_bake_git_ssh) | String | SSH authentication for remote Bake files. | -| [BUILDX_BUILDER](#buildx_builder) | String | Specify the builder instance to use. | -| [BUILDX_CONFIG](#buildx_config) | String | Specify location for configuration, state, and logs. | -| [BUILDX_EXPERIMENTAL](#buildx_experimental) | Boolean | Turn on experimental features. | -| [BUILDX_GIT_CHECK_DIRTY](#buildx_git_check_dirty) | Boolean | Enable dirty Git checkout detection. | -| [BUILDX_GIT_INFO](#buildx_git_info) | Boolean | Remove Git information in provenance attestations. | -| [BUILDX_GIT_LABELS](#buildx_git_labels) | String \| Boolean | Add Git provenance labels to images. | -| [BUILDX_NO_DEFAULT_ATTESTATIONS](#buildx_no_default_attestations) | Boolean | Turn off default provenance attestations. | -| [BUILDX_NO_DEFAULT_LOAD](#buildx_no_default_load) | Boolean | Turn off loading images to image store by default. | -| [EXPERIMENTAL_BUILDKIT_SOURCE_POLICY](#experimental_buildkit_source_policy) | String | Specify a BuildKit source policy file. | +| Variable | Type | Description | +| --------------------------------------------------------------------------- | ----------------- | ------------------------------------------------------------ | +| [BUILDKIT_COLORS](#buildkit_colors) | String | Configure text color for the terminal output. | +| [BUILDKIT_HOST](#buildkit_host) | String | Specify host to use for remote builders. | +| [BUILDKIT_PROGRESS](#buildkit_progress) | String | Configure type of progress output. | +| [BUILDKIT_TTY_LOG_LINES](#buildkit_tty_log_lines) | String | Number of log lines (for active steps in TTY mode). | +| [BUILDX_BAKE_GIT_AUTH_HEADER](#buildx_bake_git_auth_header) | String | HTTP authentication scheme for remote Bake files. | +| [BUILDX_BAKE_GIT_AUTH_TOKEN](#buildx_bake_git_auth_token) | String | HTTP authentication token for remote Bake files. | +| [BUILDX_BAKE_GIT_SSH](#buildx_bake_git_ssh) | String | SSH authentication for remote Bake files. | +| [BUILDX_BUILDER](#buildx_builder) | String | Specify the builder instance to use. | +| [BUILDX_CONFIG](#buildx_config) | String | Specify location for configuration, state, and logs. | +| [BUILDX_CPU_PROFILE](#buildx_cpu_profile) | String | Generate a `pprof` CPU profile at the specified location. | +| [BUILDX_EXPERIMENTAL](#buildx_experimental) | Boolean | Turn on experimental features. | +| [BUILDX_GIT_CHECK_DIRTY](#buildx_git_check_dirty) | Boolean | Enable dirty Git checkout detection. | +| [BUILDX_GIT_INFO](#buildx_git_info) | Boolean | Remove Git information in provenance attestations. | +| [BUILDX_GIT_LABELS](#buildx_git_labels) | String \| Boolean | Add Git provenance labels to images. | +| [BUILDX_MEM_PROFILE](#buildx_mem_profile) | String | Generate a `pprof` memory profile at the specified location. | +| [BUILDX_NO_DEFAULT_ATTESTATIONS](#buildx_no_default_attestations) | Boolean | Turn off default provenance attestations. | +| [BUILDX_NO_DEFAULT_LOAD](#buildx_no_default_load) | Boolean | Turn off loading images to image store by default. | +| [EXPERIMENTAL_BUILDKIT_SOURCE_POLICY](#experimental_buildkit_source_policy) | String | Specify a BuildKit source policy file. | BuildKit also supports a few additional configuration parameters. Refer to [BuildKit built-in build args](/reference/dockerfile.md#buildkit-built-in-build-args). @@ -507,6 +509,22 @@ Usage: $ export BUILDX_CONFIG=/usr/local/etc ``` +### BUILDX_CPU_PROFILE + +{{< introduced buildx 0.18.0 >}} + +If specified, Buildx generates a `pprof` CPU profile at the specified location. + +> [!NOTE] +> This property is only useful for when developing Buildx. The profiling data +> is not relevant for analyzing a build's performance. + +Usage: + +```console +$ export BUILDX_CPU_PROFILE=buildx_cpu.prof +``` + ### BUILDX_EXPERIMENTAL Enables experimental build features. @@ -572,6 +590,23 @@ Usage: If the repository is in a dirty state, the `revision` gets a `-dirty` suffix. +### BUILDX_MEM_PROFILE + +{{< introduced buildx 0.18.0 >}} + +If specified, Buildx generates a `pprof` memory profile at the specified +location. + +> [!NOTE] +> This property is only useful for when developing Buildx. The profiling data +> is not relevant for analyzing a build's performance. + +Usage: + +```console +$ export BUILDX_MEM_PROFILE=buildx_mem.prof +``` + ### BUILDX_NO_DEFAULT_ATTESTATIONS {{< introduced buildx 0.10.4 "../release-notes.md#0104" >}} diff --git a/content/manuals/build/buildkit/dockerfile-release-notes.md b/content/manuals/build/buildkit/dockerfile-release-notes.md index b0f63ac5c17..e05d4751de9 100644 --- a/content/manuals/build/buildkit/dockerfile-release-notes.md +++ b/content/manuals/build/buildkit/dockerfile-release-notes.md @@ -13,6 +13,68 @@ issues, and bug fixes in [Dockerfile reference](/reference/dockerfile.md). For usage, see the [Dockerfile frontend syntax](frontend.md) page. +## 1.12.0 + +{{< release-date date="2024-11-27" >}} + +The full release note for this release is available +[on GitHub](https://github.com/moby/buildkit/releases/tag/dockerfile%2F1.12.0). + +```dockerfile +# syntax=docker/dockerfile:1.12.0 +``` + +- Fix incorrect description in History line of image configuration with multiple `ARG` instructions. [moby/buildkit#5508] + +[moby/buildkit#5508]: https://github.com/moby/buildkit/pull/5508 + +## 1.11.1 + +{{< release-date date="2024-11-08" >}} + +The full release note for this release is available +[on GitHub](https://github.com/moby/buildkit/releases/tag/dockerfile%2F1.11.1). + +```dockerfile +# syntax=docker/dockerfile:1.11.1 +``` + +- Fix regression when using the `ONBUILD` instruction in stages inherited within the same Dockerfile. [moby/buildkit#5490] + +[moby/buildkit#5490]: https://github.com/moby/buildkit/pull/5490 + +## 1.11.0 + +{{< release-date date="2024-10-30" >}} + +The full release note for this release is available +[on GitHub](https://github.com/moby/buildkit/releases/tag/dockerfile%2F1.11.0). + +```dockerfile +# syntax=docker/dockerfile:1.11.0 +``` + +- The [`ONBUILD` instruction](/reference/dockerfile.md#onbuild) now supports commands that refer to other stages or images with `from`, such as `COPY --from` or `RUN mount=from=...`. [moby/buildkit#5357] +- The [`SecretsUsedInArgOrEnv`](/reference/build-checks/secrets-used-in-arg-or-env.md) build check has been improved to reduce false positives. [moby/buildkit#5208] +- A new [`InvalidDefinitionDescription`](/reference/build-checks/invalid-definition-description.md) build check recommends formatting comments for build arguments and stages descriptions. This is an [experimental check](/manuals/build/checks.md#experimental-checks). [moby/buildkit#5208], [moby/buildkit#5414] +- Multiple fixes for the `ONBUILD` instruction's progress and error handling. [moby/buildkit#5397] +- Improved error reporting for missing flag errors. [moby/buildkit#5369] +- Enhanced progress output for secret values mounted as environment variables. [moby/buildkit#5336] +- Added built-in build argument `TARGETSTAGE` to expose the name of the (final) target stage for the current build. [moby/buildkit#5431] + +### 1.11.0-labs + +- `COPY --chmod` now supports non-octal values. [moby/buildkit#5380] + +[moby/buildkit#5357]: https://github.com/moby/buildkit/pull/5357 +[moby/buildkit#5208]: https://github.com/moby/buildkit/pull/5208 +[moby/buildkit#5414]: https://github.com/moby/buildkit/pull/5414 +[moby/buildkit#5397]: https://github.com/moby/buildkit/pull/5397 +[moby/buildkit#5369]: https://github.com/moby/buildkit/pull/5369 +[moby/buildkit#5336]: https://github.com/moby/buildkit/pull/5336 +[moby/buildkit#5431]: https://github.com/moby/buildkit/pull/5431 +[moby/buildkit#5380]: https://github.com/moby/buildkit/pull/5380 + ## 1.10.0 {{< release-date date="2024-09-10" >}} diff --git a/content/manuals/build/cache/backends/_index.md b/content/manuals/build/cache/backends/_index.md index 4a9aea4e619..6dd4a8a9dee 100644 --- a/content/manuals/build/cache/backends/_index.md +++ b/content/manuals/build/cache/backends/_index.md @@ -18,7 +18,7 @@ environments usually have little-to-no persistence between runs, but it's still important to keep the runtime of image builds as low as possible. The default `docker` driver supports the `inline`, `local`, `registry`, and -`gha` cache backends, but only if you have enabled the [containerd image store](/manuals/desktop/containerd.md). +`gha` cache backends, but only if you have enabled the [containerd image store](/manuals/desktop/features/containerd.md). Other cache backends require you to select a different [driver](/manuals/build/builders/drivers/_index.md). > [!WARNING] diff --git a/content/manuals/build/cache/garbage-collection.md b/content/manuals/build/cache/garbage-collection.md index e371473a5ec..9e35068d24c 100644 --- a/content/manuals/build/cache/garbage-collection.md +++ b/content/manuals/build/cache/garbage-collection.md @@ -8,32 +8,155 @@ aliases: While [`docker builder prune`](/reference/cli/docker/builder/prune.md) or [`docker buildx prune`](/reference/cli/docker/buildx/prune.md) -commands run at once, garbage collection runs periodically and follows an -ordered list of prune policies. +commands run at once, Garbage Collection (GC) runs periodically and follows an +ordered list of prune policies. The BuildKit daemon clears the build cache when +the cache size becomes too big, or when the cache age expires. -Garbage collection runs in the BuildKit daemon. The daemon clears the build -cache when the cache size becomes too big, or when the cache age expires. The -following sections describe how you can configure both the size and age -parameters by defining garbage collection policies. +For most users, the default GC behavior is sufficient and doesn't require any +intervention. Advanced users, particularly those working with large-scale +builds, self-managed builders, or constrained storage environments, might +benefit from customizing these settings to better align with their workflow +needs. The following sections explain how GC works and provide guidance on +tailoring its behavior through custom configuration. + +## Garbage collection policies + +GC policies define a set of rules that determine how the build cache is managed +and cleaned up. These policies include criteria for when to remove cache +entries, such as the age of the cache, the amount of space being used, and the +type of cache records to prune. + +Each GC policy is evaluated in sequence, starting with the most specific +criteria, and proceeds to broader rules if previous policies do not free up +enough cache. This lets BuildKit prioritize cache entries, preserving the most +valuable cache while ensuring the system maintains performance and +availability. + +For example, say you have the following GC policies: + +1. Find "stale" cache records that haven't been used in the past 48 hours, and + delete records until there's maximum 5GB of "stale" cache left. +2. If the build cache size exceeds 10GB, delete records until the total cache + size is no more than 10GB. + +The first rule is more specific, prioritizing stale cache records and setting a +lower limit for a less valuable type of cache. The second rule imposes a higher +hard limit that applies to any type of cache records. With these policies, if +you have 11GB worth of build cache, where: + +- 7GB of which is "stale" cache +- 4GB is other, more valuable cache + +A GC sweep would delete 5GB of stale cache as part of the 1st policy, with a +remainder of 6GB, meaning the 2nd policy does not need to clear any more cache. + +The default GC policies are (approximately): + +1. Remove cache that can be easily regenerated, such as build contexts from + local directories or remote Git repositories, and cache mounts, if hasn't + been used for more than 48 hours. +2. Remove cache that hasn't been used in a build for more than 60 days. +3. Remove unshared cache that exceeds the build cache size limit. Unshared + cache records refers to layer blobs that are not used by other resources + (typically, as image layers). +4. Remove any build cache that exceeds the build cache size limit. + +The precise algorithm and the means of configuring the policies differ slightly +depending on what kind of builder you're using. Refer to +[Configuration](#configuration) for more details. ## Configuration -Depending on the [driver](../builders/drivers/_index.md) used by your builder instance, -the garbage collection will use a different configuration file. +> [!NOTE] +> If you're satisfied with the default garbage collection behavior and don't +> need to fine-tune its settings, you can skip this section. Default +> configurations work well for most use cases and require no additional setup. + +Depending on the type of [build driver](../builders/drivers/_index.md) you use, +you will use different configuration files to change the builder's GC settings: -If you're using the [`docker` driver](../builders/drivers/docker.md), garbage collection -can be configured in the [Docker Daemon configuration](/reference/cli/dockerd.md#daemon-configuration-file). -file: +- If you use the default builder for Docker Engine (the `docker` driver), use + the [Docker daemon configuration file](#docker-daemon-configuration-file). +- If you use a custom builder, use a [BuildKit configuration file](#buildkit-configuration-file). + +### Docker daemon configuration file + +If you're using the default [`docker` driver](../builders/drivers/docker.md), +GC is configured in the [`daemon.json` configuration file](/reference/cli/dockerd.md#daemon-configuration-file), +or if you use Docker Desktop, in [**Settings > Docker Engine**](/manuals/desktop/settings-and-maintenance/settings.md). + +The following snippet shows the default builder configuration for the `docker` +driver for Docker Desktop users: + +```json +{ + "builder": { + "gc": { + "defaultKeepStorage": "20GB", + "enabled": true + } + } +} +``` + +The `defaultKeepStorage` option configures the size limit of the build cache, +which influences the GC policies. The default policies for the `docker` driver +work as follows: + +1. Remove ephemeral, unused build cache older than 48 hours if it exceeds 13.8% + of `defaultKeepStorage`, or at minimum 512MB. +2. Remove unused build cache older than 60 days. +3. Remove unshared build cache that exceeds the `defaultKeepStorage` limit. +4. Remove any build cache that exceeds the `defaultKeepStorage` limit. + +Given the Docker Desktop default value for `defaultKeepStorage` of 20GB, the +default GC policies resolve to: ```json { "builder": { "gc": { "enabled": true, - "defaultKeepStorage": "10GB", "policy": [ - { "keepStorage": "10GB", "filter": ["unused-for=2200h"] }, - { "keepStorage": "50GB", "filter": ["unused-for=3300h"] }, + { + "keepStorage": "2.764GB", + "filter": [ + "unused-for=48h", + "type==source.local,type==exec.cachemount,type==source.git.checkout" + ] + }, + { "keepStorage": "20GB", "filter": ["unused-for=1440h"] }, + { "keepStorage": "20GB" }, + { "keepStorage": "20GB", "all": true } + ] + } + } +} +``` + +The easiest way to tweak the build cache configuration for the `docker` driver +is to adjust the `defaultKeepStorage` option: + +- Increase the limit if you feel like you think the GC is too aggressive. +- Decrease the limit if you need to preserve space. + +If you need even more control, you can define your own GC policies directly. +The following example defines a more conservative GC configuration with the +following policies: + +1. Remove unused cache entries older than 1440 hours, or 60 days, if build cache exceeds 50GB. +2. Remove unshared cache entries if build cache exceeds 50GB. +3. Remove any cache entries if build cache exceeds 100GB. + +```json +{ + "builder": { + "gc": { + "enabled": true, + "defaultKeepStorage": "50GB", + "policy": [ + { "keepStorage": "0", "filter": ["unused-for=1440h"] }, + { "keepStorage": "0" }, { "keepStorage": "100GB", "all": true } ] } @@ -41,52 +164,127 @@ file: } ``` -For other drivers, garbage collection can be configured using the -[BuildKit configuration](../buildkit/toml-configuration.md) file: +Policies 1 and 2 here set `keepStorage` to `0`, which means they'll fall back +to the default limit of 50GB as defined by `defaultKeepStorage`. + +### BuildKit configuration file + +For build drivers other than `docker`, GC is configured using a +[`buildkitd.toml`](../buildkit/toml-configuration.md) configuration file. This +file uses the following high-level configuration options that you can use to +tweak the thresholds for how much disk space BuildKit should use for cache: + +| Option | Description | Default value | +| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | +| `reservedSpace` | The minimum amount of disk space BuildKit is allowed to allocate for cache. Usage below this threshold will not be reclaimed during garbage collection. | 10% of total disk space or 10GB (whichever is lower) | +| `maxUsedSpace` | The maximum amount of disk space that BuildKit is allowed to use. Usage above this threshold will be reclaimed during garbage collection. | 60% of total disk space or 100GB (whichever is lower) | +| `minFreeSpace` | The amount of disk space that must be kept free. | 20GB | + +You can set these options either as number of bytes, a unit string (for +example, `512MB`), or as a percentage of the total disk size. Changing these +options influences the default GC policies used by the BuildKit worker. With +the default thresholds, the GC policies resolve as follows: ```toml +# Global defaults [worker.oci] gc = true - gckeepstorage = 10000 - [[worker.oci.gcpolicy]] - keepBytes = 512000000 - keepDuration = 172800 - filters = [ "type==source.local", "type==exec.cachemount", "type==source.git.checkout"] - [[worker.oci.gcpolicy]] - all = true - keepBytes = 1024000000 + reservedSpace = "10GB" + maxUsedSpace = "100GB" + minFreeSpace = "20%" + +# Policy 1 +[[worker.oci.gcpolicy]] + filters = [ "type==source.local", "type==exec.cachemount", "type==source.git.checkout" ] + keepDuration = "48h" + maxUsedSpace = "512MB" + +# Policy 2 +[[worker.oci.gcpolicy]] + keepDuration = "1440h" # 60 days + reservedSpace = "10GB" + maxUsedSpace = "100GB" + +# Policy 3 +[[worker.oci.gcpolicy]] + reservedSpace = "10GB" + maxUsedSpace = "100GB" + +# Policy 4 +[[worker.oci.gcpolicy]] + all = true + reservedSpace = "10GB" + maxUsedSpace = "100GB" ``` -## Default policies - -Default garbage collection policies apply to all builders if not set: - -```text -GC Policy rule#0: - All: false - Filters: type==source.local,type==exec.cachemount,type==source.git.checkout - Keep Duration: 48h0m0s - Keep Bytes: 512MB -GC Policy rule#1: - All: false - Keep Duration: 1440h0m0s - Keep Bytes: 26GB -GC Policy rule#2: - All: false - Keep Bytes: 26GB -GC Policy rule#3: - All: true - Keep Bytes: 26GB +In practical terms, this means: + +- Policy 1: If the build cache exceeds 512MB, BuildKit removes cache records + for local build contexts, remote Git contexts, and cache mounts that haven’t + been used in the last 48 hours. +- Policy 2: If disk usage exceeds 100GB, unshared build cache older than 60 + days is removed, ensuring at least 10GB of disk space is reserved for cache. +- Policy 3: If disk usage exceeds 100GB, any unshared cache is removed, + ensuring at least 10GB of disk space is reserved for cache. +- Policy 4: If disk usage exceeds 100GB, all cache—including shared and + internal records—is removed, ensuring at least 10GB of disk space is reserved + for cache. + +`reservedSpace` has the highest priority in defining the lower limit for build +cache size. If `maxUsedSpace` or `minFreeSpace` would define a lower value, the +minimum cache size would never be brought below `reservedSpace`. + +If both `reservedSpace` and `maxUsedSpace` are set, a GC sweep results in a +cache size between those thresholds. For example, if `reservedSpace` is set to +10GB, and `maxUsedSpace` is set to 20GB, the resulting amount of cache after a +GC run is less than 20GB, but at least 10GB. + +You can also define completely custom GC policies. Custom policies also let you +define filters, which lets you pinpoint the types of cache entries that a given +policy is allowed to prune. + +#### Custom GC policies in BuildKit + +Custom GC policies let you fine-tune how BuildKit manages its cache, and gives +you full control over cache retention based on criteria such as cache type, +duration, or disk space thresholds. If you need full control over the cache +thresholds and how cache records should be prioritized, defining custom GC +policies is the way to go. + +To define a custom GC policy, use the `[[worker.oci.gcpolicy]]` configuration +block in `buildkitd.toml`. Each policy define the thresholds that will be used +for that policy. The global values for `reservedSpace`, `maxUsedSpace`, and +`minFreeSpace` do not apply if you use custom policies. + +Here’s an example configuration: + +```toml +# Custom GC Policy 1: Remove unused local contexts older than 24 hours +[[worker.oci.gcpolicy]] + filters = ["type==source.local"] + keepDuration = "24h" + reservedSpace = "5GB" + maxUsedSpace = "50GB" + +# Custom GC Policy 2: Remove remote Git contexts older than 30 days +[[worker.oci.gcpolicy]] + filters = ["type==source.git.checkout"] + keepDuration = "720h" + reservedSpace = "5GB" + maxUsedSpace = "30GB" + +# Custom GC Policy 3: Aggressively clean all cache if disk usage exceeds 90GB +[[worker.oci.gcpolicy]] + all = true + reservedSpace = "5GB" + maxUsedSpace = "90GB" ``` -- `rule#0`: if build cache uses more than 512MB delete the most easily - reproducible data after it has not been used for 2 days. -- `rule#1`: remove any data not used for 60 days. -- `rule#2`: keep the unshared build cache under cap. -- `rule#3`: if previous policies were insufficient start deleting internal data - to keep build cache under cap. +In addition to the `reservedSpace`, `maxUsedSpace`, and `minFreeSpace` threshold, +when defining a GC policy you have two additional configuration options: -> [!NOTE] -> -> `Keep Bytes` defaults to 10% of the size of the disk. If the disk size cannot -> be determined, it uses 2GB as a fallback. +- `all`: By default, BuildKit will exclude some cache records from being pruned + during GC. Setting this option to `true` will allow any cache records to be + pruned. +- `filters`: Filters let you specify specific types of cache records that a GC + policy is allowed to prune. diff --git a/content/manuals/build/cache/optimize.md b/content/manuals/build/cache/optimize.md index d0551b6f35b..3e0dfed9f78 100644 --- a/content/manuals/build/cache/optimize.md +++ b/content/manuals/build/cache/optimize.md @@ -19,7 +19,7 @@ the build process: invalidation. - [Keep the context small](#keep-the-context-small): The context is the set of files and directories that are sent to the builder to process a build - instruction. Keeping the context as small reduces the amount of data that + instruction. Keeping the context as small as possible reduces the amount of data that needs to be sent to the builder, and reduces the likelihood of cache invalidation. - [Use bind mounts](#use-bind-mounts): Bind mounts let you mount a file or @@ -323,15 +323,15 @@ jobs: docker: runs-on: ubuntu-latest steps: - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@v3 - - name: Login to Docker Hub uses: docker/login-action@v3 with: username: ${{ vars.DOCKERHUB_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} - + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + - name: Build and push uses: docker/build-push-action@v6 with: diff --git a/content/manuals/build/checks.md b/content/manuals/build/checks.md index 201b9ce956f..84df51a0b4c 100644 --- a/content/manuals/build/checks.md +++ b/content/manuals/build/checks.md @@ -278,3 +278,10 @@ experimental checks, the experimental checks will still run: # syntax=docker/dockerfile:1 # check=skip=all;experimental=all ``` + +## Further reading + +For more information about using build checks, see: + +- [Build checks reference](/reference/build-checks/) +- [Validating build configuration with GitHub Actions](/manuals/build/ci/github-actions/checks.md) diff --git a/content/manuals/build/ci/github-actions/_index.md b/content/manuals/build/ci/github-actions/_index.md index d51d9285f72..444bc3bc3f7 100644 --- a/content/manuals/build/ci/github-actions/_index.md +++ b/content/manuals/build/ci/github-actions/_index.md @@ -1,5 +1,5 @@ --- -title: Introduction to GitHub Actions +title: Docker Build GitHub Actions linkTitle: GitHub Actions description: Docker maintains a set of official GitHub Actions for building Docker images. keywords: ci, github actions, gha, build, introduction, tutorial @@ -43,174 +43,6 @@ refer to the following sections: ## Get started with GitHub Actions -{{< include "gha-tutorial.md" >}} -This tutorial walks you through the process of setting up and using Docker GitHub -Actions for building Docker images, and pushing images to Docker Hub. You will -complete the following steps: - -1. Create a new repository on GitHub. -2. Define the GitHub Actions workflow. -3. Run the workflow. - -To follow this tutorial, you need a Docker ID and a GitHub account. - -### Step one: Create the repository - -Create a GitHub repository and configure the Docker Hub credentials. - -1. Create a new GitHub repository using - [this template repository](https://github.com/dvdksn/clockbox/generate). - - The repository contains a simple Dockerfile, and nothing else. Feel free to - use another repository containing a working Dockerfile if you prefer. - -2. Open the repository **Settings**, and go to **Secrets and variables** > **Actions**. - -3. Create a new **Repository variable** named `DOCKERHUB_USERNAME` and your Docker ID as value. - -4. Create a new - [personal access token](/security/for-developers/access-tokens/#create-an-access-token) - for Docker Hub. You can name this token `clockboxci`. - -5. Add the Docker Hub access token as a **Repository secret** in your GitHub repository, with the name - `DOCKERHUB_TOKEN`. - -With your repository created, and credentials configured, you're now ready for -action. - -### Step two: Set up the workflow - -Set up your GitHub Actions workflow for building and pushing the image to Docker -Hub. - -1. Go to your repository on GitHub and then select the **Actions** tab. -2. Select **set up a workflow yourself**. - - This takes you to a page for creating a new GitHub actions workflow file in - your repository, under `.github/workflows/main.yml` by default. - -3. In the editor window, copy and paste the following YAML configuration. - - ```yaml - name: ci - - on: - push: - branches: - - "main" - - jobs: - build: - runs-on: ubuntu-latest - ``` - - - `name`: the name of this workflow. - - `on.push.branches`: specifies that this workflow should run on every push - event for the branches in the list. - - `jobs`: creates a job ID (`build`) and declares the type of machine that - the job should run on. - -For more information about the YAML syntax used here, see -[Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions). - -### Step three: Define the workflow steps - -Now the essentials: what steps to run, and in what order to run them. - -```yaml -jobs: - build: - runs-on: ubuntu-latest - steps: - - - name: Login to Docker Hub - uses: docker/login-action@v3 - with: - username: ${{ vars.DOCKERHUB_USERNAME }} - password: ${{ secrets.DOCKERHUB_TOKEN }} - - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@v3 - - - name: Build and push - uses: docker/build-push-action@v6 - with: - push: true - tags: ${{ vars.DOCKERHUB_USERNAME }}/clockbox:latest -``` - -The previous YAML snippet contains a sequence of steps that: - -1. Signs in to Docker Hub, using the - [Docker Login](https://github.com/marketplace/actions/docker-login) action and your Docker Hub credentials. -2. Creates a BuildKit builder instance using the - [Docker Setup Buildx](https://github.com/marketplace/actions/docker-setup-buildx) action. -3. Builds the container image and pushes it to the Docker Hub repository, using - [Build and push Docker images](https://github.com/marketplace/actions/build-and-push-docker-images). - - The `with` key lists a number of input parameters that configures the step: - - - `push`: tells the action to upload the image to a registry after building - it. - - `tags`: tags that specify where to push the image. - -Add these steps to your workflow file. The full workflow configuration should -look as follows: - - -```yaml -name: ci - -on: - push: - branches: - - "main" - -jobs: - build: - runs-on: ubuntu-latest - steps: - - - name: Login to Docker Hub - uses: docker/login-action@v3 - with: - username: ${{ vars.DOCKERHUB_USERNAME }} - password: ${{ secrets.DOCKERHUB_TOKEN }} - - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@v3 - - - name: Build and push - uses: docker/build-push-action@v6 - with: - push: true - tags: ${{ vars.DOCKERHUB_USERNAME }}/clockbox:latest -``` - -### Run the workflow - -Save the workflow file and run the job. - -1. Select **Commit changes...** and push the changes to the `main` branch. - - After pushing the commit, the workflow starts automatically. - -2. Go to the **Actions** tab. It displays the workflow. - - Selecting the workflow shows you the breakdown of all the steps. - -3. When the workflow is complete, go to your - [repositories on Docker Hub](https://hub.docker.com/repositories). - - If you see the new repository in that list, it means the GitHub Actions - successfully pushed the image to Docker Hub. - -## Next steps - -This tutorial has shown you how to create a simple GitHub Actions workflow, -using the official Docker actions, to build and push an image to Docker Hub. - -There are many more things you can do to customize your workflow to better suit -your needs. To learn more about some of the more advanced use cases, take a look -at the advanced examples, such as [building multi-platform images](multi-platform.md), -or [using cache storage backends](cache.md) and also how to [configure your builder](configure-builder.md). +The [Introduction to GitHub Actions with Docker](/guides/gha.md) guide walks +you through the process of setting up and using Docker GitHub Actions for +building Docker images, and pushing images to Docker Hub. diff --git a/content/manuals/build/ci/github-actions/annotations.md b/content/manuals/build/ci/github-actions/annotations.md index 713c452f476..df52d16afa0 100644 --- a/content/manuals/build/ci/github-actions/annotations.md +++ b/content/manuals/build/ci/github-actions/annotations.md @@ -33,15 +33,15 @@ jobs: docker: runs-on: ubuntu-latest steps: - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@v3 - - name: Login to Docker Hub uses: docker/login-action@v3 with: username: ${{ vars.DOCKERHUB_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + - name: Extract metadata id: meta uses: docker/metadata-action@v5 @@ -75,14 +75,14 @@ jobs: - name: Checkout uses: actions/checkout@v4 - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@v3 - - name: Login to Docker Hub uses: docker/login-action@v3 with: username: ${{ vars.DOCKERHUB_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 - name: Extract metadata id: meta @@ -128,14 +128,14 @@ jobs: docker: runs-on: ubuntu-latest steps: - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@v3 - - name: Login to Docker Hub uses: docker/login-action@v3 with: username: ${{ vars.DOCKERHUB_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 - name: Extract metadata id: meta diff --git a/content/manuals/build/ci/github-actions/attestations.md b/content/manuals/build/ci/github-actions/attestations.md index 4e37da3df78..eb99baf0d2d 100644 --- a/content/manuals/build/ci/github-actions/attestations.md +++ b/content/manuals/build/ci/github-actions/attestations.md @@ -62,14 +62,14 @@ jobs: docker: runs-on: ubuntu-latest steps: - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@v3 - - name: Login to Docker Hub uses: docker/login-action@v3 with: username: ${{ vars.DOCKERHUB_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 - name: Extract metadata id: meta @@ -108,15 +108,15 @@ jobs: docker: runs-on: ubuntu-latest steps: - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@v3 - - name: Login to Docker Hub uses: docker/login-action@v3 with: username: ${{ vars.DOCKERHUB_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + - name: Extract metadata id: meta uses: docker/metadata-action@v5 diff --git a/content/manuals/build/ci/github-actions/build-summary.md b/content/manuals/build/ci/github-actions/build-summary.md index df64c5e4387..c41c654c042 100644 --- a/content/manuals/build/ci/github-actions/build-summary.md +++ b/content/manuals/build/ci/github-actions/build-summary.md @@ -69,9 +69,8 @@ select the item in the list. To disable job summaries, set the `DOCKER_BUILD_SUMMARY` environment variable in the YAML configuration for your build step: -```yaml {hl_lines=5} - - - name: Build +```yaml {hl_lines=4} + - name: Build uses: docker/docker-build-push-action@v6 env: DOCKER_BUILD_SUMMARY: false @@ -86,9 +85,8 @@ To disable the upload of the build record archive to GitHub, set the `DOCKER_BUILD_RECORD_UPLOAD` environment variable in the YAML configuration for your build step: -```yaml {hl_lines=5} - - - name: Build +```yaml {hl_lines=4} + - name: Build uses: docker/docker-build-push-action@v6 env: DOCKER_BUILD_RECORD_UPLOAD: false diff --git a/content/manuals/build/ci/github-actions/cache.md b/content/manuals/build/ci/github-actions/cache.md index eb8d9d47d69..bb12ba8b660 100644 --- a/content/manuals/build/ci/github-actions/cache.md +++ b/content/manuals/build/ci/github-actions/cache.md @@ -29,14 +29,14 @@ jobs: docker: runs-on: ubuntu-latest steps: - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@v3 - - name: Login to Docker Hub uses: docker/login-action@v3 with: username: ${{ vars.DOCKERHUB_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 - name: Build and push uses: docker/build-push-action@v6 @@ -62,15 +62,15 @@ jobs: docker: runs-on: ubuntu-latest steps: - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@v3 - - name: Login to Docker Hub uses: docker/login-action@v3 with: username: ${{ vars.DOCKERHUB_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + - name: Build and push uses: docker/build-push-action@v6 with: @@ -107,15 +107,15 @@ jobs: docker: runs-on: ubuntu-latest steps: - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@v3 - - name: Login to Docker Hub uses: docker/login-action@v3 with: username: ${{ vars.DOCKERHUB_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + - name: Build and push uses: docker/build-push-action@v6 with: @@ -165,6 +165,12 @@ jobs: build: runs-on: ubuntu-latest steps: + - name: Login to Docker Hub + uses: docker/login-action@v3 + with: + username: ${{ vars.DOCKERHUB_USERNAME }} + password: ${{ secrets.DOCKERHUB_TOKEN }} + - name: Set up QEMU uses: docker/setup-qemu-action@v3 @@ -175,7 +181,7 @@ jobs: id: meta uses: docker/metadata-action@v5 with: - images: YOUR_IMAGE + images: user/app tags: | type=ref,event=branch type=ref,event=pr @@ -188,7 +194,7 @@ jobs: path: go-build-cache key: ${{ runner.os }}-go-build-cache-${{ hashFiles('**/go.sum') }} - - name: inject go-build-cache into docker + - name: Inject go-build-cache uses: reproducible-containers/buildkit-cache-dance@4b2444fec0c0fb9dbf175a96c094720a692ef810 # v2.1.4 with: cache-source: go-build-cache @@ -230,9 +236,15 @@ jobs: docker: runs-on: ubuntu-latest steps: + - name: Login to Docker Hub + uses: docker/login-action@v3 + with: + username: ${{ vars.DOCKERHUB_USERNAME }} + password: ${{ secrets.DOCKERHUB_TOKEN }} + - name: Set up Docker Buildx uses: docker/setup-buildx-action@v3 - + - name: Cache Docker layers uses: actions/cache@v4 with: @@ -240,13 +252,7 @@ jobs: key: ${{ runner.os }}-buildx-${{ github.sha }} restore-keys: | ${{ runner.os }}-buildx- - - - name: Login to Docker Hub - uses: docker/login-action@v3 - with: - username: ${{ vars.DOCKERHUB_USERNAME }} - password: ${{ secrets.DOCKERHUB_TOKEN }} - + - name: Build and push uses: docker/build-push-action@v6 with: @@ -254,7 +260,7 @@ jobs: tags: user/app:latest cache-from: type=local,src=/tmp/.buildx-cache cache-to: type=local,dest=/tmp/.buildx-cache-new,mode=max - + - # Temp fix # https://github.com/docker/build-push-action/issues/252 # https://github.com/moby/buildkit/issues/1896 diff --git a/content/manuals/build/ci/github-actions/checks.md b/content/manuals/build/ci/github-actions/checks.md new file mode 100644 index 00000000000..dc3bda46314 --- /dev/null +++ b/content/manuals/build/ci/github-actions/checks.md @@ -0,0 +1,103 @@ +--- +title: Validating build configuration with GitHub Actions +linkTitle: Build checks +description: Discover how to validate your build configuration and identify best practice violations using build checks in GitHub Actions. +keywords: github actions, gha, build, checks +--- + +[Build checks](/manuals/build/checks.md) let you validate your `docker build` +configuration without actually running the build. + +## Run checks with `docker/build-push-action` + +To run build checks in a GitHub Actions workflow with the `build-push-action`, +set the `call` input parameter to `check`. With this set, the workflow fails if +any check warnings are detected for your build's configuration. + +```yaml +name: ci + +on: + push: + +jobs: + docker: + runs-on: ubuntu-latest + steps: + - name: Login to Docker Hub + uses: docker/login-action@v3 + with: + username: ${{ secrets.DOCKERHUB_USERNAME }} + password: ${{ secrets.DOCKERHUB_TOKEN }} + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + + - name: Validate build configuration + uses: docker/build-push-action@v6 + with: + call: check + + - name: Build and push + uses: docker/build-push-action@v6 + with: + push: true + tags: user/app:latest +``` + +## Run checks with `docker/bake-action` + +If you're using Bake and `docker/bake-action` to run your builds, you don't +need to specify any special inputs in your GitHub Actions workflow +configuration. Instead, define a Bake target that calls the `check` method, +and invoke that target in your CI. + +```hcl +target "build" { + dockerfile = "Dockerfile" + args = { + FOO = "bar" + } +} +target "validate-build" { + inherits = ["build"] + call = "check" +} +``` + +```yaml +name: ci + +on: + push: + +env: + IMAGE_NAME: user/app + +jobs: + docker: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Login to Docker Hub + uses: docker/login-action@v3 + with: + username: ${{ vars.DOCKERHUB_USERNAME }} + password: ${{ secrets.DOCKERHUB_TOKEN }} + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + + - name: Validate build configuration + uses: docker/bake-action@v5 + with: + targets: validate-build + + - name: Build + uses: docker/bake-action@v5 + with: + targets: build + push: true +``` diff --git a/content/manuals/build/ci/github-actions/copy-image-registries.md b/content/manuals/build/ci/github-actions/copy-image-registries.md index b66e9f6739a..4897a070f8f 100644 --- a/content/manuals/build/ci/github-actions/copy-image-registries.md +++ b/content/manuals/build/ci/github-actions/copy-image-registries.md @@ -18,25 +18,25 @@ jobs: docker: runs-on: ubuntu-latest steps: - - name: Set up QEMU - uses: docker/setup-qemu-action@v3 - - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@v3 - - name: Login to Docker Hub uses: docker/login-action@v3 with: username: ${{ vars.DOCKERHUB_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} - + - name: Login to GitHub Container Registry uses: docker/login-action@v3 with: registry: ghcr.io username: ${{ github.repository_owner }} password: ${{ secrets.GITHUB_TOKEN }} + + - name: Set up QEMU + uses: docker/setup-qemu-action@v3 + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + - name: Build and push uses: docker/build-push-action@v6 with: @@ -45,7 +45,7 @@ jobs: tags: | user/app:latest user/app:1.0.0 - + - name: Push image to GHCR run: | docker buildx imagetools create \ diff --git a/content/manuals/build/ci/github-actions/manage-tags-labels.md b/content/manuals/build/ci/github-actions/manage-tags-labels.md index 162536a63d0..00d2082585b 100644 --- a/content/manuals/build/ci/github-actions/manage-tags-labels.md +++ b/content/manuals/build/ci/github-actions/manage-tags-labels.md @@ -44,20 +44,14 @@ jobs: type=semver,pattern={{major}}.{{minor}} type=semver,pattern={{major}} type=sha - - - name: Set up QEMU - uses: docker/setup-qemu-action@v3 - - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@v3 - + - name: Login to Docker Hub if: github.event_name != 'pull_request' uses: docker/login-action@v3 with: username: ${{ vars.DOCKERHUB_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} - + - name: Login to GHCR if: github.event_name != 'pull_request' uses: docker/login-action@v3 @@ -65,7 +59,13 @@ jobs: registry: ghcr.io username: ${{ github.repository_owner }} password: ${{ secrets.GITHUB_TOKEN }} - + + - name: Set up QEMU + uses: docker/setup-qemu-action@v3 + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + - name: Build and push uses: docker/build-push-action@v6 with: diff --git a/content/manuals/build/ci/github-actions/multi-platform.md b/content/manuals/build/ci/github-actions/multi-platform.md index 5fb013ed7ef..a04c73562cb 100644 --- a/content/manuals/build/ci/github-actions/multi-platform.md +++ b/content/manuals/build/ci/github-actions/multi-platform.md @@ -25,23 +25,76 @@ jobs: docker: runs-on: ubuntu-latest steps: + - name: Login to Docker Hub + uses: docker/login-action@v3 + with: + username: ${{ vars.DOCKERHUB_USERNAME }} + password: ${{ secrets.DOCKERHUB_TOKEN }} + - name: Set up QEMU uses: docker/setup-qemu-action@v3 - + - name: Set up Docker Buildx uses: docker/setup-buildx-action@v3 - + + - name: Build and push + uses: docker/build-push-action@v6 + with: + platforms: linux/amd64,linux/arm64 + push: true + tags: user/app:latest +``` + +## Build and load multi-platform images + +The default Docker setup for GitHub Actions runners does not support loading +multi-platform images to the local image store of the runner after building +them. To load a multi-platform image, you need to enable the containerd image +store option for the Docker Engine. + +There is no way to configure the default Docker setup in the GitHub Actions +runners directly, but you can use `docker/setup-docker-action` to customize the +Docker Engine and CLI settings for a job. + +The following example workflow enables the containerd image store, builds a +multi-platform image, and loads the results into the GitHub runner's local +image store. + +```yaml +name: ci + +on: + push: + +jobs: + docker: + runs-on: ubuntu-latest + steps: + - name: Set up Docker + uses: docker/setup-docker-action@v4 + with: + daemon-config: | + { + "debug": true, + "features": { + "containerd-snapshotter": true + } + } + - name: Login to Docker Hub uses: docker/login-action@v3 with: username: ${{ vars.DOCKERHUB_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} - + + - name: Set up QEMU + uses: docker/setup-qemu-action@v3 + - name: Build and push uses: docker/build-push-action@v6 with: platforms: linux/amd64,linux/arm64 - push: true + load: true tags: user/app:latest ``` @@ -56,7 +109,10 @@ each platform across multiple runners and create manifest list using the The following workflow will build the image for each platform on a dedicated runner using a matrix strategy and push by digest. Then, the `merge` job will -create a manifest list and push it to Docker Hub. +create manifest lists and push them to two registries: + +- Docker Hub: `docker.io/docker-user/my-app` +- GitHub Container Registry: `ghcr.io/gh-user/my-app` This example also uses the [`metadata` action](https://github.com/docker/metadata-action) to set tags and labels. @@ -68,7 +124,8 @@ on: push: env: - REGISTRY_IMAGE: user/app + DOCKERHUB_REPO: docker-user/my-app + GHCR_REPO: ghcr.io/gh-user/my-app jobs: build: @@ -78,47 +135,54 @@ jobs: matrix: platform: - linux/amd64 - - linux/arm/v6 - - linux/arm/v7 - linux/arm64 steps: - name: Prepare run: | platform=${{ matrix.platform }} echo "PLATFORM_PAIR=${platform//\//-}" >> $GITHUB_ENV - + - name: Docker meta id: meta uses: docker/metadata-action@v5 with: - images: ${{ env.REGISTRY_IMAGE }} - - - name: Set up QEMU - uses: docker/setup-qemu-action@v3 - - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@v3 - + images: | + ${{ env.DOCKERHUB_REPO }} + ${{ env.GHCR_REPO }} + - name: Login to Docker Hub uses: docker/login-action@v3 with: username: ${{ vars.DOCKERHUB_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} - + + - name: Login to GHCR + uses: docker/login-action@v3 + with: + registry: ghcr.io + username: ${{ github.repository_owner }} + password: ${{ secrets.GITHUB_TOKEN }} + + - name: Set up QEMU + uses: docker/setup-qemu-action@v3 + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + - name: Build and push by digest id: build uses: docker/build-push-action@v6 with: platforms: ${{ matrix.platform }} labels: ${{ steps.meta.outputs.labels }} - outputs: type=image,name=${{ env.REGISTRY_IMAGE }},push-by-digest=true,name-canonical=true,push=true - + outputs: type=image,"name=${{ env.DOCKERHUB_REPO }},${{ env.GHCR_REPO }}",push-by-digest=true,name-canonical=true,push=true + - name: Export digest run: | mkdir -p /tmp/digests digest="${{ steps.build.outputs.digest }}" touch "/tmp/digests/${digest#sha256:}" - + - name: Upload digest uses: actions/upload-artifact@v4 with: @@ -138,31 +202,48 @@ jobs: path: /tmp/digests pattern: digests-* merge-multiple: true - + + - name: Login to Docker Hub + uses: docker/login-action@v3 + with: + username: ${{ vars.DOCKERHUB_USERNAME }} + password: ${{ secrets.DOCKERHUB_TOKEN }} + + - name: Login to GHCR + uses: docker/login-action@v3 + with: + registry: ghcr.io + username: ${{ github.repository_owner }} + password: ${{ secrets.GITHUB_TOKEN }} + - name: Set up Docker Buildx uses: docker/setup-buildx-action@v3 - + - name: Docker meta id: meta uses: docker/metadata-action@v5 with: - images: ${{ env.REGISTRY_IMAGE }} - - - name: Login to Docker Hub - uses: docker/login-action@v3 - with: - username: ${{ vars.DOCKERHUB_USERNAME }} - password: ${{ secrets.DOCKERHUB_TOKEN }} - + images: | + ${{ env.DOCKERHUB_REPO }} + ${{ env.GHCR_REPO }} + tags: | + type=ref,event=branch + type=ref,event=pr + type=semver,pattern={{version}} + type=semver,pattern={{major}}.{{minor}} + - name: Create manifest list and push working-directory: /tmp/digests run: | docker buildx imagetools create $(jq -cr '.tags | map("-t " + .) | join(" ")' <<< "$DOCKER_METADATA_OUTPUT_JSON") \ - $(printf '${{ env.REGISTRY_IMAGE }}@sha256:%s ' *) - + $(printf '${{ env.DOCKERHUB_REPO }}@sha256:%s ' *) + docker buildx imagetools create $(jq -cr '.tags | map("-t " + .) | join(" ")' <<< "$DOCKER_METADATA_OUTPUT_JSON") \ + $(printf '${{ env.GHCR_REPO }}@sha256:%s ' *) + - name: Inspect image run: | - docker buildx imagetools inspect ${{ env.REGISTRY_IMAGE }}:${{ steps.meta.outputs.version }} + docker buildx imagetools inspect ${{ env.DOCKERHUB_REPO }}:${{ steps.meta.outputs.version }} + docker buildx imagetools inspect ${{ env.GHCR_REPO }}:${{ steps.meta.outputs.version }} ``` ### With Bake @@ -227,26 +308,26 @@ jobs: steps: - name: Checkout uses: actions/checkout@v4 - + - name: Create matrix id: platforms run: | echo "matrix=$(docker buildx bake image-all --print | jq -cr '.target."image-all".platforms')" >>${GITHUB_OUTPUT} - + - name: Show matrix run: | echo ${{ steps.platforms.outputs.matrix }} - + - name: Docker meta id: meta uses: docker/metadata-action@v5 with: images: ${{ env.REGISTRY_IMAGE }} - + - name: Rename meta bake definition file run: | mv "${{ steps.meta.outputs.bake-file }}" "/tmp/bake-meta.json" - + - name: Upload meta bake definition uses: actions/upload-artifact@v4 with: @@ -268,28 +349,28 @@ jobs: run: | platform=${{ matrix.platform }} echo "PLATFORM_PAIR=${platform//\//-}" >> $GITHUB_ENV - + - name: Checkout uses: actions/checkout@v4 - + - name: Download meta bake definition uses: actions/download-artifact@v4 with: name: bake-meta path: /tmp - - name: Set up QEMU - uses: docker/setup-qemu-action@v3 - - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@v3 - - name: Login to Docker Hub uses: docker/login-action@v3 with: username: ${{ vars.DOCKERHUB_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} - + + - name: Set up QEMU + uses: docker/setup-qemu-action@v3 + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + - name: Build id: bake uses: docker/bake-action@v5 @@ -302,13 +383,13 @@ jobs: *.tags= *.platform=${{ matrix.platform }} *.output=type=image,"name=${{ env.REGISTRY_IMAGE }}",push-by-digest=true,name-canonical=true,push=true - + - name: Export digest run: | mkdir -p /tmp/digests digest="${{ fromJSON(steps.bake.outputs.metadata).image['containerimage.digest'] }}" touch "/tmp/digests/${digest#sha256:}" - + - name: Upload digest uses: actions/upload-artifact@v4 with: @@ -327,29 +408,29 @@ jobs: with: name: bake-meta path: /tmp - + - name: Download digests uses: actions/download-artifact@v4 with: path: /tmp/digests pattern: digests-* merge-multiple: true - - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@v3 - + - name: Login to DockerHub uses: docker/login-action@v3 with: username: ${{ vars.DOCKERHUB_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} - + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + - name: Create manifest list and push working-directory: /tmp/digests run: | docker buildx imagetools create $(jq -cr '.target."docker-metadata-action".tags | map(select(startswith("${{ env.REGISTRY_IMAGE }}")) | "-t " + .) | join(" ")' /tmp/bake-meta.json) \ $(printf '${{ env.REGISTRY_IMAGE }}@sha256:%s ' *) - + - name: Inspect image run: | docker buildx imagetools inspect ${{ env.REGISTRY_IMAGE }}:$(jq -r '.target."docker-metadata-action".args.DOCKER_META_VERSION' /tmp/bake-meta.json) diff --git a/content/manuals/build/ci/github-actions/named-contexts.md b/content/manuals/build/ci/github-actions/named-contexts.md index fe81c03e073..0419bae733a 100644 --- a/content/manuals/build/ci/github-actions/named-contexts.md +++ b/content/manuals/build/ci/github-actions/named-contexts.md @@ -34,7 +34,7 @@ jobs: steps: - name: Set up Docker Buildx uses: docker/setup-buildx-action@v3 - + - name: Build uses: docker/build-push-action@v6 with: @@ -71,14 +71,14 @@ jobs: uses: docker/setup-buildx-action@v3 with: driver: docker - + - name: Build base image uses: docker/build-push-action@v6 with: context: "{{defaultContext}}:base" load: true tags: my-base-image:latest - + - name: Build uses: docker/build-push-action@v6 with: @@ -118,20 +118,20 @@ jobs: steps: - name: Set up QEMU uses: docker/setup-qemu-action@v3 - + - name: Set up Docker Buildx uses: docker/setup-buildx-action@v3 with: # network=host driver-opt needed to push to local registry driver-opts: network=host - + - name: Build base image uses: docker/build-push-action@v6 with: context: "{{defaultContext}}:base" tags: localhost:5000/my-base-image:latest push: true - + - name: Build uses: docker/build-push-action@v6 with: diff --git a/content/manuals/build/ci/github-actions/push-multi-registries.md b/content/manuals/build/ci/github-actions/push-multi-registries.md index 5b2cb4c1844..617b39d7cff 100644 --- a/content/manuals/build/ci/github-actions/push-multi-registries.md +++ b/content/manuals/build/ci/github-actions/push-multi-registries.md @@ -18,25 +18,25 @@ jobs: docker: runs-on: ubuntu-latest steps: - - name: Set up QEMU - uses: docker/setup-qemu-action@v3 - - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@v3 - - name: Login to Docker Hub uses: docker/login-action@v3 with: username: ${{ vars.DOCKERHUB_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} - + - name: Login to GitHub Container Registry uses: docker/login-action@v3 with: registry: ghcr.io username: ${{ github.repository_owner }} password: ${{ secrets.GITHUB_TOKEN }} - + + - name: Set up QEMU + uses: docker/setup-qemu-action@v3 + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + - name: Build and push uses: docker/build-push-action@v6 with: diff --git a/content/manuals/build/ci/github-actions/reproducible-builds.md b/content/manuals/build/ci/github-actions/reproducible-builds.md index a88cc019f6f..d7c88a9b14d 100644 --- a/content/manuals/build/ci/github-actions/reproducible-builds.md +++ b/content/manuals/build/ci/github-actions/reproducible-builds.md @@ -34,7 +34,7 @@ jobs: steps: - name: Set up Docker Buildx uses: docker/setup-buildx-action@v3 - + - name: Build uses: docker/build-push-action@v6 with: @@ -58,10 +58,10 @@ jobs: steps: - name: Checkout uses: actions/checkout@v4 - + - name: Set up Docker Buildx uses: docker/setup-buildx-action@v3 - + - name: Build uses: docker/bake-action@v5 env: @@ -90,10 +90,10 @@ jobs: steps: - name: Set up Docker Buildx uses: docker/setup-buildx-action@v3 - + - name: Get Git commit timestamps run: echo "TIMESTAMP=$(git log -1 --pretty=%ct)" >> $GITHUB_ENV - + - name: Build uses: docker/build-push-action@v6 with: @@ -117,13 +117,13 @@ jobs: steps: - name: Checkout uses: actions/checkout@v4 - + - name: Set up Docker Buildx uses: docker/setup-buildx-action@v3 - + - name: Get Git commit timestamps run: echo "TIMESTAMP=$(git log -1 --pretty=%ct)" >> $GITHUB_ENV - + - name: Build uses: docker/bake-action@v5 env: diff --git a/content/manuals/build/ci/github-actions/secrets.md b/content/manuals/build/ci/github-actions/secrets.md index 4931409414d..2048b2c7766 100644 --- a/content/manuals/build/ci/github-actions/secrets.md +++ b/content/manuals/build/ci/github-actions/secrets.md @@ -44,10 +44,10 @@ jobs: steps: - name: Set up QEMU uses: docker/setup-qemu-action@v3 - + - name: Set up Docker Buildx uses: docker/setup-buildx-action@v3 - + - name: Build uses: docker/build-push-action@v6 with: @@ -176,7 +176,7 @@ jobs: host: github.com private-key: ${{ secrets.SSH_GITHUB_PPK }} private-key-name: github-ppk - + - name: Build and push uses: docker/build-push-action@v6 with: @@ -200,14 +200,14 @@ jobs: steps: - name: Checkout uses: actions/checkout@v4 - + - name: Set up SSH uses: MrSquaare/ssh-setup-action@2d028b70b5e397cf8314c6eaea229a6c3e34977a # v3.1.0 with: host: github.com private-key: ${{ secrets.SSH_GITHUB_PPK }} private-key-name: github-ppk - + - name: Build uses: docker/bake-action@v5 with: diff --git a/content/manuals/build/ci/github-actions/share-image-jobs.md b/content/manuals/build/ci/github-actions/share-image-jobs.md index 995dd08a899..17cb2d29c18 100644 --- a/content/manuals/build/ci/github-actions/share-image-jobs.md +++ b/content/manuals/build/ci/github-actions/share-image-jobs.md @@ -24,13 +24,13 @@ jobs: steps: - name: Set up Docker Buildx uses: docker/setup-buildx-action@v3 - + - name: Build and export uses: docker/build-push-action@v6 with: tags: myimage:latest outputs: type=docker,dest=/tmp/myimage.tar - + - name: Upload artifact uses: actions/upload-artifact@v4 with: @@ -46,7 +46,7 @@ jobs: with: name: myimage path: /tmp - + - name: Load image run: | docker load --input /tmp/myimage.tar diff --git a/content/manuals/build/ci/github-actions/test-before-push.md b/content/manuals/build/ci/github-actions/test-before-push.md index 064f45665cd..05c5f824b26 100644 --- a/content/manuals/build/ci/github-actions/test-before-push.md +++ b/content/manuals/build/ci/github-actions/test-before-push.md @@ -27,28 +27,28 @@ jobs: docker: runs-on: ubuntu-latest steps: - - name: Set up QEMU - uses: docker/setup-qemu-action@v3 - - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@v3 - - name: Login to Docker Hub uses: docker/login-action@v3 with: username: ${{ vars.DOCKERHUB_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} - + + - name: Set up QEMU + uses: docker/setup-qemu-action@v3 + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + - name: Build and export to Docker uses: docker/build-push-action@v6 with: load: true tags: ${{ env.TEST_TAG }} - + - name: Test run: | docker run --rm ${{ env.TEST_TAG }} - + - name: Build and push uses: docker/build-push-action@v6 with: diff --git a/content/manuals/build/ci/github-actions/update-dockerhub-desc.md b/content/manuals/build/ci/github-actions/update-dockerhub-desc.md index 04ed5cc3a68..6c49dc3ce88 100644 --- a/content/manuals/build/ci/github-actions/update-dockerhub-desc.md +++ b/content/manuals/build/ci/github-actions/update-dockerhub-desc.md @@ -19,24 +19,24 @@ jobs: docker: runs-on: ubuntu-latest steps: - - name: Set up QEMU - uses: docker/setup-qemu-action@v3 - - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@v3 - - name: Login to Docker Hub uses: docker/login-action@v3 with: username: ${{ vars.DOCKERHUB_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} - + + - name: Set up QEMU + uses: docker/setup-qemu-action@v3 + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + - name: Build and push uses: docker/build-push-action@v6 with: push: true tags: user/app:latest - + - name: Update repo description uses: peter-evans/dockerhub-description@e98e4d1628a5f3be2be7c231e50981aee98723ae # v4.0.0 with: diff --git a/content/manuals/build/concepts/overview.md b/content/manuals/build/concepts/overview.md index 8b30d385405..e8a101e649f 100644 --- a/content/manuals/build/concepts/overview.md +++ b/content/manuals/build/concepts/overview.md @@ -38,6 +38,11 @@ the CLI plugin from source, or grab a binary from the GitHub repository and install it manually. See [Buildx README](https://github.com/docker/buildx#manual-download) on GitHub for more information. +> [!NOTE] +> While `docker build` invokes Buildx under the hood, there are subtle +> differences between this command and the canonical `docker buildx build`. +> For details, see [Difference between `docker build` and `docker buildx build`](../builders/_index.md#difference-between-docker-build-and-docker-buildx-build). + ## BuildKit BuildKit is the daemon process that executes the build workloads. diff --git a/content/manuals/build/exporters/_index.md b/content/manuals/build/exporters/_index.md index e5dc78fbc0d..3aae8b94403 100644 --- a/content/manuals/build/exporters/_index.md +++ b/content/manuals/build/exporters/_index.md @@ -148,7 +148,7 @@ The `local` exporter unpacks the filesystem into a directory structure in the specified location. The `tar` exporter creates a tarball archive file. ```console -$ docker buildx build --output type=tar,dest= . +$ docker buildx build --output type=local,dest= . ``` The `local` exporter is useful in [multi-stage builds](../building/multi-stage.md) diff --git a/content/manuals/build/images/build-variables.svg b/content/manuals/build/images/build-variables.svg index 6bd6d77689c..13197975fb1 100644 --- a/content/manuals/build/images/build-variables.svg +++ b/content/manuals/build/images/build-variables.svg @@ -1,3 +1,3 @@ - Global scope# Build arguments declared here are in the global scopeARG GLOBAL_ARG="global default value"ARG VERSION="3.19"# You can't declare environment variables in the global scopeENV GLOBAL_ENV=false# GLOBAL_ARG was not redeclared in this stageRUN echo $GLOBAL_ARG# LOCAL_ARG was declared in stage-aRUN echo $LOCAL_ARGstage-bFROM --platform=$BUILDPLATFORM alpine:${VERSION} as stage-bstage-a# FROM-lines belong to the global scope and have access to global ARGsFROM alpine:${VERSION} as stage-a# Redeclaring GLOBAL_ARG without a value inherits the global defaultARG GLOBAL_ARGRUN echo $GLOBAL_ARG# ARG here this scope creates a local argumentARG LOCAL_ARG="local arg in stage-a"# Set an environment variable in this scopeENV LOCAL_ENV=true# Set an environment variable to the value of a build argumentENV MY_VAR=$LOCAL_ARGstage-c# New stage based on "stage-a"FROM stage-a AS stage-c# Arguments and variables are inherited from parent stagesRUN echo $LOCAL_ARGRUN echo $LOCAL_ENV<- prints an emptry string<- prints an emptry string<- prints "global default value"<- prints "local arg in stage-a"<- prints "true"ARG TARGETPLATFORM# You must redeclare pre-defined arguments to use them in a stageRUN echo $TARGETPLATFORM<- prints os/arch/variant of --platform# Pre-defined multi-platform arguments like $BUILDPLATFORM are global + Global scope# Build arguments declared here are in the global scopeARG GLOBAL_ARG="global default value"ARG VERSION="3.19"# You can't declare environment variables in the global scopeENV GLOBAL_ENV=false# GLOBAL_ARG was not redeclared in this stageRUN echo $GLOBAL_ARG# LOCAL_ARG was declared in stage-aRUN echo $LOCAL_ARGstage-bFROM --platform=$BUILDPLATFORM alpine:${VERSION} as stage-bstage-a# FROM-lines belong to the global scope and have access to global ARGsFROM alpine:${VERSION} as stage-a# Redeclaring GLOBAL_ARG without a value inherits the global defaultARG GLOBAL_ARGRUN echo $GLOBAL_ARG# ARG here this scope creates a local argumentARG LOCAL_ARG="local arg in stage-a"# Set an environment variable in this scopeENV LOCAL_ENV=true# Set an environment variable to the value of a build argumentENV MY_VAR=$LOCAL_ARGstage-c# New stage based on "stage-a"FROM stage-a AS stage-c# Arguments and variables are inherited from parent stagesRUN echo $LOCAL_ARGRUN echo $LOCAL_ENV<- prints an empty string<- prints an empty string<- prints "global default value"<- prints "local arg in stage-a"<- prints "true"ARG TARGETPLATFORM# You must redeclare pre-defined arguments to use them in a stageRUN echo $TARGETPLATFORM<- prints os/arch/variant of --platform# Pre-defined multi-platform arguments like $BUILDPLATFORM are global diff --git a/content/manuals/build/metadata/attestations/_index.md b/content/manuals/build/metadata/attestations/_index.md index 84ccfac5c08..fc9530a05b5 100644 --- a/content/manuals/build/metadata/attestations/_index.md +++ b/content/manuals/build/metadata/attestations/_index.md @@ -8,6 +8,8 @@ aliases: - /build/attestations/ --- +{{< youtube-embed qOzcycbTs4o >}} + 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. @@ -60,7 +62,7 @@ $ docker buildx build --sbom=true --provenance=true . > > - Use a `docker-container` driver with the `--push` flag to push the image to > a registry directly. -> - Enable the [containerd image store](/manuals/desktop/containerd.md). +> - Enable the [containerd image store](/manuals/desktop/features/containerd.md). > [!NOTE] > diff --git a/content/manuals/build/release-notes.md b/content/manuals/build/release-notes.md index 73096e72437..9e27b9f79b1 100644 --- a/content/manuals/build/release-notes.md +++ b/content/manuals/build/release-notes.md @@ -10,6 +10,98 @@ toc_max: 2 This page contains information about the new features, improvements, and bug fixes in [Docker Buildx](https://github.com/docker/buildx). +## 0.19.1 + +{{< release-date date="2024-11-27" >}} + +The full release note for this release is available +[on GitHub](https://github.com/docker/buildx/releases/tag/v0.19.1). + +### Bug fixes + +- Reverted the change in v0.19.0 that added new object notation for the fields + that previously required CSV strings in Bake definition. This enhancement was + reverted because of backwards incompatibility issues were discovered in some + edge cases. This feature has now been postponed to the v0.20.0 release. + [docker/buildx#2824](https://github.com/docker/buildx/pull/2824) + +## 0.19.0 + +{{< release-date date="2024-11-27" >}} + +The full release note for this release is available +[on GitHub](https://github.com/docker/buildx/releases/tag/v0.19.0). + +### New + +- Bake now requires you to allow filesystem entitlements when your build needs + to read or write files outside of your current working directory. + [docker/buildx#2796](https://github.com/docker/buildx/pull/2796), + [docker/buildx#2812](https://github.com/docker/buildx/pull/2812). + + To allow filesystem entitlements, use the `--allow fs.read=` flag for + the `docker buildx bake` command. + + This feature currently only reports a warning when using a local Bake + definition, but will start to produce an error starting from the v0.20 + release. To enable the error in the current release, you can set + `BUILDX_BAKE_ENTITLEMENTS_FS=1`. + +### Enhancements + +- Bake definition now supports new object notation for the fields that previously required CSV strings as inputs. [docker/buildx#2758](https://github.com/docker/buildx/pull/2758) + + > [!NOTE] + > This enhancement was reverted in [v0.19.1](#0191) due to a bug. + +- Bake definition now allows defining validation conditions to variables. [docker/buildx#2794](https://github.com/docker/buildx/pull/2794) +- Metadata file values can now contain JSON array values. [docker/buildx#2777](https://github.com/docker/buildx/pull/2777) +- Improved error messages when using an incorrect format for labels. [docker/buildx#2778](https://github.com/docker/buildx/pull/2778) +- FreeBSD and OpenBSD artifacts are now included in the release. [docker/buildx#2774](https://github.com/docker/buildx/pull/2774), [docker/buildx#2775](https://github.com/docker/buildx/pull/2775), [docker/buildx#2781](https://github.com/docker/buildx/pull/2781) + +### Bug fixes + +- Fixed an issue with printing Bake definitions containing empty Compose networks. [docker/buildx#2790](https://github.com/docker/buildx/pull/2790). + +### Packaging + +- Compose support has been updated to v2.4.4. [docker/buildx#2806](https://github.com/docker/buildx/pull/2806) [docker/buildx#2780](https://github.com/docker/buildx/pull/2780). + +## 0.18.0 + +{{< release-date date="2024-10-31" >}} + +The full release note for this release is available +[on GitHub](https://github.com/docker/buildx/releases/tag/v0.18.0). + +### New + +- The `docker buildx inspect` command now displays BuildKit daemon configuration options set with a TOML file. [docker/buildx#2684](https://github.com/docker/buildx/pull/2684) +- The `docker buildx ls` command output is now more compact by default by compacting the platform list. A new `--no-trunc` option can be used for the full list. [docker/buildx#2138](https://github.com/docker/buildx/pull/2138), [docker/buildx#2717](https://github.com/docker/buildx/pull/2717) +- The `docker buildx prune` command now supports new `--max-used-space` and `--min-free-space` filters with BuildKit v0.17.0+ builders. [docker/buildx#2766](https://github.com/docker/buildx/pull/2766) + +### Enhancements + +- Allow capturing of CPU and memory profiles with `pprof` using the [`BUILDX_CPU_PROFILE`](/manuals/build/building/variables.md#buildx_cpu_profile) and [`BUILDX_MEM_PROFILE`](/manuals/build/building/variables.md#buildx_mem_profile) environment variables. [docker/buildx#2746](https://github.com/docker/buildx/pull/2746) +- Maximum Dockerfile size from standard input has increased. [docker/buildx#2716](https://github.com/docker/buildx/pull/2716), [docker/buildx#2719](https://github.com/docker/buildx/pull/2719) +- Memory allocations have been reduced. [docker/buildx#2724](https://github.com/docker/buildx/pull/2724), [docker/buildx#2713](https://github.com/docker/buildx/pull/2713) +- The `--list-targets` and `--list-variables` flags for `docker buildx bake` no longer require initialization of the builder. [docker/buildx#2763](https://github.com/docker/buildx/pull/2763) + +### Bug fixes + +- Check warnings now print the full filepath to the offending Dockerfile, relative to the current working directory. [docker/buildx#2672](https://github.com/docker/buildx/pull/2672) +- Fallback images for the `--check` and `--call` options have been updated to correct references. [docker/buildx#2705](https://github.com/docker/buildx/pull/2705) +- Fix issue with the build details link not showing in experimental mode. [docker/buildx#2722](https://github.com/docker/buildx/pull/2722) +- Fix validation issue with invalid target linking for Bake. [docker/buildx#2700](https://github.com/docker/buildx/pull/2700) +- Fix missing error message when running an invalid command. [docker/buildx#2741](https://github.com/docker/buildx/pull/2741) +- Fix possible false warnings for local state in `--call` requests. [docker/buildx#2754](https://github.com/docker/buildx/pull/2754) +- Fix potential issues with entitlements when using linked targets in Bake. [docker/buildx#2701](https://github.com/docker/buildx/pull/2701) +- Fix possible permission issues when accessing local state after running Buildx with `sudo`. [docker/buildx#2745](https://github.com/docker/buildx/pull/2745) + +### Packaging + +- Compose compatibility has been updated to v2.4.1. [docker/buildx#2760](https://github.com/docker/buildx/pull/2760) + ## 0.17.1 {{< release-date date="2024-09-13" >}} diff --git a/content/manuals/cloud/index.md b/content/manuals/cloud/index.md index df096fb61e1..7f651778076 100644 --- a/content/manuals/cloud/index.md +++ b/content/manuals/cloud/index.md @@ -2,6 +2,9 @@ title: Cloud integrations description: ACI and ECS integration information keywords: compose, ACI, ECS, amazon, cloud integration +params: + sidebar: + group: Products aliases: - /engine/context/aci-integration/ - /cloud/aci-integration/ diff --git a/content/manuals/compose/_index.md b/content/manuals/compose/_index.md index 33d034320be..71c95c12a21 100644 --- a/content/manuals/compose/_index.md +++ b/content/manuals/compose/_index.md @@ -1,12 +1,14 @@ --- -title: Docker Compose overview -linkTitle: Docker Compose -weight: 100 +title: Docker Compose +weight: 30 description: Learn how to use Docker Compose to define and run multi-container applications with this detailed introduction to the tool. keywords: docker compose, docker-compose, docker compose command, docker compose files, docker compose documentation, using docker compose, compose container, docker compose service +params: + sidebar: + group: Open source grid: - title: Why use Compose? description: Understand Docker Compose's key benefits diff --git a/content/manuals/compose/gettingstarted.md b/content/manuals/compose/gettingstarted.md index 58cbbc26c21..5475e9e1139 100644 --- a/content/manuals/compose/gettingstarted.md +++ b/content/manuals/compose/gettingstarted.md @@ -59,7 +59,7 @@ Make sure you have: @app.route('/') def hello(): count = get_hit_count() - return 'Hello World! I have been seen {} times.\n'.format(count) + return f'Hello World! I have been seen {count} times.\n' ``` In this example, `redis` is the hostname of the redis container on the @@ -273,7 +273,7 @@ To see Compose Watch in action: message to `Hello from Docker!`: ```python - return 'Hello from Docker! I have been seen {} times.\n'.format(count) + return f'Hello from Docker! I have been seen {count} times.\n' ``` 2. Refresh the app in your browser. The greeting should be updated, and the diff --git a/content/manuals/compose/how-tos/environment-variables/envvars.md b/content/manuals/compose/how-tos/environment-variables/envvars.md index 05196b5ce4d..54a2a5e446a 100644 --- a/content/manuals/compose/how-tos/environment-variables/envvars.md +++ b/content/manuals/compose/how-tos/environment-variables/envvars.md @@ -13,15 +13,14 @@ Compose already comes with pre-defined environment variables. It also inherits c This page contains information on how you can set or change the following pre-defined environment variables if you need to: -- `COMPOSE_CONVERT_WINDOWS_PATHS` +- `COMPOSE_PROJECT_NAME` - `COMPOSE_FILE` - `COMPOSE_PROFILES` -- `COMPOSE_PROJECT_NAME` -- `DOCKER_CERT_PATH` -- `COMPOSE_PARALLEL_LIMIT` +- `COMPOSE_CONVERT_WINDOWS_PATHS` +- `COMPOSE_PATH_SEPARATOR` - `COMPOSE_IGNORE_ORPHANS` - `COMPOSE_REMOVE_ORPHANS` -- `COMPOSE_PATH_SEPARATOR` +- `COMPOSE_PARALLEL_LIMIT` - `COMPOSE_ANSI` - `COMPOSE_STATUS_STDOUT` - `COMPOSE_ENV_FILES` @@ -31,7 +30,7 @@ This page contains information on how you can set or change the following pre-de ## Methods to override You can set or change the pre-defined environment variables: -- With an [`.env` file located in your working director](/manuals/compose/how-tos/environment-variables/variable-interpolation.md) +- With an [`.env` file located in your working directory](/manuals/compose/how-tos/environment-variables/variable-interpolation.md) - From the command line - From your [shell](variable-interpolation.md#substitute-from-the-shell) @@ -68,29 +67,35 @@ See also the [command-line options overview](/reference/cli/docker/compose/_inde Specifies the path to a Compose file. Specifying multiple Compose files is supported. -- Default behavior: If not provided, Compose looks for a file named `compose.yaml` or `docker-compose.yaml` in the current directory and, if not found, then Compose searches each parent directory recursively until a file by that name is found. -- Default separator: When specifying multiple Compose files, the path separators are, by default, on: - * Mac and Linux: `:` (colon), - * Windows: `;` (semicolon). +- Default behavior: If not provided, Compose looks for a file named `compose.yaml` in the current directory and, if not found, then Compose searches each parent directory recursively until a file by that name is found. +- When specifying multiple Compose files, the path separators are, by default, on: + - Mac and Linux: `:` (colon) + - Windows: `;` (semicolon) + For example: -The path separator can also be customized using `COMPOSE_PATH_SEPARATOR`. - -Example: `COMPOSE_FILE=docker-compose.yml:docker-compose.prod.yml`. + ```console + COMPOSE_FILE=docker-compose.yml:docker-compose.prod.yml + ``` + The path separator can also be customized using [`COMPOSE_PATH_SEPARATOR`](#compose_path_separator). See also the [command-line options overview](/reference/cli/docker/compose/_index.md#command-options-overview-and-help) and [using `-f` to specify name and path of one or more Compose files](/reference/cli/docker/compose/_index.md#use--f-to-specify-name-and-path-of-one-or-more-compose-files). ### COMPOSE\_PROFILES -Specifies one or more profiles to be enabled on `compose up` execution. +Specifies one or more profiles to be enabled when `docker compose up` is run. + Services with matching profiles are started as well as any services for which no profile has been defined. For example, calling `docker compose up`with `COMPOSE_PROFILES=frontend` selects services with the `frontend` profile as well as any services without a profile specified. -* Default separator: specify a list of profiles using a comma as separator. +If specifying multiple profiles, use a comma as a separator. -Example: `COMPOSE_PROFILES=frontend,debug` -This example enables all services matching both the `frontend` and `debug` profiles and services without a profile. +This following example enables all services matching both the `frontend` and `debug` profiles and services without a profile. + +```console +COMPOSE_PROFILES=frontend,debug +``` See also [Using profiles with Compose](../profiles.md) and the [`--profile` command-line option](/reference/cli/docker/compose/_index.md#use---profile-to-specify-one-or-more-active-profiles). @@ -98,27 +103,36 @@ See also [Using profiles with Compose](../profiles.md) and the [`--profile` comm When enabled, Compose performs path conversion from Windows-style to Unix-style in volume definitions. -* Supported values: - * `true` or `1`, to enable, - * `false` or `0`, to disable. -* Defaults to: `0`. +- Supported values: + - `true` or `1`, to enable + - `false` or `0`, to disable +- Defaults to: `0` ### COMPOSE\_PATH\_SEPARATOR Specifies a different path separator for items listed in `COMPOSE_FILE`. -* Defaults to: - * On macOS and Linux to `:`, - * On Windows to`;`. +- Defaults to: + - On macOS and Linux to `:` + - On Windows to`;` ### COMPOSE\_IGNORE\_ORPHANS When enabled, Compose doesn't try to detect orphaned containers for the project. -* Supported values: - * `true` or `1`, to enable, - * `false` or `0`, to disable. -* Defaults to: `0`. +- Supported values: + - `true` or `1`, to enable + - `false` or `0`, to disable +- Defaults to: `0` + +### COMPOSE\_REMOVE\_ORPHANS + +When enabled, Compose automatically removes orphaned containers when updating a service or stack. Orphaned containers are those that were created by a previous configuration but are no longer defined in the current `compose.yaml` file. + +- Supported values: + - `true` or `1`, to enable automatic removal of orphaned containers + - `false` or `0`, to disable automatic removal. Compose displays a warning about orphaned containers instead. +- Defaults to: `0` ### COMPOSE\_PARALLEL\_LIMIT @@ -128,27 +142,27 @@ Specifies the maximum level of parallelism for concurrent engine calls. Specifies when to print ANSI control characters. -* Supported values: - * `auto`, Compose detects if TTY mode can be used. Otherwise, use plain text mode. - * `never`, use plain text mode. - * `always` or `0`, use TTY mode. -* Defaults to: `auto`. +- Supported values: + - `auto`, Compose detects if TTY mode can be used. Otherwise, use plain text mode + - `never`, use plain text mode + - `always` or `0`, use TTY mode +- Defaults to: `auto` ### COMPOSE\_STATUS\_STDOUT When enabled, Compose writes its internal status and progress messages to `stdout` instead of `stderr`. The default value is false to clearly separate the output streams between Compose messages and your container's logs. -* Supported values: - * `true` or `1`, to enable, - * `false` or `0`, to disable. -* Defaults to: `0`. +- Supported values: + - `true` or `1`, to enable + - `false` or `0`, to disable +- Defaults to: `0` ### COMPOSE\_ENV\_FILES Lets you specify which environment files Compose should use if `--env-file` isn't used. -When using multiple environment files, use a comma as a separator. For example, +When using multiple environment files, use a comma as a separator. For example: ```console COMPOSE_ENV_FILES=.env.envfile1, .env.envfile2 @@ -158,25 +172,25 @@ If `COMPOSE_ENV_FILES` is not set, and you don't provide `--env-file` in the CLI ### COMPOSE\_MENU -> Available in Docker Compose version [2.26.0](/manuals/compose/releases/release-notes.md#2260) and later, and Docker Desktop version 4.29 and later. +{{< introduced compose 2.26.0 "/manuals/compose/releases/release-notes.md#2260" >}} When enabled, Compose displays a navigation menu where you can choose to open the Compose stack in Docker Desktop, switch on [`watch` mode](../file-watch.md), or use [Docker Debug](/reference/cli/docker/debug.md). -* Supported values: - * `true` or `1`, to enable, - * `false` or `0`, to disable. -* Defaults to: `1` if you obtained Docker Compose through Docker Desktop, otherwise default is `0`. +- Supported values: + - `true` or `1`, to enable + - `false` or `0`, to disable +- Defaults to: `1` if you obtained Docker Compose through Docker Desktop, otherwise default is `0` ### COMPOSE\_EXPERIMENTAL -> Available in Docker Compose version [2.26.0](/manuals/compose/releases/release-notes.md#2260) and later, and Docker Desktop version 4.29 and later. +{{< introduced compose 2.26.0 "/manuals/compose/releases/release-notes.md#2260" >}} -This is an opt-out variable. When turned off it deactivates the experimental features such as the navigation menu or [Synchronized file shares](/manuals/desktop/synchronized-file-sharing.md). +This is an opt-out variable. When turned off it deactivates the experimental features such as the navigation menu or [Synchronized file shares](/manuals/desktop/features/synchronized-file-sharing.md). -* Supported values: - * `true` or `1`, to enable, - * `false` or `0`, to disable. -* Defaults to: `1`. +- Supported values: + - `true` or `1`, to enable + - `false` or `0`, to disable +- Defaults to: `1` ## Unsupported in Compose V2 diff --git a/content/manuals/compose/how-tos/environment-variables/set-environment-variables.md b/content/manuals/compose/how-tos/environment-variables/set-environment-variables.md index 55db221e9e3..929a7c3eec3 100644 --- a/content/manuals/compose/how-tos/environment-variables/set-environment-variables.md +++ b/content/manuals/compose/how-tos/environment-variables/set-environment-variables.md @@ -93,6 +93,7 @@ The paths to your `.env` file, specified in the `env_file` attribute, are relati - path: ./override.env required: false ``` +- As of Docker Compose version 2.30.0, you can use an alternative file format for the `env_file` with the `format` attribute. For more information, see [`format`](/reference/compose-file/services.md#format). - Values in your `.env` file can be overridden from the command line by using [`docker compose run -e`](#set-environment-variables-with-docker-compose-run---env). ## Set environment variables with `docker compose run --env` diff --git a/content/manuals/compose/how-tos/lifecycle.md b/content/manuals/compose/how-tos/lifecycle.md index aa332877e9e..d044f1bed13 100644 --- a/content/manuals/compose/how-tos/lifecycle.md +++ b/content/manuals/compose/how-tos/lifecycle.md @@ -6,6 +6,8 @@ desription: How to use lifecycle hooks with Docker Compose keywords: cli, compose, lifecycle, hooks reference --- +{{< introduced compose 2.30.0 "../releases/release-notes.md#2300" >}} + ## Services lifecycle hooks When Docker Compose runs a container, it uses two elements, @@ -63,3 +65,8 @@ services: pre_stop: - command: ./data_flush.sh ``` + +## Reference information + +- [`post_start`](/reference/compose-file/services.md#post_start) +- [`pre_stop`](/reference/compose-file/services.md#pre_stop) diff --git a/content/manuals/compose/how-tos/multiple-compose-files/merge.md b/content/manuals/compose/how-tos/multiple-compose-files/merge.md index da8120705b8..360d73d2475 100644 --- a/content/manuals/compose/how-tos/multiple-compose-files/merge.md +++ b/content/manuals/compose/how-tos/multiple-compose-files/merge.md @@ -10,8 +10,8 @@ aliases: Docker Compose lets you merge and override a set of Compose files together to create a composite Compose file. -By default, Compose reads two files, a `compose.yml` and an optional -`compose.override.yml` file. By convention, the `compose.yml` +By default, Compose reads two files, a `compose.yaml` and an optional +`compose.override.yaml` file. By convention, the `compose.yaml` contains your base configuration. The override file can contain configuration overrides for existing services or entirely new services. @@ -32,10 +32,10 @@ add to their predecessors. For example: ```console -$ docker compose -f compose.yml -f compose.admin.yml run backup_db +$ docker compose -f compose.yaml -f compose.admin.yaml run backup_db ``` -The `compose.yml` file might specify a `webapp` service. +The `compose.yaml` file might specify a `webapp` service. ```yaml webapp: @@ -46,7 +46,7 @@ webapp: - "/data" ``` -The `compose.admin.yml` may also specify this same service: +The `compose.admin.yaml` may also specify this same service: ```yaml webapp: @@ -226,7 +226,7 @@ For more merging rules, see [Merge and override](/reference/compose-file/merge.m ### Additional information -- Using `-f` is optional. If not provided, Compose searches the working directory and its parent directories for a `compose.yml` and a `compose.override.yml` file. You must supply at least the `compose.yml` file. If both files exist on the same directory level, Compose combines them into a single configuration. +- Using `-f` is optional. If not provided, Compose searches the working directory and its parent directories for a `compose.yaml` and a `compose.override.yaml` file. You must supply at least the `compose.yaml` file. If both files exist on the same directory level, Compose combines them into a single configuration. - You can use a `-f` with `-` (dash) as the filename to read the configuration from `stdin`. For example: ```console @@ -246,12 +246,12 @@ For more merging rules, see [Merge and override](/reference/compose-file/merge.m - You can use the `-f` flag to specify a path to a Compose file that is not located in the current directory, either from the command line or by setting up a [COMPOSE_FILE environment variable](../environment-variables/envvars.md#compose_file) in your shell or in an environment file. - For example, if you are running the [Compose Rails sample](https://github.com/docker/awesome-compose/tree/master/official-documentation-samples/rails/README.md), and have a `compose.yml` file in a directory called `sandbox/rails`. You can use a command like [docker compose pull](/reference/cli/docker/compose/pull.md) to get the postgres image for the `db` service from anywhere by using the `-f` flag as follows: `docker compose -f ~/sandbox/rails/compose.yml pull db` + For example, if you are running the [Compose Rails sample](https://github.com/docker/awesome-compose/tree/master/official-documentation-samples/rails/README.md), and have a `compose.yaml` file in a directory called `sandbox/rails`. You can use a command like [docker compose pull](/reference/cli/docker/compose/pull.md) to get the postgres image for the `db` service from anywhere by using the `-f` flag as follows: `docker compose -f ~/sandbox/rails/compose.yaml pull db` Here's the full example: ```console - $ docker compose -f ~/sandbox/rails/compose.yml pull db + $ docker compose -f ~/sandbox/rails/compose.yaml pull db Pulling db (postgres:latest)... latest: Pulling from library/postgres ef0380f84d05: Pull complete @@ -281,7 +281,7 @@ a few different files: Start with a base file that defines the canonical configuration for the services. -`compose.yml` +`compose.yaml` ```yaml services: @@ -301,7 +301,7 @@ services: In this example the development configuration exposes some ports to the host, mounts our code as a volume, and builds the web image. -`compose.override.yml` +`compose.override.yaml` ```yaml services: @@ -329,7 +329,7 @@ When you run `docker compose up` it reads the overrides automatically. To use this Compose app in a production environment, another override file is created, which might be stored in a different git repository or managed by a different team. -`compose.prod.yml` +`compose.prod.yaml` ```yaml services: @@ -347,12 +347,12 @@ services: To deploy with this production Compose file you can run ```console -$ docker compose -f compose.yml -f compose.prod.yml up -d +$ docker compose -f compose.yaml -f compose.prod.yaml up -d ``` This deploys all three services using the configuration in -`compose.yml` and `compose.prod.yml` but not the -dev configuration in `compose.override.yml`. +`compose.yaml` and `compose.prod.yaml` but not the +dev configuration in `compose.override.yaml`. For more information, see [Using Compose in production](../production.md). diff --git a/content/manuals/compose/install/_index.md b/content/manuals/compose/install/_index.md index f96f7a9f847..8e24ad484ba 100644 --- a/content/manuals/compose/install/_index.md +++ b/content/manuals/compose/install/_index.md @@ -24,9 +24,9 @@ The easiest and recommended way to get Docker Compose is to install Docker Deskt includes Docker Compose along with Docker Engine and Docker CLI which are Compose prerequisites. Docker Desktop is available on: -- [Linux](/manuals/desktop/install/linux/_index.md) -- [Mac](/manuals/desktop/install/mac-install.md) -- [Windows](/manuals/desktop/install/windows-install.md) +- [Linux](/manuals/desktop/setup/install/linux/_index.md) +- [Mac](/manuals/desktop/setup/install/mac-install.md) +- [Windows](/manuals/desktop/setup/install/windows-install.md) If you have already installed Docker Desktop, you can check which version of Compose you have by selecting **About Docker Desktop** from the Docker menu {{< inline-image src="../../desktop/images/whale-x.svg" alt="whale menu" >}}. @@ -41,22 +41,23 @@ If you have already installed Docker Desktop, you can check which version of Com > $ sudo rm /usr/local/bin/docker-compose > $ sudo ln -s /Applications/Docker.app/Contents/Resources/cli-plugins/docker-compose /usr/local/bin/docker-compose > ``` -> Or enable [Automatically check configuration](/desktop/settings/) which will detect and fix it for you. +> Or enable [Automatically check configuration](/manuals/desktop/settings-and-maintenance/settings.md) which will detect and fix it for you. -### Scenario two: Install the Compose plugin - -If you already have Docker Engine and Docker CLI installed, you can install the Compose plugin from the command line, by either: -- [Using Docker's repository](linux.md#install-using-the-repository) -- [Downloading and installing manually](linux.md#install-the-plugin-manually) +### Scenario two: Install the Docker Compose plugin > [!IMPORTANT] > ->This is only available on Linux +> This install scenario is only available on Linux. -### Scenario three: Install the Compose standalone +If you already have Docker Engine and Docker CLI installed, you can install the Docker Compose plugin from the command line, by either: +- [Using Docker's repository](linux.md#install-using-the-repository) +- [Downloading and installing manually](linux.md#install-the-plugin-manually) -You can [install the Compose standalone](standalone.md) on Linux or on Windows Server. +### Scenario three: Install the Docker Compose standalone > [!WARNING] > ->This install scenario is not recommended and is only supported for backward compatibility purposes. +> This install scenario is not recommended and is only supported for backward compatibility purposes. + +You can [install the Docker Compose standalone](standalone.md) on Linux or on Windows Server. + diff --git a/content/manuals/compose/install/linux.md b/content/manuals/compose/install/linux.md index faffb9cf25f..c8d68c2526d 100644 --- a/content/manuals/compose/install/linux.md +++ b/content/manuals/compose/install/linux.md @@ -6,26 +6,27 @@ keywords: install docker compose linux, docker compose linux, docker compose plu linux install docker-compose, linux docker compose, docker compose v2 linux, install docker compose on linux toc_max: 3 -title: Install the Compose plugin +title: Install the Docker Compose plugin +linkTitle: Plugin aliases: - /compose/compose-plugin/ - /compose/compose-linux/ +weight: 10 --- -On this page you can find instructions on how to install the Compose plugin on Linux from the command line. +This page contains instructions on how to install the Docker Compose plugin on Linux from the command line. -To install the Compose plugin on Linux, you can either: +To install the Docker Compose plugin on Linux, you can either: - [Set up Docker's repository on your Linux system](#install-using-the-repository). -- [Install Compose manually](#install-the-plugin-manually). +- [Install manually](#install-the-plugin-manually). > [!NOTE] > -> These instructions assume you already have Docker Engine and Docker CLI installed and now want to install the Compose plugin. -For Compose standalone, see [Install Compose Standalone](standalone.md). +> These instructions assume you already have Docker Engine and Docker CLI installed and now want to install the Docker Compose plugin. For the Docker Compose standalone, see [Install the Docker Compose Standalone](standalone.md). ## Install using the repository -1. Set up the repository. Find distro-specific instructions in: +1. Set up the repository. Find distribution-specific instructions in: [Ubuntu](/manuals/engine/install/ubuntu.md#install-using-the-repository) | [CentOS](/manuals/engine/install/centos.md#set-up-the-repository) | @@ -43,7 +44,7 @@ For Compose standalone, see [Install Compose Standalone](standalone.md). $ sudo apt-get update $ sudo apt-get install docker-compose-plugin ``` - * For RPM-based distros, run: + * For RPM-based distributions, run: ```console $ sudo yum update @@ -64,9 +65,9 @@ For Compose standalone, see [Install Compose Standalone](standalone.md). Where `vN.N.N` is placeholder text standing in for the latest version. -### Update Compose +### Update Docker Compose -To update the Compose plugin, run the following commands: +To update the Docker Compose plugin, run the following commands: * For Ubuntu and Debian, run: @@ -74,7 +75,7 @@ To update the Compose plugin, run the following commands: $ sudo apt-get update $ sudo apt-get install docker-compose-plugin ``` -* For RPM-based distros, run: +* For RPM-based distributions, run: ```console $ sudo yum update @@ -85,9 +86,9 @@ To update the Compose plugin, run the following commands: > [!NOTE] > -> This option requires you to manage upgrades manually. We recommend setting up Docker's repository for easier maintenance. +> This option requires you to manage upgrades manually. It is recommended that you set up Docker's repository for easier maintenance. -1. To download and install the Compose CLI plugin, run: +1. To download and install the Docker Compose CLI plugin, run: ```console $ DOCKER_CONFIG=${DOCKER_CONFIG:-$HOME/.docker} @@ -95,11 +96,11 @@ To update the Compose plugin, run the following commands: $ curl -SL https://github.com/docker/compose/releases/download/{{% param "compose_version" %}}/docker-compose-linux-x86_64 -o $DOCKER_CONFIG/cli-plugins/docker-compose ``` - This command downloads the latest release of Docker Compose (from the Compose releases repository) and installs Compose for the active user under `$HOME` directory. + This command downloads and installs the latest release of Docker Compose for the active user under `$HOME` directory. To install: - * Docker Compose for _all users_ on your system, replace `~/.docker/cli-plugins` with `/usr/local/lib/docker/cli-plugins`. - * A different version of Compose, substitute `{{% param "compose_version" %}}` with the version of Compose you want to use. + - Docker Compose for _all users_ on your system, replace `~/.docker/cli-plugins` with `/usr/local/lib/docker/cli-plugins`. + - A different version of Compose, substitute `{{% param "compose_version" %}}` with the version of Compose you want to use. - For a different architecture, substitute `x86_64` with the [architecture you want](https://github.com/docker/compose/releases). diff --git a/content/manuals/compose/install/standalone.md b/content/manuals/compose/install/standalone.md index d2908157dcc..9e7ff3a02d4 100644 --- a/content/manuals/compose/install/standalone.md +++ b/content/manuals/compose/install/standalone.md @@ -1,54 +1,66 @@ --- -title: Install Compose standalone +title: Install the Docker Compose standalone +linkTitle: Standalone description: How to install Docker Compose - Other Scenarios keywords: compose, orchestration, install, installation, docker, documentation toc_max: 3 +weight: 20 --- -On this page you can find instructions on how to install Compose standalone on Linux or Windows Server, from the command line. - -### On Linux +This page contains instructions on how to install Docker Compose standalone on Linux or Windows Server, from the command line. > [!WARNING] > -> Note that Compose standalone uses the `-compose` syntax instead of the current standard syntax `compose`. ->For example type `docker-compose up` when using Compose standalone, instead of `docker compose up`. +> The Docker Compose standalone uses the `-compose` syntax instead of the current standard syntax `compose`. +> For example, you must type `docker-compose up` when using Docker Compose standalone, instead of `docker compose up`. + +## On Linux + +1. To download and install the Docker Compose standalone, run: -1. To download and install Compose standalone, run: ```console $ curl -SL https://github.com/docker/compose/releases/download/{{% param "compose_version" %}}/docker-compose-linux-x86_64 -o /usr/local/bin/docker-compose ``` + 2. Apply executable permissions to the standalone binary in the target path for the installation. -3. Test and execute compose commands using `docker-compose`. - > [!TIP] - > - > If the command `docker-compose` fails after installation, check your path. - > You can also create a symbolic link to `/usr/bin` or any other directory in your path. - > For example: - > ```console - > $ sudo ln -s /usr/local/bin/docker-compose /usr/bin/docker-compose - > ``` + ```console + $ chmod +x /usr/local/bin/docker-compose + ``` -### On Windows Server +3. Test and execute Docker Compose commands using `docker-compose`. -Follow these instructions if you are running the Docker daemon and client directly -on Microsoft Windows Server and want to install Docker Compose. +> [!TIP] +> +> If the command `docker-compose` fails after installation, check your path. +> You can also create a symbolic link to `/usr/bin` or any other directory in your path. +> For example: +> ```console +> $ sudo ln -s /usr/local/bin/docker-compose /usr/bin/docker-compose +> ``` + +## On Windows Server + +Follow these instructions if you are [running the Docker daemon directly +on Microsoft Windows Server](/manuals/engine/install/binaries.md#install-server-and-client-binaries-on-windows) and want to install Docker Compose. 1. Run PowerShell as an administrator. - When asked if you want to allow this app to make changes to your device, select **Yes** in order to proceed with the installation. + In order to proceed with the installation, select **Yes** when asked if you want this app to make changes to your device. -2. GitHub now requires TLS1.2. In PowerShell, run the following: +2. Optional. Ensure TLS1.2 is enabled. + GitHub requires TLS1.2 fore secure connections. If you’re using an older version of Windows Server, for example 2016, or suspect that TLS1.2 is not enabled, run the following command in PowerShell: ```powershell [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 ``` -3. Run the following command to download the latest release of Compose ({{% param "compose_version" %}}): + +3. Download the latest release of Docker Compose ({{% param "compose_version" %}}). Run the following command: ```powershell Start-BitsTransfer -Source "https://github.com/docker/compose/releases/download/{{% param "compose_version" %}}/docker-compose-windows-x86_64.exe" -Destination $Env:ProgramFiles\Docker\docker-compose.exe ``` - To install a different version of Compose, substitute `{{% param "compose_version" %}}` with the version of Compose you want to use. + + To install a different version of Docker Compose, substitute `{{% param "compose_version" %}}` with the version of Compose you want to use. > [!NOTE] > diff --git a/content/manuals/compose/install/uninstall.md b/content/manuals/compose/install/uninstall.md index a57d76b1cbb..8cda6ca42bc 100644 --- a/content/manuals/compose/install/uninstall.md +++ b/content/manuals/compose/install/uninstall.md @@ -9,22 +9,22 @@ Uninstalling Docker Compose depends on the method you have used to install Docke ## Uninstalling Docker Desktop -If you want to uninstall Compose and you have installed Docker Desktop, see [Uninstall Docker Desktop](/manuals/desktop/uninstall.md). +If you want to uninstall Docker Compose and you have installed Docker Desktop, see [Uninstall Docker Desktop](/manuals/desktop/uninstall.md). > [!NOTE] > -> Unless you have other Docker instances installed on that specific environment, you would be removing Docker altogether by uninstalling the Desktop. +> Unless you have other Docker instances installed on that specific environment, you would be removing Docker altogether by uninstalling Docker Desktop. ## Uninstalling the Docker Compose CLI plugin -To remove the Compose CLI plugin, run: +To remove the Docker Compose CLI plugin, run: Ubuntu, Debian: ```console $ sudo apt-get remove docker-compose-plugin ``` -RPM-based distros: +RPM-based distributions: ```console $ sudo yum remove docker-compose-plugin @@ -32,7 +32,7 @@ RPM-based distros: ### Manually installed -If you used `curl` to install Compose CLI plugin, to uninstall it, run: +If you used `curl` to install Docker Compose CLI plugin, to uninstall it, run: ```console $ rm $DOCKER_CONFIG/cli-plugins/docker-compose @@ -40,7 +40,7 @@ If you used `curl` to install Compose CLI plugin, to uninstall it, run: ### Remove for all users -Or, if you have installed Compose for all users, run: +Or, if you have installed Docker Compose for all users, run: ```console $ rm /usr/local/lib/docker/cli-plugins/docker-compose @@ -48,15 +48,14 @@ Or, if you have installed Compose for all users, run: > [!NOTE] > -> If you get a **Permission denied** error using either of the above -> methods, you do not have the permissions allowing you to remove -> Docker Compose. To force the removal, prepend `sudo` to either of the above instructions and run it again. +> If you get a **Permission denied** error using either of the previous +> methods, you do not have the permissions needed to remove +> Docker Compose. To force the removal, prepend `sudo` to either of the previous instructions and run it again. ### Inspect the location of the Compose CLI plugin To check where Compose is installed, use: - ```console $ docker info --format '{{range .ClientInfo.Plugins}}{{if eq .Name "compose"}}{{.Path}}{{end}}{{end}}' ``` diff --git a/content/manuals/compose/intro/compose-application-model.md b/content/manuals/compose/intro/compose-application-model.md index 10662265682..510c35cb8bc 100644 --- a/content/manuals/compose/intro/compose-application-model.md +++ b/content/manuals/compose/intro/compose-application-model.md @@ -19,13 +19,13 @@ Computing components of an application are defined as [services](/reference/comp Services communicate with each other through [networks](/reference/compose-file/networks.md). In the Compose Specification, a network is a platform capability abstraction to establish an IP route between containers within services connected together. -Services store and share persistent data into [volumes](/reference/compose-file/volumes.md). The Specification describes such a persistent data as a high-level filesystem mount with global options. +Services store and share persistent data into [volumes](/reference/compose-file/volumes.md). The Specification describes such a persistent data as a high-level filesystem mount with global options. Some services require configuration data that is dependent on the runtime or platform. For this, the Specification defines a dedicated [configs](/reference/compose-file/configs.md) concept. From a service container point of view, configs are comparable to volumes, in that they are files mounted into the container. But the actual definition involves distinct platform resources and services, which are abstracted by this type. A [secret](/reference/compose-file/secrets.md) is a specific flavor of configuration data for sensitive data that should not be exposed without security considerations. Secrets are made available to services as files mounted into their containers, but the platform-specific resources to provide sensitive data are specific enough to deserve a distinct concept and definition within the Compose specification. ->**Note** +> [!NOTE] > > With volumes, configs and secrets you can have a simple declaration at the top-level and then add more platform-specific information at the service level. diff --git a/content/manuals/compose/releases/release-notes.md b/content/manuals/compose/releases/release-notes.md index ccf4f263a7a..2b4729c9fcd 100644 --- a/content/manuals/compose/releases/release-notes.md +++ b/content/manuals/compose/releases/release-notes.md @@ -13,6 +13,77 @@ aliases: For more detailed information, see the [release notes in the Compose repo](https://github.com/docker/compose/releases/). +## 2.32.0 + +{{< release-date date="2024-12-13" >}} + +### Update + +- Dependencies upgrade: bump docker + buildx to latest release +- Dependencies upgrade: bump otel dependencies to v1.28.0 and v0.53.0 +- Dependencies upgrade: bump golang.org/x/sys 0.28.0 +- Dependencies upgrade: bump golang.org/x/crypto to 0.31.0 +- Dependencies upgrade: bump google.golang.org/grpc to 1.68.1 +- Dependencies upgrade: bump golang.org/x/sync 0.10.0 +- Dependencies upgrade: bump xx to v1.6.1 + +### Bug fixes and enhancements + +- Improved support when building with [Bake](/manuals/build/bake.md) +- Added `restart` and `sync+exec` watch actions +- Compose now recreates containers when the volume or network configuration changes +- Fixed support for `mac_address` +- Fixed `pull --quiet` to only hide progress, not global status +- Fixed an issue where only the `rebuild` watch action now requires a build declaration +- Compose now logs `watch` configuration error when enabled through the Compose menu + + +## 2.31.0 + +{{< release-date date="2024-11-28" >}} + +### Update + +- Dependencies upgrade: bump compose-go to v2.4.5 +- Dependencies upgrade: bump docker engine and cli to v27.4.0-rc.2 +- Dependencies upgrade: bump buildx to v0.18.0 +- Dependencies upgrade: bump buildkit to v0.17.1 + +### Bug fixes and enhancements + +- Added the ability to use Docker Buildx Bake to build Docker Compose services +- Added `commit` command to create new images from running containers +- Fixed an issue where network changes were not detected +- Fixed an issue where containers stopped sequentially which slowed down the restart process + + +## 2.30.3 + +{{< release-date date="2024-11-07" >}} + +### Update + +- Dependencies upgrade: bump compose-go to v2.4.4 + +### Bug fixes and enhancements + +- Fixed an issue re-starting services that should not when using `--watch` +- Improve the fix of using same YAML anchor multiple times in a Compose file + + +## 2.30.2 + +{{< release-date date="2024-11-05" >}} + +### Update + +- Dependencies upgrade: bump compose-go to v2.4.3 + +### Bug fixes and enhancements + +- Fixed an issue re-creating services when updating its profiles +- Fixed a regression when using the same YAML anchor multiple times in a Compose file + ## 2.30.1 {{< release-date date="2024-10-30" >}} @@ -977,9 +1048,9 @@ For the full change log or additional information, check the [Compose repository {{< release-date date="2022-09-27" >}} -> [!NOTE] -> -> - Updates on environment file syntax & interpolation: see [compose#9879](https://github.com/docker/compose/issues/9879) +> [!NOTE] +> +> - Updates on environment file syntax & interpolation: see [compose#9879](https://github.com/docker/compose/issues/9879) > - Setting `DOCKER_HOST` via `.env` files is not supported in Compose v2 ### Updates @@ -1118,10 +1189,9 @@ For the full change log, check the [Compose repository 2.10.0 release page](http > [!IMPORTANT] > > Compose v2.9.0 contains changes to the environment variable's precedence that have since been reverted. We recommend using v2.10+ to avoid compatibility issues. -> > [!NOTE] -> +> > This release reverts the breaking changes introduced in [Compose v2.8.0](#280) by [`compose-go v1.3.0`](https://github.com/compose-spec/compose-go/releases/tag/v1.3.0). ### Updates @@ -1724,7 +1794,7 @@ For a list of PRs and issues fixed in this release, see [Compose 1.28.3](https:/ - Removed `None` entries on exec command. -- Added `distro` package to get distro information. +- Added `distribution` package to get distribution information. - Added `python-dotenv` to delegate `.env` file processing. @@ -1949,8 +2019,9 @@ This release contains minor improvements and bug fixes. - Reverted a 1.23.0 change that appended random strings to container names created by `docker-compose up`, causing addressability issues. - > [!NOTE]: Containers created by `docker-compose run` will continue to use - randomly generated names to avoid collisions during parallel runs. + > [!NOTE] + > + > Containers created by `docker-compose run` will continue to use randomly generated names to avoid collisions during parallel runs. - Fixed an issue where some `dockerfile` paths would fail unexpectedly when attempting to build on Windows. @@ -2954,7 +3025,10 @@ naming scheme accordingly before upgrading. - Containers dependencies can now be set up to wait on positive healthchecks when declared using `depends_on`. See the documentation for the updated syntax. - **Note**: This feature will not be ported to version 3 Compose files. + + > [!NOTE] + > + > This feature will not be ported to version 3 Compose files. - Added support for the `sysctls` parameter in service definitions @@ -3848,7 +3922,7 @@ The highlights: This means the GitHub repository has moved to [https://github.com/docker/fig](https://github.com/docker/fig) and our IRC channel is now #docker-fig on Freenode. - - Fig can be used with the [official Docker OS X installer](/manuals/desktop/install/mac-install.md). Boot2Docker will mount the home directory from your host machine so volumes work as expected. + - Fig can be used with the [official Docker OS X installer](/manuals/desktop/setup/install/mac-install.md). Boot2Docker will mount the home directory from your host machine so volumes work as expected. - Fig supports Docker 1.3. diff --git a/content/manuals/copilot/_index.md b/content/manuals/copilot/_index.md new file mode 100644 index 00000000000..e38267582a8 --- /dev/null +++ b/content/manuals/copilot/_index.md @@ -0,0 +1,69 @@ +--- +title: Docker for GitHub Copilot +params: + sidebar: + group: Products + badge: + color: violet + text: EA +weight: 50 +description: | + Learn how to streamline Docker-related tasks with the Docker for GitHub + Copilot extension. This integration helps you generate Docker assets, analyze + vulnerabilities, and automate containerization through GitHub Copilot Chat in + various development environments. +keywords: Docker, GitHub Copilot, extension, Visual Studio Code, chat, ai, containerization +--- + +{{% restricted title="Early Access" %}} +The Docker for GitHub Copilot extension is an [early access](/release-lifecycle#early-access-ea) product. +{{% /restricted %}} + +The [Docker for GitHub Copilot](https://github.com/marketplace/docker-for-github-copilot) +extension integrates Docker's capabilities with GitHub Copilot, providing +assistance with containerizing applications, generating Docker assets, and +analyzing project vulnerabilities. This extension helps you streamline +Docker-related tasks wherever GitHub Copilot Chat is available. + +## Key features + +Key features of the Docker for GitHub Copilot extension include: + +- Ask questions and receive responses about containerization in any context + where GitHub Copilot Chat is available, such as on GitHub.com and in Visual Studio Code. +- Automatically generate Dockerfiles, Docker Compose files, and `.dockerignore` + files for a project. +- Open pull requests with generated Docker assets directly from the chat + interface. +- Get summaries of project vulnerabilities from [Docker + Scout](/manuals/scout/_index.md) and receive next steps via the CLI. + +## Data Privacy + +The Docker agent is trained exclusively on Docker's documentation and tools to +assist with containerization and related tasks. It does not have access to your +project's data outside the context of the questions you ask. + +When using the Docker Extension for GitHub Copilot, GitHub Copilot may include +a reference to the currently open file in its request if authorized by the +user. The Docker agent can read the file to provide context-aware responses. + +If the agent is requested to check for vulnerabilities or generate +Docker-related assets, it will clone the referenced repository into in-memory +storage to perform the necessary actions. + +Source code or project metadata is never persistently stored. Questions and +answers are retained for analytics and troubleshooting. Data processed by the +Docker agent is never shared with third parties. + +## Supported languages + +The Docker Extension for GitHub Copilot supports the following programming +languages for tasks involving containerizing a project from scratch: + +- Go +- Java +- JavaScript +- Python +- Rust +- TypeScript diff --git a/content/manuals/copilot/copilot-action-prompt.png b/content/manuals/copilot/copilot-action-prompt.png deleted file mode 100644 index 0c7d7aae7a7..00000000000 Binary files a/content/manuals/copilot/copilot-action-prompt.png and /dev/null differ diff --git a/content/manuals/copilot/examples.md b/content/manuals/copilot/examples.md new file mode 100644 index 00000000000..f9573a6a1b0 --- /dev/null +++ b/content/manuals/copilot/examples.md @@ -0,0 +1,63 @@ +--- +title: Example prompts for the Docker agent +linkTitle: Example prompts +description: | + Discover example prompts to interact with the Docker agent and learn how to + automate tasks like Dockerizing projects or opening pull requests. +weight: 30 +--- + +{{% restricted title="Early Access" %}} +The Docker for GitHub Copilot extension is an [early access](/release-lifecycle#early-access-ea) product. +{{% /restricted %}} + +## Use cases + +Here are some examples of the types of questions you can ask the Docker agent: + +### Ask general Docker questions + +You can ask general question about Docker. For example: + +- `@docker what is a Dockerfile?` +- `@docker how do I build a Docker image?` +- `@docker how do I run a Docker container?` +- `@docker what does 'docker buildx imagetools inspect' do?` + +### Get help containerizing your project + +You can ask the agent to help you containerize your existing project: + +- `@docker can you help create a compose file for this project?` +- `@docker can you create a Dockerfile for this project?` + +#### Opening pull requests + +The Docker agent will analyze your project, generate the necessary files, and, +if applicable, offer to raise a pull request with the necessary Docker assets. + +Automatically opening pull requests against your repositories is only available +when the agent generates new Docker assets. + +### Analyze a project for vulnerabilities + +The agent can help you improve your security posture with [Docker +Scout](/manuals/scout/_index.md): + +- `@docker can you help me find vulnerabilities in my project?` +- `@docker does my project contain any insecure dependencies?` + +The agent will run use Docker Scout to analyze your project's dependencies, and +report whether you're vulnerable to any [known CVEs](/manuals/scout/deep-dive/advisory-db-sources.md). + +![Copilot vulnerabilities report](images/copilot-vuln-report.png?w=500px&border=1) + +## Limitations + +- The agent is currently not able to access specific files in your repository, + such as the currently-opened file in your editor, or if you pass a file + reference with your message in the chat message. + +## Feedback + +For issues or feedback, visit the [GitHub feedback repository](https://github.com/docker/copilot-issues). diff --git a/content/manuals/copilot/copilot-button.png b/content/manuals/copilot/images/copilot-button.png similarity index 100% rename from content/manuals/copilot/copilot-button.png rename to content/manuals/copilot/images/copilot-button.png diff --git a/content/manuals/copilot/images/copilot-vuln-report.png b/content/manuals/copilot/images/copilot-vuln-report.png new file mode 100644 index 00000000000..ca203875bd0 Binary files /dev/null and b/content/manuals/copilot/images/copilot-vuln-report.png differ diff --git a/content/manuals/copilot/docker-agent-copilot.png b/content/manuals/copilot/images/docker-agent-copilot.png similarity index 100% rename from content/manuals/copilot/docker-agent-copilot.png rename to content/manuals/copilot/images/docker-agent-copilot.png diff --git a/content/manuals/copilot/index.md b/content/manuals/copilot/index.md deleted file mode 100644 index b563ffac811..00000000000 --- a/content/manuals/copilot/index.md +++ /dev/null @@ -1,197 +0,0 @@ ---- -title: Docker for GitHub Copilot -linkTitle: Docker for GitHub Copilot -params: - sidebar: - badge: - color: violet - text: Early Access -weight: 100 -description: Learn how to use the Docker Extension for GitHub Copilot to streamline Docker-related tasks. -keywords: Docker, GitHub Copilot, extension, Visual Studio Code, chat, ai, containerization ---- - -{{% restricted title="Early access" %}} - -The Docker Extension for GitHub Copilot is a part of the [Limited Public Beta](https://github.blog/changelog/2024-05-21-copilot-extensions-now-in-limited-public-beta/) -for GitHub Copilot Extensions. - -To get access, [sign up for the Copilot Extensions waitlist](https://github.com/github-copilot/copilot_extensions_waitlist_signup). - -{{% /restricted %}} - -The Docker Extension for GitHub Copilot integrates Docker's capabilities with -GitHub Copilot, providing assistance with containerizing applications and -generating Docker assets. This extension helps you streamline Docker-related -tasks wherever GitHub Copilot Chat is available. - -The key features are: - -- Ask questions and receive responses about containerization in any context - when GitHub Copilot Chat is available, such as on GitHub.com and in Visual Studio Code. -- Automatically generate Dockerfiles, Docker Compose files, and .dockerignore - files for a project. -- Open pull requests with generated Docker assets directly from the chat - interface. -- Get summaries of project vulnerabilities from Docker Scout and receive next - steps via CLI. - -## Data Privacy - -The Docker agent is trained exclusively on Docker's documentation and tools to -assist with containerization and related tasks. It does not have access to your -project's data outside the context of the questions you ask. - -When using the Docker Extension for GitHub Copilot, GitHub Copilot may include -a reference to the currently open file in its request if authorized by the -user. The Docker agent can read the file to provide context-aware responses. - -If the agent is requested to check for vulnerabilities or generate -Docker-related assets, it will clone the referenced repository into in-memory -storage to perform the necessary actions. - -Source code, questions, and responses are not persistently stored. The Docker -agent processes data only to provide responses and discards it immediately -afterward. - -## Supported languages - -The Docker Extension for GitHub Copilot supports the following -programming languages: - -- Dockerfile -- Go -- Java -- JavaScript -- Python -- Rust -- TypeScript - -## Get Started - -Here's how to get started with the Docker Extension for GitHub Copilot. - -### Prerequisites - -Before you start, ensure that: - -- You have been granted access to GitHub's [limited public beta program](https://github.blog/changelog/2024-05-21-copilot-extensions-now-in-limited-public-beta/). -- You're signed in to your GitHub account on GitHub.com. - -### Install the extension for your organization - -1. Go to the [Docker for GitHub Copilot](https://github.com/marketplace/docker-for-github-copilot) - app in the GitHub Marketplace. - -2. Select the **Add** button at the top of the page. - -3. Under **Pricing and setup**, select the organization that you want to - install the extension for and select **Install it for free**. - -4. Select the **Complete order and begin installation** button. - -5. Select the repositories where you want to use the Docker Extension for - GitHub Copilot and finish with **Install**. - -> [!NOTE] -> Before you can use Copilot Extensions in your organization, you need to -> enable the Copilot Extensions policy. For more information, see -> [Setting a policy for GitHub Copilot Extensions in your organization](https://docs.github.com/en/copilot/managing-copilot/managing-github-copilot-in-your-organization/setting-policies-for-copilot-in-your-organization/managing-policies-for-copilot-in-your-organization#setting-a-policy-for-github-copilot-extensions-in-your-organization). - -### Set up Copilot Chat - -Once you've installed the Docker Extension for GitHub Copilot and enabled the -Copilot Extensions policy, you can use the extension in your editor or IDE, or -on GitHub.com. - -{{< tabs >}} -{{< tab name="Editor or IDE" >}} - -For instructions on how to use the Docker Extension for GitHub Copilot in -your editor, see: - -- [Visual Studio Code](https://docs.github.com/en/copilot/github-copilot-chat/copilot-chat-in-ides/using-github-copilot-chat-in-your-ide?tool=vscode) -- [Visual Studio](https://docs.github.com/en/copilot/github-copilot-chat/copilot-chat-in-ides/using-github-copilot-chat-in-your-ide?tool=visualstudio) -- [Codespaces](https://docs.github.com/en/codespaces/reference/using-github-copilot-in-github-codespaces) - -{{< /tab >}} -{{< tab name="GitHub.com" >}} - -No setup is needed for the Docker Extension for GitHub Copilot on GitHub.com. -Simply go to any repository and start using the chat interface, -see [Using the extension](#using-the-extension). - -{{< /tab >}} -{{< /tabs >}} - -You can verify that the extension has been properly installed by typing -`@docker` in the Copilot Chat window. As you type, you should see the Docker -agent appear in the chat interface. - -![Docker agent in chat](/copilot/docker-agent-copilot.png) - -## Using the extension - -The Docker Extension for GitHub Copilot provides a chat interface that you can -use to interact with the Docker agent. You can ask questions and get help -Dockerizing your project. - -The Docker agent is trained to understand Docker-related questions, and provide -guidance on Dockerfiles, Docker Compose files, and other Docker assets. - -### Editor - -To use the extension in your editor or IDE: - -1. Open your project in your editor. -2. Open the Copilot chat interface. -3. Interact with the Docker agent using the `/docker` or `@docker`, followed by your question. - -### GitHub.com - -To use the extension in the GitHub web interface: - -1. Go to [github.com](https://github.com/) and sign in to your account. -2. Go to any repository. -3. Select the Copilot logo in the site menu to open the chat interface. - - ![Copilot chat button](/copilot/copilot-button.png?w=400px) - -4. Interact with the Docker agent by tagging `@docker`. - -## Example prompts - -Here are some examples of the types of questions you can ask the Docker agent: - -### Ask general Docker questions - -You can ask general question about Docker. For example: - -- `@docker what is a Dockerfile` -- `@docker how do I build a Docker image` -- `@docker how do I run a Docker container` - -### Ask questions about your project - -You can ask questions about your project, such as: - -- `@docker what is the best way to Dockerize this project` -- `@docker can you help me find vulnerabilities in my project?` - -The Docker agent will analyze your project, generate the necessary files, and, -if applicable, offer to raise a pull request with the necessary Docker assets. - -## Performing actions on your behalf - -Before the agent performs any actions on your behalf, such as opening a pull -request for you, you're prompted to provide your consent to allow the -operation. You can always roll back or back out of the changes. - -![Copilot action prompt](/copilot/copilot-action-prompt.png?w=400px) - -In the event that the agent encounters an error, for example during PR -creation, it handles timeouts and lack of responses gracefully. - -## Feedback - -For issues or feedback, visit the [GitHub feedback repository](https://github.com/docker/copilot-issues). diff --git a/content/manuals/copilot/install.md b/content/manuals/copilot/install.md new file mode 100644 index 00000000000..35756b6cfd2 --- /dev/null +++ b/content/manuals/copilot/install.md @@ -0,0 +1,44 @@ +--- +title: Install the extension for your organization +linkTitle: Install +description: | + Learn how to install the Docker for GitHub Copilot extension for your + organization and manage relevant policies to enable seamless integration. +weight: 10 +--- + +{{% restricted title="Early Access" %}} +The Docker for GitHub Copilot extension is an [early access](/release-lifecycle#early-access-ea) product. +{{% /restricted %}} + +To use the Docker for GitHub copilot extension, you first need to +[install](#install) the extension for your organization, and +[manage](#manage-policies) policies for Copilot in your organization. + +## Prerequisites + +Before you start, ensure that you're signed in to your GitHub account on +GitHub.com. + +## Install + +To install the Docker for GitHub Copilot extension for your GitHub organization: + +1. Go to the [Docker for GitHub Copilot](https://github.com/marketplace/docker-for-github-copilot) + app in the GitHub Marketplace. + +2. Select the **Add** button at the top of the page. + +3. Under **Pricing and setup**, select the organization that you want to + install the extension for and select **Install it for free**. + +4. Select the **Complete order and begin installation** button. + +5. Select the repositories where you want to use the Docker Extension for + GitHub Copilot and finish with **Install**. + +## Manage policies + +If you're enabling the extension for a GitHub organization, you also +need to enable the Copilot Extensions policy. For instructions, see +[Setting a policy for GitHub Copilot Extensions in your organization](https://docs.github.com/en/copilot/managing-copilot/managing-github-copilot-in-your-organization/setting-policies-for-copilot-in-your-organization/managing-policies-for-copilot-in-your-organization#setting-a-policy-for-github-copilot-extensions-in-your-organization). diff --git a/content/manuals/copilot/usage.md b/content/manuals/copilot/usage.md new file mode 100644 index 00000000000..92cba9c494a --- /dev/null +++ b/content/manuals/copilot/usage.md @@ -0,0 +1,65 @@ +--- +title: Using the Docker for GitHub Copilot extension +linkTitle: Usage +description: | + Learn how to use the Docker for GitHub Copilot extension to interact with the + Docker agent, get help Dockerizing projects, and ask Docker-related questions + directly from your IDE or GitHub.com. +weight: 20 +--- + +{{% restricted title="Early Access" %}} +The Docker for GitHub Copilot extension is an [early access](/release-lifecycle#early-access-ea) product. +{{% /restricted %}} + +The Docker Extension for GitHub Copilot provides a chat interface that you can +use to interact with the Docker agent. You can ask questions and get help +Dockerizing your project. + +The Docker agent is trained to understand Docker-related questions, and provide +guidance on Dockerfiles, Docker Compose files, and other Docker assets. + +## Setup + +Before you can start interacting with the Docker agent, make sure you've +[installed](./install.md) the extension for your organization. + +### Enable GitHub Copilot chat in your editor or IDE + +For instructions on how to use the Docker Extension for GitHub Copilot in +your editor, see: + +- [Visual Studio Code](https://docs.github.com/en/copilot/github-copilot-chat/copilot-chat-in-ides/using-github-copilot-chat-in-your-ide?tool=vscode) +- [Visual Studio](https://docs.github.com/en/copilot/github-copilot-chat/copilot-chat-in-ides/using-github-copilot-chat-in-your-ide?tool=visualstudio) +- [Codespaces](https://docs.github.com/en/codespaces/reference/using-github-copilot-in-github-codespaces) + +### Verify the setup + +You can verify that the extension has been properly installed by typing +`@docker` in the Copilot Chat window. As you type, you should see the Docker +agent appear in the chat interface. + +![Docker agent in chat](images/docker-agent-copilot.png) + +The first time you interact with the agent, you're prompted to sign in and +authorize the Copilot extension with your Docker account. + +## Asking Docker questions in your editor + +To interact with the Docker agent from within your editor or IDE: + +1. Open your project in your editor. +2. Open the Copilot chat interface. +3. Interact with the Docker agent by tagging `@docker`, followed by your question. + +## Asking Docker questions on GitHub.com + +To interact with the Docker agent from the GitHub web interface: + +1. Go to [github.com](https://github.com/) and sign in to your account. +2. Go to any repository. +3. Select the Copilot logo in the site menu, or select the floating Copilot widget, to open the chat interface. + + ![Copilot chat button](images/copilot-button.png?w=400px) + +4. Interact with the Docker agent by tagging `@docker`, followed by your question. diff --git a/content/manuals/desktop/_index.md b/content/manuals/desktop/_index.md index cb1957d25e6..17c87b9cfcd 100644 --- a/content/manuals/desktop/_index.md +++ b/content/manuals/desktop/_index.md @@ -1,17 +1,19 @@ --- -title: Overview of Docker Desktop -linkTitle: Docker Desktop -weight: 100 +title: Docker Desktop +weight: 10 description: Explore Docker Desktop, what it has to offer, and its key features. Take the next step by downloading or find additional resources keywords: how to use docker desktop, what is docker desktop used for, what does docker desktop do, using docker desktop +params: + sidebar: + group: Products grid: - title: Install Docker Desktop description: | Install Docker Desktop on - [Mac](/desktop/install/mac-install/), - [Windows](/desktop/install/windows-install/), or - [Linux](/desktop/install/linux/). + [Mac](/desktop/setup/install/mac-install/), + [Windows](/desktop/setup/install/windows-install/), or + [Linux](/desktop/setup/install/linux/). icon: download - title: Explore Docker Desktop description: Navigate Docker Desktop and learn about its key features. @@ -24,16 +26,16 @@ grid: - title: Browse common FAQs description: Explore general FAQs or FAQs for specific platforms. icon: help - link: /desktop/faqs/ + link: /desktop/troubleshoot-and-support/faqs/general/ - title: Find additional resources description: | Find information on networking features, deploying on Kubernetes, and more. icon: category - link: /desktop/kubernetes/ + link: /desktop/features/kubernetes/ - title: Give feedback description: Provide feedback on Docker Desktop or Docker Desktop features. icon: sms - link: /desktop/feedback/ + link: /desktop/troubleshoot-and-support/feedback/ aliases: - /desktop/opensource/ - /docker-for-mac/dashboard/ diff --git a/content/manuals/desktop/features/_index.md b/content/manuals/desktop/features/_index.md new file mode 100644 index 00000000000..b62f571d019 --- /dev/null +++ b/content/manuals/desktop/features/_index.md @@ -0,0 +1,6 @@ +--- +build: + render: never +title: Features and capabilities +weight: 30 +--- \ No newline at end of file diff --git a/content/manuals/desktop/containerd.md b/content/manuals/desktop/features/containerd.md similarity index 98% rename from content/manuals/desktop/containerd.md rename to content/manuals/desktop/features/containerd.md index 58c645431f9..e78c4448323 100644 --- a/content/manuals/desktop/containerd.md +++ b/content/manuals/desktop/features/containerd.md @@ -1,9 +1,11 @@ --- title: containerd image store -weight: 50 +weight: 10 description: How to activate the containerd integration feature in Docker Desktop keywords: Docker, containerd, engine, image store, lazy-pull toc_max: 3 +aliases: +- /desktop/containerd/ --- This page provides information about the ongoing integration of `containerd` for diff --git a/content/manuals/desktop/features/desktop-cli.md b/content/manuals/desktop/features/desktop-cli.md new file mode 100644 index 00000000000..1c6d428ac47 --- /dev/null +++ b/content/manuals/desktop/features/desktop-cli.md @@ -0,0 +1,42 @@ +--- +title: Using the Docker Desktop CLI +linkTitle: Docker Desktop CLI +weight: 120 +description: How to use the Docker Desktop CLI +keywords: cli, docker desktop, macos, windows, linux +params: + sidebar: + badge: + color: green + text: New +--- + +{{% experimental title="Beta" %}} +Docker Desktop CLI is currently in [Beta](../../release-lifecycle.md#beta). +{{% /experimental %}} + +The Docker Desktop CLI lets you perform key operations such as starting, stopping, restarting, and checking the status of Docker Desktop directly from the command line. It is available with Docker Desktop version 4.37 and later. + +The Docker Desktop CLI provides: + +- Enhanced automation and CI/CD integration: Perform Docker Desktop operations directly in CI/CD pipelines for better workflow automation. +- An improved developer experience: Restart, quit, or reset Docker Desktop from the command line, reducing dependency on the Docker Desktop Dashboard and improving flexibility and efficiency. + +## Usage + +```console +docker desktop COMMAND [OPTIONS] +``` + +## Commands + +| Command | Description | +|:---------------------|:-----------------------------------------| +| `start` | Starts Docker Desktop | +| `stop` | Stops Docker Desktop | +| `restart` | Restarts Docker Desktop | +| `status` | Displays whether Docker Desktop is running or stopped. | +| `engine ls` | Lists available engines (Windows only) | +| `engine use` | Switch between Linux and Windows containers (Windows only) | + +For more details on each command, see the [Docker Desktop CLI reference](/reference/cli/docker/desktop/_index.md). diff --git a/content/manuals/desktop/dev-environments/_index.md b/content/manuals/desktop/features/dev-environments/_index.md similarity index 95% rename from content/manuals/desktop/dev-environments/_index.md rename to content/manuals/desktop/features/dev-environments/_index.md index c13a82948ee..85cdf928583 100644 --- a/content/manuals/desktop/dev-environments/_index.md +++ b/content/manuals/desktop/features/dev-environments/_index.md @@ -4,12 +4,14 @@ keywords: Dev Environments, share, local, Compose title: Overview of Dev Environments linkTitle: Dev Environments (Beta) weight: 40 +aliases: +- /desktop/dev-environments/ --- {{< include "dev-envs-changing.md" >}} {{% experimental title="Beta" %}} -The Dev Environments feature is currently in [Beta](../../release-lifecycle.md#beta). +The Dev Environments feature is currently in [Beta](/manuals/release-lifecycle.md#beta). {{% /experimental %}} Dev Environments let you create a configurable developer environment with all the code and tools you need to quickly get up and running. diff --git a/content/manuals/desktop/dev-environments/create-dev-env.md b/content/manuals/desktop/features/dev-environments/create-dev-env.md similarity index 99% rename from content/manuals/desktop/dev-environments/create-dev-env.md rename to content/manuals/desktop/features/dev-environments/create-dev-env.md index f1676b32299..c0a2bc32446 100644 --- a/content/manuals/desktop/dev-environments/create-dev-env.md +++ b/content/manuals/desktop/features/dev-environments/create-dev-env.md @@ -4,6 +4,7 @@ keywords: Dev Environments, share, Docker Desktop, Compose, launch title: Launch a dev environment aliases: - /desktop/dev-environments/create-compose-dev-env/ +- /desktop/dev-environments/create-dev-env/ weight: 10 --- diff --git a/content/manuals/desktop/dev-environments/dev-cli.md b/content/manuals/desktop/features/dev-environments/dev-cli.md similarity index 95% rename from content/manuals/desktop/dev-environments/dev-cli.md rename to content/manuals/desktop/features/dev-environments/dev-cli.md index 68233d07be9..c7d51bb0bf9 100644 --- a/content/manuals/desktop/dev-environments/dev-cli.md +++ b/content/manuals/desktop/features/dev-environments/dev-cli.md @@ -2,13 +2,15 @@ description: Set up a dev Environments keywords: Dev Environments, share, docker dev, Docker Desktop title: Use the docker dev CLI plugin +aliases: +- /desktop/dev-environments/dev-cli/ --- {{< 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. -It is available with [Docker Desktop 4.13.0 and later](../release-notes.md). +It is available with [Docker Desktop 4.13.0 and later](/manuals/desktop/release-notes.md). ### Usage diff --git a/content/manuals/desktop/dev-environments/set-up.md b/content/manuals/desktop/features/dev-environments/set-up.md similarity index 98% rename from content/manuals/desktop/dev-environments/set-up.md rename to content/manuals/desktop/features/dev-environments/set-up.md index e711b219d72..7c1fd89982d 100644 --- a/content/manuals/desktop/dev-environments/set-up.md +++ b/content/manuals/desktop/features/dev-environments/set-up.md @@ -3,6 +3,8 @@ description: Set up a dev Environments keywords: Dev Environments, share, set up, Compose, Docker Desktop title: Set up a dev environment weight: 20 +aliases: +- /desktop/dev-environments/set-up/ --- {{< include "dev-envs-changing.md" >}} diff --git a/content/manuals/desktop/dev-environments/share.md b/content/manuals/desktop/features/dev-environments/share.md similarity index 97% rename from content/manuals/desktop/dev-environments/share.md rename to content/manuals/desktop/features/dev-environments/share.md index e36659c1cf0..79f8703def3 100644 --- a/content/manuals/desktop/dev-environments/share.md +++ b/content/manuals/desktop/features/dev-environments/share.md @@ -3,6 +3,8 @@ description: Dev Environments keywords: Dev Environments, share, Docker Desktop title: Distribute your dev environment weight: 30 +aliases: +- /desktop/dev-environments/share/ --- {{< include "dev-envs-changing.md" >}} diff --git a/content/manuals/desktop/features/gordon.md b/content/manuals/desktop/features/gordon.md new file mode 100644 index 00000000000..469a9ac6ee6 --- /dev/null +++ b/content/manuals/desktop/features/gordon.md @@ -0,0 +1,292 @@ +--- +title: Ask Gordon +description: Learn how to streamline your workflow with Docker's AI-powered assistant. +weight: 10 +params: + sidebar: + badge: + color: blue + text: Beta +--- + +{{% restricted title=Beta %}} +Ask Gordon is a [Beta](/manuals/release-lifecycle.md) feature, and only members +of the Ask Gordon beta program can access it. Features, user interface, and +behavior are subject to change in future releases. + +{{< button text="Apply for access" url="https://docker.qualtrics.com/jfe/form/SV_dmVHFjQ4fZlrEOy" >}} +{{% /restricted %}} + +Ask Gordon is your personal AI assistant embedded in Docker Desktop and the +Docker CLI. It's designed to streamline your workflow and help you make the +most of the Docker ecosystem. + +## What is Ask Gordon? + +Ask Gordon is a suite of AI-powered capabilities integrated into Docker's +tools. These features, currently in Beta, are not enabled by default, and are +not production-ready. You may also encounter the term "Docker AI" as a broader +reference to this technology. + +The goal of Ask Gordon is to make Docker's tools for managing images and +containers more intuitive and accessible. It provides contextual assistance +tailored to your local environment, including Dockerfiles, containers, and +applications. + +Ask Gordon integrates directly with Docker's tools to help you perform specific +tasks. It understands your local setup, such as your local source code and +images. For example, you can ask Gordon to help you identify vulnerabilities in +your project or how to optimize a Dockerfile in your local repository. This +tight integration ensures responses are practical and actionable. + +> [!NOTE] +> Ask Gordon is powered by Large Language Models (LLMs). Like all LLM-based +> tools, its responses may sometimes be inaccurate. Always verify the +> information provided. + +### What data does Gordon access? + +When you use Ask Gordon, the data it accesses depends on the context of your +query: + +- Local files: If you use the `docker ai` command, Ask Gordon can access + files and directories in the current working directory where the command is + executed. In Docker Desktop, if you ask about a specific file or directory in + the **Ask Gordon** view, you'll be prompted to select the relevant context. +- Local images: Gordon integrates with Docker Desktop and can view all images + in your local image store. This includes images you've built or pulled from a + registry. + +To provide accurate responses, Ask Gordon may send relevant files, directories, +or image metadata to the Gordon backend along with your query. This data +transfer occurs over the network but is never stored persistently or shared +with third parties. It is used exclusively to process your request and +formulate a response. + +All data transferred is encrypted in transit. + +### How your data is collected and used + +Docker collects anonymized data from your interactions with Ask Gordon to +enhance the service. This includes the following: + +- Your queries: Questions you ask Gordon. +- Responses: Answers provided by Gordon. +- Feedback: Thumbs-up and thumbs-down ratings. + +To ensure privacy and security: + +- Data is anonymized and cannot be traced back to you or your account. +- Docker does not use this data to train AI models or share it with third + parties. + +By using Ask Gordon, you help improve Docker AI's reliability and accuracy, +making it more effective for all users. + +If you have concerns about data collection or usage, you can +[disable](#disable-ask-gordon) the feature at any time. + +## Setup + +To use this feature, you must have: + +- [Access to the Ask Gordon beta program](https://docker.qualtrics.com/jfe/form/SV_dmVHFjQ4fZlrEOy). + +- Docker Desktop version 4.37 or later. + +Ask Gordon is not enabled by default. After having received access to the beta +program, you must enable the feature: + +1. [Sign in](#sign-in) to your Docker account. +2. [Enable the feature](#enable-the-feature) in the Docker Desktop settings. +3. [Accept the terms of service](#accept-the-terms-of-service). + +### Sign in + +1. Open Docker Desktop. +2. Select the **Sign in** button. +3. Complete the sign-in process in your web browser. + +### Enable the feature + +After signing in to your Docker Account, enable the Docker AI feature: + +1. Open the **Settings** view in Docker Desktop. +2. Navigate to **Features in development**. +3. Check the **Enable Docker AI** checkbox. +4. Select **Apply & restart**. + +### Accept the terms of service + +To start using Docker AI, you need to accept the terms of service. You can do +this in one of two ways: + +- Open the **Ask Gordon** view in Docker Desktop and ask a question. +- Use the `docker ai` CLI command to issue a query. + +The first time you interact with Docker AI, you'll see a prompt to accept the +terms of service. For example: + +```console +$ docker ai what can you do? + + Before using Gordon, please accept the terms of service +``` + +After accepting the terms, you can begin using Ask Gordon. + +## Using Ask Gordon + +The primary interfaces to Docker's AI capabilities are through the **Ask +Gordon** view in Docker Desktop, or if you prefer to use the CLI: the `docker +ai` CLI command. + +If you've used an AI chatbot before, these interfaces will be pretty familiar +to you. You can chat with the Docker AI to get help with your Docker tasks. + +### Contextual help + +Once you've enabled the Docker AI features, you'll also find references to +**Ask Gordon** in various other places throughout the Docker Desktop user +interface. Whenever you encounter a button with the "sparkles" (✨) icon in the +user interface, you can use the button to get contextual support from Ask +Gordon. + +## Example workflows + +Ask Gordon is a general-purpose AI assistant created to help you with all your +Docker-related tasks and workflows. If you need some inspiration, here are a +few ways things you can try: + +- [Troubleshoot a crashed container](#troubleshoot-a-crashed-container) +- [Get help with running a container](#get-help-with-running-a-container) +- [Improve a Dockerfile](#improve-a-dockerfile) + +For more examples, try asking Gordon directly. For example: + +```console +$ docker ai "What can you do?" +``` + +### Troubleshoot a crashed container + +If you try to start a container with an invalid configuration or command, you +can use Ask Gordon to troubleshoot the error. For example, try starting a +Postgres container without specifying a database password: + +```console +$ docker run postgres +Error: Database is uninitialized and superuser password is not specified. + You must specify POSTGRES_PASSWORD to a non-empty value for the + superuser. For example, "-e POSTGRES_PASSWORD=password" on "docker run". + + You may also use "POSTGRES_HOST_AUTH_METHOD=trust" to allow all + connections without a password. This is *not* recommended. + + See PostgreSQL documentation about "trust": + https://www.postgresql.org/docs/current/auth-trust.html +``` + +In the **Containers** view in Docker Desktop, select the ✨ icon next to the +container's name, or inspect the container and open the **Ask Gordon** tab. + +### Get help with running a container + +If you want to run a specific image but you're not sure how, Gordon might be +able to help you get set up: + +1. Pull an image from Docker Hub (for example, `postgres`). +2. Open the **Images** view in Docker Desktop and select the image. +3. Select the **Run** button. + +In the _Run a new container_ dialog that opens, you should see a message about +**Ask Gordon**. + +![Ask Gordon hint in Docker Desktop](../images/gordon-run-ctr.png) + +The linked text in the hint is a suggested prompt to start a conversation with +Ask Gordon. + +### Improve a Dockerfile + +Gordon can analyze your Dockerfile and suggest improvements. To have Gordon +evaluate your Dockerfile using the `docker ai` command: + +1. Navigate to your project directory: + + ```console + $ cd path/to/my/project + ``` + +2. Use the `docker ai` command to rate your Dockerfile: + + ```console + $ docker ai rate my Dockerfile + ``` + +Gordon will analyze your Dockerfile and identify opportunities for improvement +across several dimensions: + +- Build cache optimization +- Security +- Image size efficiency +- Best practices compliance +- Maintainability +- Reproducibility +- Portability +- Resource efficiency + +## Disable Ask Gordon + +If you've enabled Ask Gordon and you want to disable it again: + +1. Open the **Settings** view in Docker Desktop. +2. Navigate to **Features in development**. +3. Clear the **Enable Docker AI** checkbox. +4. Select **Apply & restart**. + +If you want to disable Ask Gordon for your entire Docker organization, using +[Settings Management](/manuals/security/for-admins/hardened-desktop/settings-management/_index.md), +add the following property to your `admin-settings.json` file: + +```json +{ + "enableDockerAI": { + "value": false, + "locked": true + } +} +``` + +Alternatively, you can disable all Beta features by setting `allowBetaFeatures` to false: + +```json +{ + "allowBetaFeatures": { + "value": false, + "locked": true + } +} +``` + +## Feedback + + + +We value your input on Ask Gordon and encourage you to share your experience. +Your feedback helps us improve and refine Ask Gordon for all users. If you +encounter issues, have suggestions, or simply want to share what you like, +here's how you can get in touch: + +- Thumbs-up and thumbs-down buttons + + Rate Ask Gordon's responses using the thumbs-up or thumbs-down buttons in the + response. + +- Feedback survey + + You can access the Ask Gordon survey by following the _Give feedback_ link in + the **Ask Gordon** view in Docker Desktop, or from the CLI by running the + `docker ai feedback` command. + +Thank you for helping us improve Ask Gordon. diff --git a/content/manuals/desktop/gpu.md b/content/manuals/desktop/features/gpu.md similarity index 98% rename from content/manuals/desktop/gpu.md rename to content/manuals/desktop/features/gpu.md index fe3e2358aa0..494d178291d 100644 --- a/content/manuals/desktop/gpu.md +++ b/content/manuals/desktop/features/gpu.md @@ -1,10 +1,12 @@ --- title: GPU support in Docker Desktop linkTitle: GPU support -weight: 90 +weight: 80 description: How to use GPU in Docker Desktop keywords: gpu, gpu support, nvidia, wsl2, docker desktop, windows toc_max: 3 +aliases: +- /desktop/gpu/ --- > [!NOTE] diff --git a/content/manuals/desktop/kubernetes.md b/content/manuals/desktop/features/kubernetes.md similarity index 99% rename from content/manuals/desktop/kubernetes.md rename to content/manuals/desktop/features/kubernetes.md index 7cf2c7121c1..5742400aa03 100644 --- a/content/manuals/desktop/kubernetes.md +++ b/content/manuals/desktop/features/kubernetes.md @@ -5,7 +5,8 @@ title: Deploy on Kubernetes with Docker Desktop aliases: - /docker-for-windows/kubernetes/ - /docker-for-mac/kubernetes/ -weight: 110 +- /desktop/kubernetes/ +weight: 60 --- Docker Desktop includes a standalone Kubernetes server and client, diff --git a/content/manuals/desktop/networking.md b/content/manuals/desktop/features/networking.md similarity index 97% rename from content/manuals/desktop/networking.md rename to content/manuals/desktop/features/networking.md index f743884951d..71156eebdf0 100644 --- a/content/manuals/desktop/networking.md +++ b/content/manuals/desktop/features/networking.md @@ -10,7 +10,8 @@ aliases: - /docker-for-win/networking/ - /docker-for-windows/networking/ - /desktop/windows/networking/ -weight: 120 +- /desktop/networking/ +weight: 50 --- Docker Desktop provides several networking features to make it easier to @@ -46,11 +47,11 @@ syntax for `-p` is `HOST_PORT:CLIENT_PORT`. ### HTTP/HTTPS Proxy support -See [Proxies](/manuals/desktop/settings.md#proxies) +See [Proxies](/manuals/desktop/settings-and-maintenance/settings.md#proxies) ### SOCKS5 proxy support -{{< introduced desktop 4.28.0 "release-notes.md#4280" >}} +{{< introduced desktop 4.28.0 "../release-notes.md#4280" >}} > [!NOTE] > diff --git a/content/manuals/desktop/synchronized-file-sharing.md b/content/manuals/desktop/features/synchronized-file-sharing.md similarity index 97% rename from content/manuals/desktop/synchronized-file-sharing.md rename to content/manuals/desktop/features/synchronized-file-sharing.md index 94dbb573078..789a9c159f9 100644 --- a/content/manuals/desktop/synchronized-file-sharing.md +++ b/content/manuals/desktop/features/synchronized-file-sharing.md @@ -1,8 +1,10 @@ --- title: Synchronized file shares -weight: 70 +weight: 30 description: Get started with Synchronized file shares on Docker Desktop. keyword: mutagen, file sharing, docker desktop, bind mounts +aliases: +- /desktop/synchronized-file-sharing/ --- > [!NOTE] @@ -11,7 +13,7 @@ keyword: mutagen, file sharing, docker desktop, bind mounts Synchronized file shares is an alternative file sharing mechanism that provides fast and flexible host-to-VM file sharing, enhancing bind mount performance through the use of synchronized filesystem caches. -![Image of Synchronized file shares pane](images/synched-file-shares.webp) +![Image of Synchronized file shares pane](../images/synched-file-shares.webp) ## Who is it for? diff --git a/content/manuals/desktop/features/usbip.md b/content/manuals/desktop/features/usbip.md new file mode 100644 index 00000000000..12483da06bf --- /dev/null +++ b/content/manuals/desktop/features/usbip.md @@ -0,0 +1,145 @@ +--- +title: Using USB/IP with Docker Desktop +linkTitle: USB/IP support +weight: 100 +description: How to use USB/IP in Docker Desktop +keywords: usb, usbip, docker desktop, macos, windows, linux +toc_max: 3 +aliases: +- /desktop/usbip/ +params: + sidebar: + badge: + color: green + text: New +--- + +{{< introduced desktop 4.35.0 "../../desktop/release-notes.md#4350" >}} + +> [!NOTE] +> +> Available on Docker Desktop for Mac, Linux, and Windows with the Hyper-V backend. + +USB/IP enables you to share USB devices over the network, which can then be accessed from within Docker containers. This page focuses on sharing USB devices connected to the machine you run Docker Desktop on. You can repeat the following process to attach and use additional USB devices as needed. + +> [!NOTE] +> +> The Docker Desktop VM kernel image comes pre-configured with drivers for many common USB devices, but Docker can't guarantee every possible USB device will work with this setup. + +## Setup and use + +### Step one: Run a USB/IP server + +To use USB/IP, you need to run a USB/IP server. For this guide, the implementation provided by [jiegec/usbip](https://github.com/jiegec/usbip) will be used. + +1. Clone the repository. + + ```console + $ git clone https://github.com/jiegec/usbip + $ cd usbip + ``` + +2. Run the emulated Human Interface Device (HID) device example. + + ```console + $ env RUST_LOG=info cargo run --example hid_keyboard + ``` + +### Step two: Start a privileged Docker container + +To attach the USB device, start a privileged Docker container with the PID namespace set to `host`: + +```console +$ docker run --rm -it --privileged --pid=host alpine +``` + +### Step three: Enter the mount namespace of PID 1 + +Inside the container, enter the mount namespace of the `init` process to gain access to the pre-installed USB/IP tools: + +```console +$ nsenter -t 1 -m +``` + +### Step four: Use USB/IP tools + +Now you can use the USB/IP tools as you would on any other system: + +#### List USB devices + +To list exportable USB devices from the host: + +```console +$ usbip list -r host.docker.internal +``` + +Expected output: + +```console +Exportable USB devices +====================== + - host.docker.internal + 0-0-0: unknown vendor : unknown product (0000:0000) + : /sys/bus/0/0/0 + : (Defined at Interface level) (00/00/00) + : 0 - unknown class / unknown subclass / unknown protocol (03/00/00) +``` + +#### Attach a USB device + +To attach a specific USB device, or the emulated keyboard in this case: + +```console +$ usbip attach -r host.docker.internal -d 0-0-0 +``` + +#### Verify device attachment + +After attaching the emulated keyboard, check the `/dev/input` directory for the device node: + +```console +$ ls /dev/input/ +``` + +Example output: + +```console +event0 mice +``` + +### Step five: Use the attached device in another container + +While the initial container remains running to keep the USB device operational, you can access the attached device from another container. For example: + +1. Start a new container with the attached device. + + ```console + $ docker run --rm -it --device "/dev/input/event0" alpine + ``` + +2. Install a tool like `evtest` to test the emulated keyboard. + + ```console + $ apk add evtest + $ evtest /dev/input/event0 + ``` + +3. Interact with the device, and observe the output. + + Example output: + + ```console + Input driver version is 1.0.1 + Input device ID: bus 0x3 vendor 0x0 product 0x0 version 0x111 + ... + Properties: + Testing ... (interrupt to exit) + Event: time 1717575532.881540, type 4 (EV_MSC), code 4 (MSC_SCAN), value 7001e + Event: time 1717575532.881540, type 1 (EV_KEY), code 2 (KEY_1), value 1 + Event: time 1717575532.881540, -------------- SYN_REPORT ------------ + ... + ``` + +> [!IMPORTANT] +> +> The initial container must remain running to maintain the connection to the USB device. Exiting the container will stop the device from working. diff --git a/content/manuals/desktop/vmm.md b/content/manuals/desktop/features/vmm.md similarity index 89% rename from content/manuals/desktop/vmm.md rename to content/manuals/desktop/features/vmm.md index bffad295014..e1099faeae6 100644 --- a/content/manuals/desktop/vmm.md +++ b/content/manuals/desktop/features/vmm.md @@ -8,10 +8,12 @@ params: text: New keywords: virtualization software, resource allocation, mac, docker desktop, vm monitoring, vm performance, apple silicon description: Discover Docker Desktop for Mac's Virtual Machine Manager (VMM) options, including the new Docker VMM for Apple Silicon, offering enhanced performance and efficiency -weight: 150 +weight: 110 +aliases: +- /desktop/vmm/ --- -The Virtual Machine Manager (VMM) in Docker Desktop for Mac is responsible for creating and managing the virtual machine used to run containers. Depending on your system architecture and performance needs, you can choose from multiple VMM options in Docker Desktop's [settings](/manuals/desktop/settings.md#general). This page provides an overview of the available options. +The Virtual Machine Manager (VMM) in Docker Desktop for Mac is responsible for creating and managing the virtual machine used to run containers. Depending on your system architecture and performance needs, you can choose from multiple VMM options in Docker Desktop's [settings](/manuals/desktop/settings-and-maintenance/settings.md#general). This page provides an overview of the available options. ## Docker VMM (Beta) @@ -25,6 +27,10 @@ Some key performance enhancements provided by Docker VMM include: These improvements directly impact developers who rely on frequent file access and overall system responsiveness during containerized development. Docker VMM marks a significant leap in speed, enabling smoother workflows and faster iteration cycles. +> [!NOTE] +> +> Docker VMM requires a minimum of 4GB of memory to be allocated to the Docker Linux VM. The memory needs to be increased before Docker VMM is enabled, and this can be done from the **Resources** tab in **Settings**. + ### Known issues As Docker VMM is still in Beta, there are a few known limitations: diff --git a/content/manuals/desktop/wasm.md b/content/manuals/desktop/features/wasm.md similarity index 98% rename from content/manuals/desktop/wasm.md rename to content/manuals/desktop/features/wasm.md index c8c36392f44..741637fc12f 100644 --- a/content/manuals/desktop/wasm.md +++ b/content/manuals/desktop/features/wasm.md @@ -1,13 +1,15 @@ --- title: Wasm workloads (Beta) -weight: 60 +weight: 20 description: How to run Wasm workloads with Docker Desktop keywords: Docker, WebAssembly, wasm, containerd, engine toc_max: 3 +aliases: +- /desktop/wasm/ --- {{% experimental title="Beta" %}} -The Wasm feature is currently in [Beta](../release-lifecycle.md#beta). +The Wasm feature is currently in [Beta](/manuals/release-lifecycle.md#beta). We recommend that you do not use this feature in production environments as this feature may change or be removed from future releases. {{% /experimental %}} diff --git a/content/manuals/desktop/wsl/_index.md b/content/manuals/desktop/features/wsl/_index.md similarity index 76% rename from content/manuals/desktop/wsl/_index.md rename to content/manuals/desktop/features/wsl/_index.md index 40e22fad773..74a5eae3e9d 100644 --- a/content/manuals/desktop/wsl/_index.md +++ b/content/manuals/desktop/features/wsl/_index.md @@ -5,11 +5,12 @@ keywords: wsl, wsl2, installing wsl2, wsl installation, docker wsl2, wsl docker, tech preview, wsl install docker, install docker wsl, how to install docker in wsl title: Docker Desktop WSL 2 backend on Windows linkTitle: WSL -weight: 80 +weight: 90 aliases: - /docker-for-windows/wsl/ - /docker-for-windows/wsl-tech-preview/ - /desktop/windows/wsl/ +- /desktop/wsl/ --- Windows Subsystem for Linux (WSL) 2 is a full Linux kernel built by Microsoft, which lets Linux distributions run without managing virtual machines. With Docker Desktop running on WSL 2, users can leverage Linux workspaces and avoid maintaining both Linux and Windows build scripts. In addition, WSL 2 provides improvements to file system sharing and boot time. @@ -23,7 +24,7 @@ Additionally, with WSL 2, the time required to start a Docker daemon after a col Before you turn on the Docker Desktop WSL 2 feature, ensure you have: - At a minimum WSL version 1.1.3.0., but ideally the latest version of WSL to [avoid Docker Desktop not working as expected](best-practices.md). -- Met the Docker Desktop for Windows' [system requirements](https://docs.docker.com/desktop/install/windows-install/#system-requirements). +- Met the Docker Desktop for Windows' [system requirements](/manuals/desktop/setup/install/windows-install.md#system-requirements). - Installed the WSL 2 feature on Windows. For detailed instructions, refer to the [Microsoft documentation](https://docs.microsoft.com/en-us/windows/wsl/install-win10). > [!TIP] @@ -55,13 +56,13 @@ Now `docker` commands work from Windows using the new WSL 2 engine. > > By default, Docker Desktop stores the data for the WSL 2 engine at `C:\Users\[USERNAME]\AppData\Local\Docker\wsl`. > If you want to change the location, for example, to another drive you can do so via the `Settings -> Resources -> Advanced` page from the Docker Dashboard. -> Read more about this and other Windows settings at [Changing settings](/manuals/desktop/settings.md) +> Read more about this and other Windows settings at [Changing settings](/manuals/desktop/settings-and-maintenance/settings.md) -## Enabling Docker support in WSL 2 distros +## Enabling Docker support in WSL 2 distributions -WSL 2 adds support for "Linux distros" to Windows, where each distro behaves like a VM except they all run on top of a single shared Linux kernel. +WSL 2 adds support for "Linux distributions" to Windows, where each distribution behaves like a VM except they all run on top of a single shared Linux kernel. -Docker Desktop does not require any particular Linux distros to be installed. The `docker` CLI and UI all work fine from Windows without any additional Linux distros. However for the best developer experience, we recommend installing at least one additional distro and enable Docker support: +Docker Desktop does not require any particular Linux distributions to be installed. The `docker` CLI and UI all work fine from Windows without any additional Linux distributions. However for the best developer experience, we recommend installing at least one additional distribution and enable Docker support: 1. Ensure the distribution runs in WSL 2 mode. WSL can run distributions in both v1 or v2 mode. @@ -71,10 +72,10 @@ Docker Desktop does not require any particular Linux distros to be installed. Th $ wsl.exe -l -v ``` - To upgrade the Linux distro to v2, run: + To upgrade the Linux distribution to v2, run: ```console - $ wsl.exe --set-version (distro name) 2 + $ wsl.exe --set-version (distribution name) 2 ``` To set v2 as the default version for future installations, run: @@ -85,19 +86,20 @@ Docker Desktop does not require any particular Linux distros to be installed. Th 2. When Docker Desktop starts, go to **Settings** > **Resources** > **WSL Integration**. - The Docker-WSL integration is enabled on the default WSL distribution, which is [Ubuntu](https://learn.microsoft.com/en-us/windows/wsl/install). To change your default WSL distro, run: + The Docker-WSL integration is enabled on the default WSL distribution, which is [Ubuntu](https://learn.microsoft.com/en-us/windows/wsl/install). To change your default WSL distribution, run: ```console - $ wsl --set-default + $ wsl --set-default ``` + If **WSL integrations** isn't available under **Resources**, Docker may be in Windows container mode. In your taskbar, select the Docker menu and then **Switch to Linux containers**. 3. Select **Apply & Restart**. > [!NOTE] > -> With Docker Desktop version 4.30 and earlier, Docker Desktop installed two special-purpose internal Linux distros `docker-desktop` and `docker-desktop-data`. `docker-desktop` is used to run the Docker engine `dockerd`, while `docker-desktop-data` stores containers and images. Neither can be used for general development. +> With Docker Desktop version 4.30 and earlier, Docker Desktop installed two special-purpose internal Linux distributions `docker-desktop` and `docker-desktop-data`. `docker-desktop` is used to run the Docker engine `dockerd`, while `docker-desktop-data` stores containers and images. Neither can be used for general development. > > With fresh installations of Docker Desktop 4.30 and later, `docker-desktop-data` is no longer created. Instead, Docker Desktop creates and -> manages its own virtual hard disk for storage. The `docker-desktop` distro is still created and used to run the Docker engine. +> manages its own virtual hard disk for storage. The `docker-desktop` distribution is still created and used to run the Docker engine. > > Note that Docker Desktop version 4.30 and later keeps using the `docker-desktop-data` distribution if it was already created by an earlier version of Docker Desktop and has not been freshly installed or factory reset. @@ -106,4 +108,4 @@ Docker Desktop does not require any particular Linux distros to be installed. Th - [Explore best practices](best-practices.md) - [Understand how to develop with Docker and WSL 2](use-wsl.md) -- [Learn about GPU support with WSL 2](../gpu.md) +- [Learn about GPU support with WSL 2](/manuals/desktop/features/gpu.md) diff --git a/content/manuals/desktop/wsl/best-practices.md b/content/manuals/desktop/features/wsl/best-practices.md similarity index 98% rename from content/manuals/desktop/wsl/best-practices.md rename to content/manuals/desktop/features/wsl/best-practices.md index ce190dd548a..393604b2ced 100644 --- a/content/manuals/desktop/wsl/best-practices.md +++ b/content/manuals/desktop/features/wsl/best-practices.md @@ -3,6 +3,8 @@ title: Best practices description: Best practices for using Docker Desktop with WSL 2 keywords: wsl, docker desktop, best practices tags: [Best practices] +aliases: +- /desktop/wsl/best-practices/ --- - Always use the latest version of WSL. At a minimum you must use WSL version 1.1.3.0., otherwise Docker Desktop may not work as expected. Testing, development, and documentation is based on the newest kernel versions. Older versions of WSL can cause: diff --git a/content/manuals/desktop/wsl/use-wsl.md b/content/manuals/desktop/features/wsl/use-wsl.md similarity index 74% rename from content/manuals/desktop/wsl/use-wsl.md rename to content/manuals/desktop/features/wsl/use-wsl.md index 4601532b446..fc4a7fd4031 100644 --- a/content/manuals/desktop/wsl/use-wsl.md +++ b/content/manuals/desktop/features/wsl/use-wsl.md @@ -2,13 +2,15 @@ title: Use WSL description: How to develop with Docker and WSL 2 and understand GPU support for WSL keywords: wsl, wsl 2, develop, docker desktop, windows +aliases: +- /desktop/wsl/use-wsl/ --- -The following section describes how to start developing your applications using Docker and WSL 2. We recommend that you have your code in your default Linux distribution for the best development experience using Docker and WSL 2. After you have turned on the WSL 2 feature on Docker Desktop, you can start working with your code inside the Linux distro and ideally with your IDE still in Windows. This workflow is straightforward if you are using [VS Code](https://code.visualstudio.com/download). +The following section describes how to start developing your applications using Docker and WSL 2. We recommend that you have your code in your default Linux distribution for the best development experience using Docker and WSL 2. After you have turned on the WSL 2 feature on Docker Desktop, you can start working with your code inside the Linux distribution and ideally with your IDE still in Windows. This workflow is straightforward if you are using [VS Code](https://code.visualstudio.com/download). ## Develop with Docker and WSL 2 -1. Open VS Code and install the [Remote - WSL](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-wsl) extension. This extension lets you work with a remote server in the Linux distro and your IDE client still on Windows. +1. Open VS Code and install the [Remote - WSL](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-wsl) extension. This extension lets you work with a remote server in the Linux distribution and your IDE client still on Windows. 2. Open your terminal and type: ```console @@ -20,7 +22,7 @@ The following section describes how to start developing your applications using $ code . ``` - This opens a new VS Code window connected remotely to your default Linux distro which you can check in the bottom corner of the screen. + This opens a new VS Code window connected remotely to your default Linux distribution which you can check in the bottom corner of the screen. Alternatively, you can open your default Linux distribution from the **Start** menu, navigate to your project directory, and then run `code .` diff --git a/content/manuals/desktop/images/dashboard.webp b/content/manuals/desktop/images/dashboard.webp index e76911ae84b..ac3346c820c 100644 Binary files a/content/manuals/desktop/images/dashboard.webp and b/content/manuals/desktop/images/dashboard.webp differ diff --git a/content/manuals/desktop/images/diagnose-support.png b/content/manuals/desktop/images/diagnose-support.png deleted file mode 100644 index 981eaa88809..00000000000 Binary files a/content/manuals/desktop/images/diagnose-support.png and /dev/null differ diff --git a/content/manuals/desktop/images/gordon-run-ctr.png b/content/manuals/desktop/images/gordon-run-ctr.png new file mode 100644 index 00000000000..5369a82a7b0 Binary files /dev/null and b/content/manuals/desktop/images/gordon-run-ctr.png differ diff --git a/content/manuals/desktop/images/troubleshoot.png b/content/manuals/desktop/images/troubleshoot.png deleted file mode 100644 index 7e24d46931c..00000000000 Binary files a/content/manuals/desktop/images/troubleshoot.png and /dev/null differ diff --git a/content/manuals/desktop/install/images/docker-app-in-apps.png b/content/manuals/desktop/install/images/docker-app-in-apps.png deleted file mode 100644 index 6f191918597..00000000000 Binary files a/content/manuals/desktop/install/images/docker-app-in-apps.png and /dev/null differ diff --git a/content/manuals/desktop/install/msi/_index.md b/content/manuals/desktop/install/msi/_index.md deleted file mode 100644 index 9cdb5cbc360..00000000000 --- a/content/manuals/desktop/install/msi/_index.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Deploy with Microsoft installer -linkTitle: Use the MSI installer -weight: 50 -description: If you're an IT admin, learn how to deploy Docker Desktop with Microsoft installer -keywords: msi, docker desktop, windows, installation ---- - -> [!NOTE] -> -> The MSI installer is available to all company and organization owners with a Business subscription and Docker Desktop version 4.32 and later. - -Docker offers a 64-bit Microsoft Installer (MSI) package designed to assist IT administrators in customizing and deploying Docker Desktop across multiple users or machines in an enterprise environment. - -The MSI package supports various MDM (Mobile Device Management) solutions, making it ideal for bulk installations and eliminating the need for manual setups by individual users. With this package, IT administrators can ensure standardized, policy-driven installations of Docker Desktop, enhancing efficiency and software management across their organizations. - -Whether you're looking to implement scripted installations or integrate Docker Desktop with existing MDM solutions, this MSI package is an essential resource. - -## What's next - -- [Use the Microsoft installer and read the configuration options](install-and-configure.md) -- [Read the FAQs](faq.md) -- [Install with Intune](use-intune.md) diff --git a/content/manuals/desktop/previous-versions/2.x-windows.md b/content/manuals/desktop/previous-versions/2.x-windows.md index 3db8701020a..1b20bc5c82d 100644 --- a/content/manuals/desktop/previous-versions/2.x-windows.md +++ b/content/manuals/desktop/previous-versions/2.x-windows.md @@ -104,15 +104,15 @@ Docker Desktop 2.4.0.0 contains a Kubernetes upgrade. Your local Kubernetes clus ### WSL 2 changes -- Docker contexts are now synced between Windows and WSL distros. +- Docker contexts are now synced between Windows and WSL distributions. - Fixed an issue that intermittently causes the backend to fail to start. - Fixed a proxy crash that happened when glibc was not compatible. See [docker/for-win#8183](https://github.com/docker/for-win/issues/8183). - Fixed an issue when removing a container mounting `/mnt/wsl` would break WSL integration. See [docker/for-win#7836](https://github.com/docker/for-win/issues/7836). -- Added support for mounting files from a distro using the Windows CLI (e.g. `docker run -v \\wsl$\Ubuntu\home\simon\web:/web ...`) +- Added support for mounting files from a distribution using the Windows CLI (e.g. `docker run -v \\wsl$\Ubuntu\home\simon\web:/web ...`) - Fixed the error message when attempting to use a shared volume with a relative path. Fixes [docker/for-win#6894](https://github.com/docker/for-win/issues/6894). - Fixed an issue when updating Windows to a WSL 2 capable version, where a configuration file is locked by the old Hyper-V VM. - Fixed a discrepancy in the version of Docker Compose inside and outside of WSL 2. Fixes [docker/for-win#6461](https://github.com/docker/for-win/issues/6461). -- Detect when the `docker-desktop` wsl distro is stopped and display a clearer error message. +- Detect when the `docker-desktop` wsl distribution is stopped and display a clearer error message. - Fix a race condition when exposing ports. - Enable dialog no longer blocks other windows. @@ -189,7 +189,7 @@ Docker Desktop 2.4.0.0 contains a Kubernetes upgrade. Your local Kubernetes clus ### New -- Windows 10 Home users can now use Docker Desktop through WSL 2. This requires Windows 10, version 2004 or higher. For more information, see [Install Docker Desktop on Windows](../install/windows-install.md). +- Windows 10 Home users can now use Docker Desktop through WSL 2. This requires Windows 10, version 2004 or higher. For more information, see [Install Docker Desktop on Windows](/manuals/desktop/setup/install/windows-install.md). - Docker Desktop introduces a new onboarding tutorial upon first startup. The Quick Start tutorial guides users to get started with Docker in a few easy steps. 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 Desktop now allows sharing individual folders, rather than whole drives, giving more control to users over what is being shared. @@ -205,7 +205,7 @@ Docker Desktop 2.4.0.0 contains a Kubernetes upgrade. Your local Kubernetes clus **WSL 2** - Docker Desktop only exposes host ports in Linux if the Windows port is available. -- Docker Desktop now allows users to refresh the list of distros. +- Docker Desktop now allows users to refresh the list of distributions. - Docker Desktop defaults to WSL 2 on install on compatible OS versions. - Docker Desktop detects missing Linux kernel and adds a pointer to the Microsoft documentation to download the kernel. - Detect when the WSL 2 backend stops and allow the user to restart it. @@ -244,7 +244,7 @@ Docker Desktop 2.4.0.0 contains a Kubernetes upgrade. Your local Kubernetes clus ### Known issues -- Some CLI commands fail if you are running Docker Desktop in the experimental Linux Containers on Windows (LCOW) mode. As alternatives, we recommend running either traditional Linux containers, or the [WSL 2 backend](../wsl/_index.md). +- Some CLI commands fail if you are running Docker Desktop in the experimental Linux Containers on Windows (LCOW) mode. As alternatives, we recommend running either traditional Linux containers, or the [WSL 2 backend](/manuals/desktop/features/wsl/_index.md). **WSL 2** @@ -284,7 +284,7 @@ Docker Desktop 2.4.0.0 contains a Kubernetes upgrade. Your local Kubernetes clus ### Known issues -- Some CLI commands fail if you are running Docker Desktop in the experimental Linux Containers on Windows (LCOW) mode. As alternatives, we recommend running either traditional Linux containers, or the experimental [WSL backend](../wsl/_index.md). +- Some CLI commands fail if you are running Docker Desktop in the experimental Linux Containers on Windows (LCOW) mode. As alternatives, we recommend running either traditional Linux containers, or the experimental [WSL backend](/manuals/desktop/features/wsl/_index.md). - It is not possible to resize the disk image using the Docker Desktop **Settings** UI. If you would like to update the size of the disk image (for example, to 128 GB), run the following command in PowerShell: ```powershell @@ -318,11 +318,11 @@ Docker Desktop 2.4.0.0 contains a Kubernetes upgrade. Your local Kubernetes clus - Fixed a race condition when starting the WSL engine which caused Docker Desktop to incorrectly report that the containers have exited. Fixes [docker/for-win#5607](https://github.com/docker/for-win/issues/5607). - Fixed an issue where editing code inside a container resulted in an error. Fixes [docker/for-win#5528](https://github.com/docker/for-win/issues/5528). - Fixed a bug where running the command `DockerCli.exe -SharedDrives` failed to display a list of drives that are shared. Fixes [docker/for-win#5625](https://github.com/docker/for-win/issues/5625). -- Starting with Docker Desktop 2.2.0.3, you must access all shared files using their original case. For example, if you have created a file called `test`, you must open it as `test`. Attempts to open the file as `Test` will fail with the error `No such file or directory`. For more information, see _Tips on shared drives, permissions, and volume mounts_ in [File sharing](/manuals/desktop/settings.md#file-sharing). +- Starting with Docker Desktop 2.2.0.3, you must access all shared files using their original case. For example, if you have created a file called `test`, you must open it as `test`. Attempts to open the file as `Test` will fail with the error `No such file or directory`. For more information, see _Tips on shared drives, permissions, and volume mounts_ in [File sharing](/manuals/desktop/settings-and-maintenance/settings.md#file-sharing). ### Known issues -- DockerNAT has been removed from Docker Desktop 2.2.0.0 as using an IP address to communicate from the host to a container is not a supported feature. To communicate from a container to the host, you must use the special DNS name `host.docker.internal`. We also recommend using ports to communicate from the host to a container. For more information, see [Networking](../networking.md#use-cases-and-workarounds-for-all-platforms). +- DockerNAT has been removed from Docker Desktop 2.2.0.0 as using an IP address to communicate from the host to a container is not a supported feature. To communicate from a container to the host, you must use the special DNS name `host.docker.internal`. We also recommend using ports to communicate from the host to a container. For more information, see [Networking](/manuals/desktop/features/networking.md#use-cases-and-workarounds-for-all-platforms). However, if your current setup relies on IP addresses for communication, you can use a temporary workaround to reinstate DockerNAT. To do this, open `C:\Program Files\Docker\Docker\resources\MobyLinux.ps1` and add `$SwitchName = "DockerNAT"` between line 175 and 176. Note that the temporary workaround to reinstate DockerNAT may be removed from future releases. @@ -348,7 +348,7 @@ Docker Desktop 2.2.0.0 contains a Kubernetes upgrade. Your local Kubernetes clus - **Docker Desktop Dashboard:** The new Docker Desktop **Dashboard** provides a user-friendly interface which enables you to interact with containers and applications, and manage the lifecycle of your applications directly from the UI. In addition, it allows you to access the logs, view container details, and monitor resource utilization to explore the container behavior. For detailed information about the new Dashboard UI, see [Docker Desktop Dashboard](../_index.md). -- **WSL 2 backend:** The experimental Docker Desktop WSL 2 backend architecture introduces support for Kubernetes, provides an updated Docker daemon, offers VPN-friendly networking, and additional features. For more information, see [Docker Desktop WSL 2 backend](../wsl/_index.md). +- **WSL 2 backend:** The experimental Docker Desktop WSL 2 backend architecture introduces support for Kubernetes, provides an updated Docker daemon, offers VPN-friendly networking, and additional features. For more information, see [Docker Desktop WSL 2 backend](/manuals/desktop/features/wsl/_index.md). - **New file sharing implementation:** Docker Desktop introduces a new file sharing implementation that replaces Samba, CIFS, and Hyper-V networking. The new implementation offers improved I/O performance. Additionally, when using the new file system: diff --git a/content/manuals/desktop/previous-versions/3.x-mac.md b/content/manuals/desktop/previous-versions/3.x-mac.md index 1dfddfc554f..3444a12d02f 100644 --- a/content/manuals/desktop/previous-versions/3.x-mac.md +++ b/content/manuals/desktop/previous-versions/3.x-mac.md @@ -49,7 +49,7 @@ This page contains release notes for Docker Desktop for Mac 3.x. ### New -**Dev Environments Preview**: Dev Environments enable you to seamlessly collaborate with your team members without moving between Git branches to get your code onto your team members' machines. When using Dev Environments, you can share your in-progress work with your team members in just one click, and without having to deal with any merge conflicts. For more information and for instructions on how to use Dev Environments, see [Development Environments Preview](../dev-environments/_index.md). +**Dev Environments Preview**: Dev Environments enable you to seamlessly collaborate with your team members without moving between Git branches to get your code onto your team members' machines. When using Dev Environments, you can share your in-progress work with your team members in just one click, and without having to deal with any merge conflicts. For more information and for instructions on how to use Dev Environments, see [Development Environments Preview](/manuals/desktop/features/dev-environments/_index.md). ### Upgrades @@ -77,7 +77,7 @@ This page contains release notes for Docker Desktop for Mac 3.x. ### New -**Dev Environments Preview**: Dev Environments enable you to seamlessly collaborate with your team members without moving between Git branches to get your code onto your team members' machines. When using Dev Environments, you can share your in-progress work with your team members in just one click, and without having to deal with any merge conflicts. For more information and for instructions on how to use Dev Environments, see [Development Environments Preview](../dev-environments/_index.md). +**Dev Environments Preview**: Dev Environments enable you to seamlessly collaborate with your team members without moving between Git branches to get your code onto your team members' machines. When using Dev Environments, you can share your in-progress work with your team members in just one click, and without having to deal with any merge conflicts. For more information and for instructions on how to use Dev Environments, see [Development Environments Preview](/manuals/desktop/features/dev-environments/_index.md). **Compose V2 beta**: Docker Desktop now includes the beta version of Compose V2, which supports the `docker compose` command as part of the Docker CLI. While `docker-compose` is still supported and maintained, Compose V2 implementation relies directly on the compose-go bindings which are maintained as part of the specification. 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`. There are a few remaining flags that have yet to be implemented, see the [docker-compose compatibility list](/manuals/compose/releases/migrate.md) for more information about the flags that are supported in the new compose command. If you run into any problems with Compose V2, you can easily switch back to Compose v1 by either by making changes in Docker Desktop **Experimental** Settings, or by running the command `docker-compose disable-v2`. Let us know your feedback on the new ‘compose’ command by creating an issue in the [Compose-CLI](https://github.com/docker/compose-cli/issues) GitHub repository. @@ -90,7 +90,7 @@ This page contains release notes for Docker Desktop for Mac 3.x. ### New -**Dev Environments Preview**: Dev Environments enable you to seamlessly collaborate with your team members without moving between Git branches to get your code onto your team members' machines. When using Dev Environments, you can share your in-progress work with your team members in just one click, and without having to deal with any merge conflicts. For more information and for instructions on how to use Dev Environments, see [Development Environments Preview](../dev-environments/_index.md). +**Dev Environments Preview**: Dev Environments enable you to seamlessly collaborate with your team members without moving between Git branches to get your code onto your team members' machines. When using Dev Environments, you can share your in-progress work with your team members in just one click, and without having to deal with any merge conflicts. For more information and for instructions on how to use Dev Environments, see [Development Environments Preview](/manuals/desktop/features/dev-environments/_index.md). **Compose V2 beta**: Docker Desktop now includes the beta version of Compose V2, which supports the `docker compose` command as part of the Docker CLI. While `docker-compose` is still supported and maintained, Compose V2 implementation relies directly on the compose-go bindings which are maintained as part of the specification. 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`. There are a few remaining flags that have yet to be implemented, see the [docker-compose compatibility list](/manuals/compose/releases/migrate.md) for more information about the flags that are supported in the new compose command. If you run into any problems with Compose V2, you can easily switch back to Compose v1 by either by making changes in Docker Desktop **Experimental** Settings, or by running the command `docker-compose disable-v2`. Let us know your feedback on the new ‘compose’ command by creating an issue in the [Compose-CLI](https://github.com/docker/compose-cli/issues) GitHub repository. @@ -202,7 +202,7 @@ This page contains release notes for Docker Desktop for Mac 3.x. ### New -Docker Desktop is now available for Apple silicon as well as Intel chips. This enables developers with their choice of local development environments, and extends development pipelines for ARM-based applications. For more information, see [Docker Desktop for Apple silicon](../install/mac-install.md). +Docker Desktop is now available for Apple silicon as well as Intel chips. This enables developers with their choice of local development environments, and extends development pipelines for ARM-based applications. For more information, see [Docker Desktop for Apple silicon](/manuals/desktop/setup/install/mac-install.md). ### Bug fixes and minor changes diff --git a/content/manuals/desktop/previous-versions/3.x-windows.md b/content/manuals/desktop/previous-versions/3.x-windows.md index 861b1b88ec4..b93c1c7435f 100644 --- a/content/manuals/desktop/previous-versions/3.x-windows.md +++ b/content/manuals/desktop/previous-versions/3.x-windows.md @@ -56,7 +56,7 @@ This page contains release notes for Docker Desktop for Windows 3.x. ### New -**Dev Environments Preview**: Dev Environments enable you to seamlessly collaborate with your team members without moving between Git branches to get your code onto your team members' machines. When using Dev Environments, you can share your in-progress work with your team members in just one click, and without having to deal with any merge conflicts. For more information and for instructions on how to use Dev Environments, see [Development Environments Preview](../dev-environments/_index.md). +**Dev Environments Preview**: Dev Environments enable you to seamlessly collaborate with your team members without moving between Git branches to get your code onto your team members' machines. When using Dev Environments, you can share your in-progress work with your team members in just one click, and without having to deal with any merge conflicts. For more information and for instructions on how to use Dev Environments, see [Development Environments Preview](/manuals/desktop/features/dev-environments/_index.md). ### Upgrades @@ -84,7 +84,7 @@ This page contains release notes for Docker Desktop for Windows 3.x. ### New -**Dev Environments Preview**: Dev Environments enable you to seamlessly collaborate with your team members without moving between Git branches to get your code onto your team members' machines. When using Dev Environments, you can share your in-progress work with your team members in just one click, and without having to deal with any merge conflicts. For more information and for instructions on how to use Dev Environments, see [Development Environments Preview](../dev-environments/_index.md). +**Dev Environments Preview**: Dev Environments enable you to seamlessly collaborate with your team members without moving between Git branches to get your code onto your team members' machines. When using Dev Environments, you can share your in-progress work with your team members in just one click, and without having to deal with any merge conflicts. For more information and for instructions on how to use Dev Environments, see [Development Environments Preview](/manuals/desktop/features/dev-environments/_index.md). **Compose V2 beta**: Docker Desktop now includes the beta version of Compose V2, which supports the `docker compose` command as part of the Docker CLI. While `docker-compose` is still supported and maintained, Compose V2 implementation relies directly on the compose-go bindings which are maintained as part of the specification. 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`. There are a few remaining flags that have yet to be implemented, see the [docker-compose compatibility list](/manuals/compose/releases/migrate.md) for more information about the flags that are supported in the new compose command. If you run into any problems with Compose V2, you can easily switch back to Compose v1 by either by making changes in Docker Desktop **Experimental** Settings, or by running the command `docker-compose disable-v2`. Let us know your feedback on the new ‘compose’ command by creating an issue in the [Compose-CLI](https://github.com/docker/compose-cli/issues) GitHub repository. @@ -98,7 +98,7 @@ This page contains release notes for Docker Desktop for Windows 3.x. ### New -**Dev Environments Preview**: Dev Environments enable you to seamlessly collaborate with your team members without moving between Git branches to get your code onto your team members' machines. When using Dev Environments, you can share your in-progress work with your team members in just one click, and without having to deal with any merge conflicts. For more information and for instructions on how to use Dev Environments, see [Development Environments Preview](../dev-environments/_index.md). +**Dev Environments Preview**: Dev Environments enable you to seamlessly collaborate with your team members without moving between Git branches to get your code onto your team members' machines. When using Dev Environments, you can share your in-progress work with your team members in just one click, and without having to deal with any merge conflicts. For more information and for instructions on how to use Dev Environments, see [Development Environments Preview](/manuals/desktop/features/dev-environments/_index.md). **Compose V2 beta**: Docker Desktop now includes the beta version of Compose V2, which supports the `docker compose` command as part of the Docker CLI. While `docker-compose` is still supported and maintained, Compose V2 implementation relies directly on the compose-go bindings which are maintained as part of the specification. 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`. There are a few remaining flags that have yet to be implemented, see the [docker-compose compatibility list](/manuals/compose/releases/migrate.md) for more information about the flags that are supported in the new compose command. If you run into any problems with Compose V2, you can easily switch back to Compose v1 by either by making changes in Docker Desktop **Experimental** Settings, or by running the command `docker-compose disable-v2`. Let us know your feedback on the new ‘compose’ command by creating an issue in the [Compose-CLI](https://github.com/docker/compose-cli/issues) GitHub repository. diff --git a/content/manuals/desktop/previous-versions/archive-mac.md b/content/manuals/desktop/previous-versions/archive-mac.md index 28003bd6bc8..692afebd842 100644 --- a/content/manuals/desktop/previous-versions/archive-mac.md +++ b/content/manuals/desktop/previous-versions/archive-mac.md @@ -31,7 +31,7 @@ This page contains release notes for older versions of Docker Desktop for Mac. - Linux Kernel 4.9.93 with CEPH, DRBD, RBD, MPLS_ROUTING and MPLS_IPTUNNEL enabled * New - - Kubernetes Support. You can now run a single-node Kubernetes cluster from the "Kubernetes" Pane in Docker For Mac Preferences and use kubectl commands as well as docker commands. See [the Kubernetes section](../kubernetes.md) + - Kubernetes Support. You can now run a single-node Kubernetes cluster from the "Kubernetes" Pane in Docker For Mac Preferences and use kubectl commands as well as docker commands. See [the Kubernetes section](/manuals/desktop/features/kubernetes.md) - Add an experimental SOCKS server to allow access to container networks, see [docker/for-mac#2670](https://github.com/docker/for-mac/issues/2670#issuecomment-372365274). Also see [docker/for-mac#2721](https://github.com/docker/for-mac/issues/2721) - Re-enable raw as the default disk format for users running macOS 10.13.4 and higher. Note this change only takes effect after a "reset to factory defaults" or "remove all data" (from the Whale menu -> Preferences -> Reset). Related to [docker/for-mac#2625](https://github.com/docker/for-mac/issues/2625) diff --git a/content/manuals/desktop/previous-versions/archive-windows.md b/content/manuals/desktop/previous-versions/archive-windows.md index efeb4f928ea..262e7c79339 100644 --- a/content/manuals/desktop/previous-versions/archive-windows.md +++ b/content/manuals/desktop/previous-versions/archive-windows.md @@ -47,7 +47,7 @@ This page contains release notes for older versions of Docker Desktop for Window - Linux Kernel 4.9.93 with CEPH, DRBD, RBD, MPLS_ROUTING and MPLS_IPTUNNEL enabled * New - - Kubernetes Support. You can now run a single-node Kubernetes cluster from the "Kubernetes" Pane in Docker for Windows settings and use kubectl commands as well as Docker commands. See [the Kubernetes section](../kubernetes.md) + - Kubernetes Support. You can now run a single-node Kubernetes cluster from the "Kubernetes" Pane in Docker for Windows settings and use kubectl commands as well as Docker commands. See [the Kubernetes section](/manuals/desktop/features/kubernetes.md) * Bug fixes and minor changes - AUFS storage driver is deprecated in Docker Desktop and AUFS support will be removed in the next major release. You can continue with AUFS in Docker Desktop 18.06.x, but you will need to reset the disk image (in Settings > Reset menu) before updating to the next major update. You can check documentation to [save images](/reference/cli/docker/image/save/#examples) and [backup volumes](/manuals/engine/storage/volumes.md#back-up-restore-or-migrate-data-volumes) diff --git a/content/manuals/desktop/previous-versions/edge-releases-mac.md b/content/manuals/desktop/previous-versions/edge-releases-mac.md index 0a17922e475..60a9bccf7f5 100644 --- a/content/manuals/desktop/previous-versions/edge-releases-mac.md +++ b/content/manuals/desktop/previous-versions/edge-releases-mac.md @@ -12,7 +12,7 @@ sitemap: false This page contains information about Docker Desktop Edge releases. Edge releases give you early access to our newest features. Note that some of the features may be experimental, and some of them may not ever reach the Stable release. For Docker Desktop system requirements, see -[What to know before you install](../install/mac-install.md#system-requirements). +[What to know before you install](/manuals/desktop/setup/install/mac-install.md#system-requirements). ## Docker Desktop Community 2.5.4 2020-12-07 @@ -82,7 +82,7 @@ This release contains a Kubernetes upgrade. Note that your local Kubernetes clus ### New -- If you have enabled [Vulnerability Scanning](/docker-hub/vulnerability-scanning/) in Docker Hub, the scan results will now appear in Docker Desktop. +- If you have enabled [Vulnerability Scanning](/docker-hub/repos/manage/vulnerability-scanning/) in Docker Hub, the scan results will now appear in Docker Desktop. ### Upgrades @@ -924,7 +924,7 @@ This release contains a Kubernetes upgrade. Note that your local Kubernetes clus - [Docker 17.12.0-ce](https://github.com/docker/docker-ce/releases/tag/v17.12.0-ce) * New - - Experimental Kubernetes Support. You can now run a single-node Kubernetes cluster from the "Kubernetes" Pane in Docker For Mac Preferences and use kubectl commands as well as docker commands. See [the Kubernetes section](../kubernetes.md) + - Experimental Kubernetes Support. You can now run a single-node Kubernetes cluster from the "Kubernetes" Pane in Docker For Mac Preferences and use kubectl commands as well as docker commands. See [the Kubernetes section](/manuals/desktop/features/kubernetes.md) - DNS name `docker.for.mac.host.internal` should be used instead of `docker.for.mac.localhost` (still valid) for host resolution from containers, since since there is an RFC banning the use of subdomains of localhost (See https://tools.ietf.org/html/draft-west-let-localhost-be-localhost-06). * Bug fixes and minor changes @@ -1450,7 +1450,9 @@ TCP connection is idle for more than five minutes (related to ### Beta 36 Release Notes (2017-01-12 1.13.0-rc6-beta36) ->**Important Note:** Plugins installed using the experimental "managed plugins" feature in Docker 1.12 must be removed/uninstalled before upgrading. +> [!IMPORTANT] +> +> Plugins installed using the experimental "managed plugins" feature in Docker 1.12 must be removed/uninstalled before upgrading. **Upgrades** @@ -1464,7 +1466,9 @@ TCP connection is idle for more than five minutes (related to ### Beta 35 Release Notes (2017-01-06 1.13.0-rc5-beta35) ->**Important Note:** Plugins installed using the experimental "managed plugins" feature in Docker 1.12 must be removed/uninstalled before upgrading. +> [!IMPORTANT] +> +> Plugins installed using the experimental "managed plugins" feature in Docker 1.12 must be removed/uninstalled before upgrading. **Upgrades** @@ -1475,7 +1479,9 @@ TCP connection is idle for more than five minutes (related to ### Beta 34.1 Release Notes (2016-12-22 1.13.0-rc4-beta34.1) ->**Important Note:** Plugins installed using the experimental "managed plugins" feature in Docker 1.12 must be removed/uninstalled before upgrading. +> [!IMPORTANT] +> +> Plugins installed using the experimental "managed plugins" feature in Docker 1.12 must be removed/uninstalled before upgrading. **Hotfix** @@ -1487,7 +1493,9 @@ TCP connection is idle for more than five minutes (related to ### Beta 34 Release Notes (2016-12-20 1.13.0-rc4-beta34) ->**Important Note:** Plugins installed using the experimental "managed plugins" feature in Docker 1.12 must be removed/uninstalled before upgrading. +> [!IMPORTANT] +> +> Plugins installed using the experimental "managed plugins" feature in Docker 1.12 must be removed/uninstalled before upgrading. **New** @@ -1509,7 +1517,9 @@ TCP connection is idle for more than five minutes (related to ### Beta 33.1 Release Notes (2016-12-16 1.13.0-rc3-beta33.1) ->**Important Note:** Plugins installed using the experimental "managed plugins" feature in Docker 1.12 must be removed/uninstalled before upgrading. +> [!IMPORTANT] +> +> Plugins installed using the experimental "managed plugins" feature in Docker 1.12 must be removed/uninstalled before upgrading. **Hotfix** @@ -1517,7 +1527,9 @@ TCP connection is idle for more than five minutes (related to ### Beta 33 Release Notes (2016-12-15 1.13.0-rc3-beta33) ->**Important Note:** Plugins installed using the experimental "managed plugins" feature in Docker 1.12 must be removed/uninstalled before upgrading. +> [!IMPORTANT] +> +> Plugins installed using the experimental "managed plugins" feature in Docker 1.12 must be removed/uninstalled before upgrading. **New** @@ -1560,9 +1572,9 @@ TCP connection is idle for more than five minutes (related to **New** -- Dedicated preference pane for advanced configuration of the docker daemon (edit daemon.json). See [Daemon Advanced (JSON configuration file)](/manuals/desktop/settings.md#docker-engine). +- Dedicated preference pane for advanced configuration of the docker daemon (edit daemon.json). See [Daemon Advanced (JSON configuration file)](/manuals/desktop/settings-and-maintenance/settings.md#docker-engine). -- Docker Experimental mode can be toggled. See [Daemon Basic (experimental mode and registries)](/manuals/desktop/settings.md#docker-engine). +- Docker Experimental mode can be toggled. See [Daemon Basic (experimental mode and registries)](/manuals/desktop/settings-and-maintenance/settings.md#docker-engine). **Upgrades** @@ -1718,7 +1730,7 @@ issue is being investigated. The workaround is to restart Docker.app. traversals of large directories are currently slow. Additionally, containers that perform large numbers of directory operations, such as repeated scans of large directory trees, may suffer from poor performance. More information is -available in [Known Issues](../troubleshoot/known-issues.md) in Troubleshooting. +available in [Known Issues](/manuals/desktop/troubleshoot-and-support/troubleshoot/known-issues.md) in Troubleshooting. * Under some unhandled error conditions, `inotify` event delivery can fail and become permanently disabled. The workaround is to restart `Docker.app`. @@ -1748,7 +1760,7 @@ with `osxfs`. In particular, writes of small blocks and traversals of large directories are currently slow. Additionally, containers that perform large numbers of directory operations, such as repeated scans of large directory trees, may suffer from poor performance. More information is available in -[Known Issues](../troubleshoot/known-issues.md) in Troubleshooting. +[Known Issues](/manuals/desktop/troubleshoot-and-support/troubleshoot/known-issues.md) in Troubleshooting. * Under some unhandled error conditions, `inotify` event delivery can fail and become permanently disabled. The workaround is to restart Docker.app. @@ -1782,7 +1794,7 @@ trees, may suffer from poor performance. More information is available in * There are a number of issues with the performance of directories bind-mounted with `osxfs`. In particular, writes of small blocks and traversals of large directories are currently slow. Additionally, containers that perform large numbers of directory operations, such as repeated scans of large directory -trees, may suffer from poor performance. For more information and workarounds, see the bullet on performance of bind-mounted directories in [Known Issues](../troubleshoot/known-issues.md) in Troubleshooting. +trees, may suffer from poor performance. For more information and workarounds, see the bullet on performance of bind-mounted directories in [Known Issues](/manuals/desktop/troubleshoot-and-support/troubleshoot/known-issues.md) in Troubleshooting. * Under some unhandled error conditions, `inotify` event delivery can fail and become permanently disabled. The workaround is to restart `Docker.app`. @@ -1808,7 +1820,7 @@ trees, may suffer from poor performance. For more information and workarounds, s * Docker.app sometimes uses 200% CPU after macOS wakes up from sleep mode. The issue is being investigated. The workaround is to restart Docker.app -* There are a number of issues with the performance of directories bind-mounted with `osxfs`. In particular, writes of small blocks and traversals of large directories are currently slow. Additionally, containers that perform large numbers of directory operations, such as repeated scans of large directory trees, may suffer from poor performance. For more information and workarounds, see the bullet on performance of bind-mounted directories in [Known Issues](../troubleshoot/known-issues.md) in Troubleshooting. +* There are a number of issues with the performance of directories bind-mounted with `osxfs`. In particular, writes of small blocks and traversals of large directories are currently slow. Additionally, containers that perform large numbers of directory operations, such as repeated scans of large directory trees, may suffer from poor performance. For more information and workarounds, see the bullet on performance of bind-mounted directories in [Known Issues](/manuals/desktop/troubleshoot-and-support/troubleshoot/known-issues.md) in Troubleshooting. * Under some unhandled error conditions, `inotify` event delivery can fail and become permanently disabled. The workaround is to restart Docker.app @@ -1831,7 +1843,7 @@ trees, may suffer from poor performance. For more information and workarounds, s * Docker.app sometimes uses 200% CPU after macOS wakes up from sleep mode. The issue is being investigated. The workaround is to restart Docker.app -* There are a number of issues with the performance of directories bind-mounted with `osxfs`. In particular, writes of small blocks and traversals of large directories are currently slow. Additionally, containers that perform large numbers of directory operations, such as repeated scans of large directory trees, may suffer from poor performance. More information is available in [Known Issues](../troubleshoot/known-issues.md). +* There are a number of issues with the performance of directories bind-mounted with `osxfs`. In particular, writes of small blocks and traversals of large directories are currently slow. Additionally, containers that perform large numbers of directory operations, such as repeated scans of large directory trees, may suffer from poor performance. More information is available in [Known Issues](/manuals/desktop/troubleshoot-and-support/troubleshoot/known-issues.md). * Under some unhandled error conditions, `inotify` event delivery can fail and become permanently disabled. The workaround is to restart Docker.app @@ -1855,7 +1867,7 @@ events or unexpected unmounts. **New** -* Docker for Mac is now available from 2 channels: **stable** and **beta**. New features and bug fixes will go out first in auto-updates to users in the beta channel. Updates to the stable channel are much less frequent and happen in sync with major and minor releases of the Docker engine. Only features that are well-tested and ready for production are added to the stable channel releases. For downloads of both and more information, see the [installation guide](../install/mac-install.md). +* Docker for Mac is now available from 2 channels: **stable** and **beta**. New features and bug fixes will go out first in auto-updates to users in the beta channel. Updates to the stable channel are much less frequent and happen in sync with major and minor releases of the Docker Engine. Only features that are well-tested and ready for production are added to the stable channel releases. For downloads of both and more information, see the [installation guide](/manuals/desktop/setup/install/mac-install.md). **Upgrades** @@ -1878,7 +1890,7 @@ events or unexpected unmounts. * Docker.app sometimes uses 200% CPU after macOS wakes up from sleep mode. The issue is being investigated. The workaround is to restart Docker.app -* There are a number of issues with the performance of directories bind-mounted with `osxfs`. In particular, writes of small blocks, and traversals of large directories are currently slow. Additionally, containers that perform large numbers of directory operations, such as repeated scans of large directory trees, may suffer from poor performance. For more information and workarounds, see [Known Issues](../troubleshoot/known-issues.md) in [Logs and Troubleshooting](../troubleshoot/_index.md). +* There are a number of issues with the performance of directories bind-mounted with `osxfs`. In particular, writes of small blocks, and traversals of large directories are currently slow. Additionally, containers that perform large numbers of directory operations, such as repeated scans of large directory trees, may suffer from poor performance. For more information and workarounds, see [Known Issues](/manuals/desktop/troubleshoot-and-support/troubleshoot/known-issues.md) in [Logs and Troubleshooting](/manuals/desktop/troubleshoot-and-support/troubleshoot/_index.md). * Under some unhandled error conditions, `inotify` event delivery can fail and become permanently disabled. The workaround is to restart Docker.app @@ -1922,11 +1934,13 @@ events or unexpected unmounts. **Known issues** -* See [Known Issues](../troubleshoot/known-issues.md). +* See [Known Issues](/manuals/desktop/troubleshoot-and-support/troubleshoot/known-issues.md). ### Beta 18.1 Release Notes (2016-07-07 1.12.0-rc3-beta18.1) ->**Note**: Docker 1.12.0 RC3 release introduces a backward incompatible change from RC2. You can fix this by recreating or updating your containers. +> [!NOTE] +> +> Docker 1.12.0 RC3 release introduces a backward incompatible change from RC2. You can fix this by recreating or updating your containers. **Hotfix** @@ -1948,7 +1962,7 @@ events or unexpected unmounts. **Known issues** -* See [Known Issues](../troubleshoot/known-issues.md). +* See [Known Issues](/manuals/desktop/troubleshoot-and-support/troubleshoot/known-issues.md). ### Beta 18 Release Notes (2016-07-06 1.12.0-rc3-beta18) @@ -1969,7 +1983,7 @@ events or unexpected unmounts. **Known issues** -* See [Known Issues](../troubleshoot/known-issues.md). +* See [Known Issues](/manuals/desktop/troubleshoot-and-support/troubleshoot/known-issues.md). ### Beta 17 Release Notes (2016-06-29 1.12.0-rc2-beta17) @@ -1988,7 +2002,7 @@ events or unexpected unmounts. **Known issues** -* See [Known Issues](../troubleshoot/known-issues.md). +* See [Known Issues](/manuals/desktop/troubleshoot-and-support/troubleshoot/known-issues.md). ### Beta 16 Release Notes (2016-06-17 1.12.0-rc2-beta16) @@ -2010,7 +2024,7 @@ events or unexpected unmounts. **Known issues** -* See [Known Issues](../troubleshoot/known-issues.md). +* See [Known Issues](/manuals/desktop/troubleshoot-and-support/troubleshoot/known-issues.md). ### Beta 15 Release Notes (2016-06-10 1.11.2-beta15) @@ -2034,7 +2048,7 @@ events or unexpected unmounts. **Known issues** -* See [Known Issues](../troubleshoot/known-issues.md). +* See [Known Issues](/manuals/desktop/troubleshoot-and-support/troubleshoot/known-issues.md). ### Beta 14 Release Notes (2016-06-02 1.11.1-beta14) diff --git a/content/manuals/desktop/previous-versions/edge-releases-windows.md b/content/manuals/desktop/previous-versions/edge-releases-windows.md index b458ad0685c..ab7f67c7824 100644 --- a/content/manuals/desktop/previous-versions/edge-releases-windows.md +++ b/content/manuals/desktop/previous-versions/edge-releases-windows.md @@ -12,7 +12,7 @@ sitemap: false This page contains information about Docker Desktop Edge releases. Edge releases give you early access to our newest features. Note that some of the features may be experimental, and some of them may not ever reach the Stable release. For Docker Desktop system requirements, see -[What to know before you install](../install/windows-install.md#system-requirements). +[What to know before you install](/manuals/desktop/setup/install/windows-install.md#system-requirements). ## Docker Desktop Community 2.5.4 2020-12-07 @@ -74,7 +74,7 @@ This release contains a Kubernetes upgrade. Note that your local Kubernetes clus ### New -- If you have enabled [Vulnerability Scanning](../../docker-hub/vulnerability-scanning.md) in Docker Hub, the scan results will now appear in Docker Desktop. +- If you have enabled [Vulnerability Scanning](../../docker-hub/repos/manage/vulnerability-scanning.md) in Docker Hub, the scan results will now appear in Docker Desktop. ### Upgrades @@ -179,7 +179,7 @@ the `--privileged` flag. See [docker/for-win#8326](https://github.com/docker/for ### Bug fixes and minor changes -- Fixed an issue with Docker Desktop integration with other WSL 2 distros. See [docker/for-win#6894](https://github.com/docker/for-win/issues/6894) +- Fixed an issue with Docker Desktop integration with other WSL 2 distributions. See [docker/for-win#6894](https://github.com/docker/for-win/issues/6894) - Fixed DNS resolution of short names. See [docker/for-win#4425](https://github.com/docker/for-win/issues/4425) ## Docker Desktop Community 2.3.5.1 @@ -354,7 +354,7 @@ the `--privileged` flag. See [docker/for-win#8326](https://github.com/docker/for - Fixed an upgrade bug where users on versions still using the PowerShell-based VM management experience a silent un-installation crash leading to Docker Desktop being uninstalled instead of upgraded. - Fixed a crash when failing to login due to no Internet connection. - Fixed bug in handling shared volume paths with `..` characters. Fixes [docker/for-win#5375](https://github.com/docker/for-win/issues/5375). -- WSL 2: Docker Desktop detects when the wsl-distro is stopped and displays an actionable error message. +- WSL 2: Docker Desktop detects when the wsl-distribution is stopped and displays an actionable error message. - Fixed a bug in `ftruncate` which prevented [libgit2sharp](https://github.com/libgit2/libgit2sharp) from cloning repositories on shared volumes. See [docker/for-win#5808](https://github.com/docker/for-win/issues/5808#issuecomment-610996272). - Fixed a bug that caused starting and stopping of a Compose application from the UI to fail when the path contains whitespace. @@ -423,7 +423,7 @@ the `--privileged` flag. See [docker/for-win#8326](https://github.com/docker/for **WSL 2** - Docker Desktop only exposes host ports in Linux if the Windows port is available. -- Docker Desktop now allows users to refresh the list of Linux distros. +- Docker Desktop now allows users to refresh the list of Linux distributions. - Docker Desktop defaults to WSL 2 on install on compatible OS versions. - Docker Desktop detects missing Linux kernel and adds a pointer to the Microsoft documentation to download the kernel. @@ -480,7 +480,7 @@ This release contains a Kubernetes upgrade. Note that your local Kubernetes clus ### Bug fixes and minor changes - Added a prerequisite check in the installer for the `LanmanServer` service. Fixes [docker/for-win#5150](https://github.com/docker/for-win/issues/5150). -- DockerNAT has been removed from Docker Desktop as using an IP address to communicate from the host to a container is not a supported feature. To communicate from a container to the host, you must use the special DNS name `host.docker.internal`. We also recommend using ports to communicate from the host to a container. For more information, see [Networking](../networking.md). +- DockerNAT has been removed from Docker Desktop as using an IP address to communicate from the host to a container is not a supported feature. To communicate from a container to the host, you must use the special DNS name `host.docker.internal`. We also recommend using ports to communicate from the host to a container. For more information, see [Networking](/manuals/desktop/features/networking.md). - Ceph support has been removed from Docker Desktop to save disk space. - Fixed an issue that caused the Windows log file archive to grow indefinitely. Fixes [docker/for-win#5113](https://github.com/docker/for-win/issues/5113). @@ -516,7 +516,7 @@ This release contains a Kubernetes upgrade. Note that your local Kubernetes clus ### Known issues -- DockerNAT has been removed from Docker Desktop 2.2.0.0 as using an IP address to communicate from the host to a container is not a supported feature. To communicate from a container to the host, you must use the special DNS name `host.docker.internal`. We also recommend using ports to communicate from the host to a container. For more information, see [Networking](../networking.md). +- DockerNAT has been removed from Docker Desktop 2.2.0.0 as using an IP address to communicate from the host to a container is not a supported feature. To communicate from a container to the host, you must use the special DNS name `host.docker.internal`. We also recommend using ports to communicate from the host to a container. For more information, see [Networking](/manuals/desktop/features/networking.md). However, if your current setup relies on IP addresses for communication, you can use a temporary workaround to reinstate DockerNAT. To do this, open `C:\Program Files\Docker\Docker\resources\MobyLinux.ps1` and add `$SwitchName = "DockerNAT"` between line 175 and 176. Note that the temporary workaround to reinstate DockerNAT may be removed from future releases. @@ -594,8 +594,8 @@ Added the ability to start and stop Compose-based applications and view combined - Fixed a container start error when a container has more than one port with an arbitrary or not-yet-configured external port number. For example, `docker run -p 80 -p 443 nginx`). Fixes [docker/for-win#4935](https://github.com/docker/for-win/issues/4935) and [docker/compose#6998](https://github.com/docker/compose/issues/6998). - Fixed an issue which caused Docker Desktop to crash when resetting to factory defaults while running Windows containers. - Fixed multiple issues related to Fast Startup. -- Injected Docker CLI, CLI plugins, Docker Compose, Notary, and kubectl into WSL distros when Docker Desktop WSL integration is enabled. -- Fixed an issue where bind mounts created with Docker Compose from a WSL distro were incorrectly translated. Fixes [docker/for-win#5084](https://github.com/docker/for-win/issues/5084). +- Injected Docker CLI, CLI plugins, Docker Compose, Notary, and kubectl into WSL distributions when Docker Desktop WSL integration is enabled. +- Fixed an issue where bind mounts created with Docker Compose from a WSL distribution were incorrectly translated. Fixes [docker/for-win#5084](https://github.com/docker/for-win/issues/5084). - Docker Desktop now supports inotify events on shared filesystems for Windows file sharing. - Fixed a cache invalidation bug when a file in a shared volume is renamed on the host for Windows file sharing. - Fixed a handle leak when calling `Mknod` on a shared volume for Windows file sharing. @@ -624,7 +624,7 @@ This release contains a Kubernetes upgrade. Note that your local Kubernetes clus To access the Dashboard UI, select the Docker menu from the system tray and then click **Dashboard**. -- **WSL 2 backend:** The new Docker Desktop WSL 2 backend replaces the Docker Desktop WSL 2 Tech Preview. The WSL 2 backend architecture introduces support for Kubernetes, provides an updated Docker daemon, offers VPN-friendly networking, and additional features. For more information, see [Docker Desktop WSL 2 backend](../wsl/_index.md). +- **WSL 2 backend:** The new Docker Desktop WSL 2 backend replaces the Docker Desktop WSL 2 Tech Preview. The WSL 2 backend architecture introduces support for Kubernetes, provides an updated Docker daemon, offers VPN-friendly networking, and additional features. For more information, see [Docker Desktop WSL 2 backend](/manuals/desktop/features/wsl/_index.md). - **New file sharing implementation:** Docker Desktop introduces a new file sharing implementation which uses gRPC, FUSE, and Hypervisor sockets instead of Samba, CIFS, and Hyper-V networking. The new implementation offers improved I/O performance. Additionally, when using the new file system: @@ -699,7 +699,7 @@ This release contains a Kubernetes upgrade. Note that your local Kubernetes clus #### New -- [Docker Desktop WSL 2 Tech Preview](../wsl/_index.md) +- [Docker Desktop WSL 2 Tech Preview](/manuals/desktop/features/wsl/_index.md) #### Bug fixes and minor changes @@ -1094,7 +1094,7 @@ This release contains a Kubernetes upgrade. Note that your local Kubernetes clus - [Docker 18.02.0-ce-rc1](https://github.com/docker/docker-ce/releases/tag/v18.02.0-ce-rc1) * New - - Experimental Kubernetes Support. You can now run a single-node Kubernetes cluster from the "Kubernetes" Pane in Docker for Windows settings and use kubectl commands as well as docker commands. See [the Kubernetes section](../kubernetes.md). + - Experimental Kubernetes Support. You can now run a single-node Kubernetes cluster from the "Kubernetes" Pane in Docker for Windows settings and use kubectl commands as well as docker commands. See [the Kubernetes section](/manuals/desktop/features/kubernetes.md). - LCOW containers can now be run next to Windows containers (on Windows RS3 build 16299 and later). Use `--platform=linux` in Windows container mode to run Linux Containers On Windows. Note that LCOW is still experimental, and requires daemon `experimental` option. * Bug fixes and minor changes @@ -1276,9 +1276,10 @@ This release contains a Kubernetes upgrade. Note that your local Kubernetes clus TCP connection is idle for more than 5 minutes (related to [docker/for-mac#1374](https://github.com/docker/for-mac/issues/1374)) -> [!NOTE]: The link above goes to Docker for Mac issues because a -Mac user reported this problem, which applied to both Mac and Windows -and was fixed on both. +> [!NOTE] +> +> The link above goes to Docker for Mac issues because a +Mac user reported this problem, which applied to both Mac and Windows and was fixed on both. ### Docker Community Edition 17.07.0-rc3-win23 Release Notes (2017-08-21 17.07.0-win23) @@ -1626,7 +1627,9 @@ registry access (fixes [docker/for-win#569](https://github.com/docker/for-win/is ### Beta 36 Release Notes (2017-01-12 1.13.0-rc6-beta36) ->**Important Note:** Plugins installed using the experimental "managed plugins" feature in Docker 1.12 must be removed/uninstalled before upgrading. +> [!IMPORTANT] +> +> Plugins installed using the experimental "managed plugins" feature in Docker 1.12 must be removed/uninstalled before upgrading. **Upgrades** @@ -1640,7 +1643,9 @@ registry access (fixes [docker/for-win#569](https://github.com/docker/for-win/is ### Beta 35 Release Notes (2017-01-06 1.13.0-rc5-beta35) ->**Important Note:** Plugins installed using the experimental "managed plugins" feature in Docker 1.12 must be removed/uninstalled before upgrading. +> [!IMPORTANT] +> +> Plugins installed using the experimental "managed plugins" feature in Docker 1.12 must be removed/uninstalled before upgrading. **Upgrades** @@ -1669,7 +1674,9 @@ registry access (fixes [docker/for-win#569](https://github.com/docker/for-win/is ### Beta 33 Release Notes (2016-12-15 1.13.0-rc3-beta33) ->**Important Note:** Plugins installed using the experimental "managed plugins" feature in Docker 1.12 must be removed/uninstalled before upgrading. +> [!IMPORTANT] +> +> Plugins installed using the experimental "managed plugins" feature in Docker 1.12 must be removed/uninstalled before upgrading. **New** @@ -1686,7 +1693,9 @@ registry access (fixes [docker/for-win#569](https://github.com/docker/for-win/is ### Beta 32.1 Release Notes (2016-12-09 1.13.0-rc3-beta32.1) ->**Important Note:** Plugins installed using the experimental "managed plugins" feature in Docker 1.12 must be removed/uninstalled before upgrading. +> [!IMPORTANT] +> +> Plugins installed using the experimental "managed plugins" feature in Docker 1.12 must be removed/uninstalled before upgrading. **Hotfixes** @@ -1716,14 +1725,14 @@ registry access (fixes [docker/for-win#569](https://github.com/docker/for-win/is ### Beta 32 Release Notes (2016-12-07 1.13.0-rc3-beta32) ->**Important Note**: +> [!IMPORTANT] > -> Plugins installed using the experimental "managed plugins" feature in Docker 1.12 must be removed/uninstalled before upgrading. +> Plugins installed using the experimental "managed plugins" feature in Docker 1.12 must be removed/uninstalled before upgrading. **New** - Windows containers settings panel and options are working. In previous releases, settings were not implemented for -[Windows containers mode](../faqs/windowsfaqs.md#how-do-i-switch-between-windows-and-linux-containers). +[Windows containers mode](/manuals/desktop/troubleshoot-and-support/faqs/windowsfaqs.md#how-do-i-switch-between-windows-and-linux-containers). - Windows containers: Restart from the settings panel works - Windows containers: Factory default - Windows containers: `Daemon.json` can be modified @@ -1992,7 +2001,7 @@ work. Some insider builds may not work. **Known issues** * Only UTF-8 passwords are supported for host filesystem sharing -* Docker automatically disables lingering net adapters. The only way to remove them is manually using `devmgmt.msc` as documented in [Troubleshooting](../troubleshoot/known-issues.md). +* Docker automatically disables lingering net adapters. The only way to remove them is manually using `devmgmt.msc` as documented in [Troubleshooting](/manuals/desktop/troubleshoot-and-support/troubleshoot/known-issues.md). ### Beta 22 Release (2016-08-11 1.12.0-beta22) @@ -2000,13 +2009,13 @@ Unreleased. See Beta 23 for changes. **Known issues** -* Docker automatically disables lingering net adapters. The only way to remove them is manually using `devmgmt.msc` as documented in [Troubleshooting](../troubleshoot/known-issues.md). +* Docker automatically disables lingering net adapters. The only way to remove them is manually using `devmgmt.msc` as documented in [Troubleshooting](/manuals/desktop/troubleshoot-and-support/troubleshoot/known-issues.md). ### Beta 21 Release (2016-07-28 1.12.0-beta21) **New** -* Docker for Windows is now available from two channels: **stable** and **beta**. New features and bug fixes go out first in auto-updates to users in the beta channel. Updates to the stable channel are much less frequent and happen in sync with major and minor releases of the Docker engine. Only features that are well-tested and ready for production are added to the stable channel releases. For downloads of both and more information, see [Install Docker Desktop on Windows](../install/windows-install.md). +* Docker for Windows is now available from two channels: **stable** and **beta**. New features and bug fixes go out first in auto-updates to users in the beta channel. Updates to the stable channel are much less frequent and happen in sync with major and minor releases of the Docker Engine. Only features that are well-tested and ready for production are added to the stable channel releases. For downloads of both and more information, see [Install Docker Desktop on Windows](/manuals/desktop/setup/install/windows-install.md). * Removed the docker host name. Containers with exported ports are reachable via localhost. @@ -2070,7 +2079,9 @@ Unreleased. See Beta 23 for changes. ### Beta 18.1 Release (2016-07-07 1.12.0-rc3-beta18.1) ->**Note**: Docker 1.12.0 RC3 release introduces a backward incompatible change from RC2. You can fix this by recreating or updating your containers. +> [!NOTE] +> +> Docker 1.12.0 RC3 release introduces a backward incompatible change from RC2. You can fix this by recreating or updating your containers. **Hotfix** @@ -2275,11 +2286,11 @@ This Beta release includes some significant changes: * The GUI now runs in non-elevated mode and connects to an elevated Windows service * Allocate virtual machine memory by 256 MB increments, instead of 1 GB * Show a meaningful error when the user has an empty password -* Improved [Troubleshooting](../troubleshoot/_index.md) page +* Improved [Troubleshooting](/manuals/desktop/troubleshoot-and-support/troubleshoot/_index.md) page **Upgrades** -* docker-compose 1.7.1 (see changelog) +* docker-compose 1.7.1 (see [changelog](https://github.com/docker/compose/releases/tag/1.7.1)) * Kernel 4.4.9 **Bug fixes and minor changes** @@ -2299,7 +2310,7 @@ This Beta release includes some significant changes: **Known issues** -* Due to limitation in the Windows NAT implementation, co-existence with other NAT prefixes needs to be carefully managed. See [Troubleshooting](../troubleshoot/known-issues.md) for more details. +* Due to limitation in the Windows NAT implementation, co-existence with other NAT prefixes needs to be carefully managed. See [Troubleshooting](/manuals/desktop/troubleshoot-and-support/troubleshoot/known-issues.md) for more details. * Logs for the windows service are not aggregated with logs from the GUI. This is expected to be fixed in future versions. @@ -2327,7 +2338,7 @@ This Beta release includes some significant changes: **Known issues** -* Due to limitation in the Windows NAT implementation, co-existence with other NAT prefixes needs to be carefully managed. See [Troubleshooting](../troubleshoot/_index.md) for more details. +* Due to limitation in the Windows NAT implementation, co-existence with other NAT prefixes needs to be carefully managed. See [Troubleshooting](/manuals/desktop/troubleshoot-and-support/troubleshoot/_index.md) for more details. ### Beta 9 Release (2016-04-26 1.11.0-beta9) @@ -2493,7 +2504,9 @@ are working on a solution. * Fix msi version * Don't truncate Toolbox link ->**Note**: Docker for Windows skipped from Beta 1 to Beta 5 at this point to synch up the version numbering with Docker for Mac, which went into beta cycles a little earlier. +> [!NOTE] +> +> Docker for Windows skipped from Beta 1 to Beta 5 at this point to synch up the version numbering with Docker for Mac, which went into beta cycles a little earlier. ### Beta 1 Release (2016-03-24 1.10.6) diff --git a/content/manuals/desktop/release-notes.md b/content/manuals/desktop/release-notes.md index 7656dbbcc27..7e051dcb67d 100644 --- a/content/manuals/desktop/release-notes.md +++ b/content/manuals/desktop/release-notes.md @@ -17,12 +17,129 @@ aliases: weight: 220 --- -This page contains information about the new features, improvements, known issues, and bug fixes in Docker Desktop releases. For frequently asked questions about Docker Desktop releases, see [FAQs](faqs/releases.md). +This page contains information about the new features, improvements, known issues, and bug fixes in Docker Desktop releases. For frequently asked questions about Docker Desktop releases, see [FAQs](/manuals/desktop/troubleshoot-and-support/faqs/releases.md). Docker Desktop versions older than 6 months from the latest release are not available for download. Previous release notes are available in our [documentation repository](https://github.com/docker/docs/tree/main/content/manuals/desktop/previous-versions). Take a look at the [Docker Public Roadmap](https://github.com/orgs/docker/projects/51/views/1?filterQuery=) to see what's coming next. +## 4.37.1 + +{{< release-date date="2024-12-17" >}} + +{{< desktop-install-v2 all=true beta_win_arm=true version="4.37.1" build_path="/178610/" >}} + +### Bug fixes and enhancements + +#### For all platforms + +- Fixed an issue that caused the AI Catalog in Docker Hub to be unavailable in Docker Desktop. +- Fixed an issue that caused Docker Desktop to panic with `index out of range [0] with length 0` when using [Enhanced Container Isolation](/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/_index.md). + +## 4.37.0 + +{{< release-date date="2024-12-12" >}} + +{{< desktop-install-v2 all=true beta_win_arm=true version="4.37.0" build_path="/178034/" >}} + +### New + +- You can now perform key operations such as starting, stopping, restarting, and checking the status of Docker Desktop directly from the [command line](/manuals/desktop/features/desktop-cli.md) (Beta). +- The AI Catalog in Docker Hub is available directly through Docker Desktop. + +### Upgrades + +- [Docker Buildx v0.19.2](https://github.com/docker/buildx/releases/tag/v0.19.2) +- [Docker Compose v2.31.0](https://github.com/docker/compose/releases/tag/v2.31.0) +- [Docker Engine v27.4.0](https://docs.docker.com/engine/release-notes/27/#2740) +- [Docker Scout CLI v1.15.1](https://github.com/docker/scout-cli/releases/tag/v1.15.1) +- [NVIDIA Container Toolkit v1.17.2](https://github.com/NVIDIA/nvidia-container-toolkit/releases/tag/v1.17.2) + +### Bug fixes and enhancements + +#### For all platforms + +- The default disk usage limit for Docker Engine in new installations is now 1TB. +- Fixed an issue where containers could not establish loopback `AF_VSOCK` connections. +- Fixed a bug where resetting default settings would also reset the CLI context. +- Fixed a bug where the Docker Desktop Dashboard would get out of sync with the Docker daemon after restarting the engine while in Resource Saver mode (Windows with WSL2 backend only) or after switching engines (macOS). +- Fixed a bug where Resource Saver mode would fail to re-engage after restarting the engine while in Resource Saver mode. + +#### For Mac + +- Fixed a bug that would create certain user directories with root permission when running the uninstaller binary twice with `sudo`. + +#### For Windows + +- Added support for Windows on ARM using WSL 2 version 2.3.24 and later to single distribution mode on WSL 2. +- Fixed an issue where Docker Desktop would fail to start. Fixes [docker/for-win#14453](https://github.com/docker/for-win/issues/14453) + +### Known issues + +- Kubernetes cluster may not start if **Registry Access Manager** is enabled. As a workaround, add `registry.k8s.io` and `-docker.pkg.dev` to **Registry Access Management** policies. + +### Deprecation + +#### For Mac + +- QEMU (Legacy) as a VMM on Apple Silicon will be removed in a future version. It is recommended that you switch to the Apple Virtualization Framework for increased performance and stability. If you encounter an issue, [contact Docker Support](https://www.docker.com/support/) or [file a GitHub issue](https://github.com/docker/for-mac/issues). +- osxfs (Legacy) will be removed in a future version. It is recommended that you switch to VirtioFS for increased performance. If you encounter an issue, [contact Docker Support](https://www.docker.com/support/) or [file a GitHub issue](https://github.com/docker/for-mac/issues). + +## 4.36.0 + +{{< release-date date="2024-11-18" >}} + +{{< desktop-install-v2 all=true beta_win_arm=true version="4.36.0" build_path="/175267/" >}} + +### New + +- Existing Docker Desktop installations using the WSL2 engine on Windows are now automatically migrated to a unified single-distribution architecture for enhanced consistency and performance. +- Administrators can now: + - Enforce sign-in with macOS [configuration profiles](/manuals/security/for-admins/enforce-sign-in/methods.md#configuration-profiles-method-mac-only) (Early Access). + - Enforce sign-in for more than one organization at a time (Early Access). + - Deploy Docker Desktop for Mac in bulk with the [PKG installer](/manuals/desktop/setup/install/enterprise-deployment/pkg-install-and-configure.md) (Early Access). + - Use Desktop Settings Management to manage and enforce defaults via admin.docker.com (Early Access). +- Enhance Container Isolation (ECI) has been improved to: + - Allow admins to [turn off Docker socket mount restrictions](/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/config.md#allowing-all-containers-to-mount-the-docker-socket). + - Support wildcard tags when using the [`allowedDerivedImages` setting](/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/config.md#docker-socket-mount-permissions-for-derived-images). + +### Upgrades + +- [Docker Buildx v0.18.0](https://github.com/docker/buildx/releases/tag/v0.18.0) +- [Docker Compose v2.30.3](https://github.com/docker/compose/releases/tag/v2.30.3) +- [Kubernetes v1.30.5](https://github.com/kubernetes/kubernetes/releases/tag/v1.30.5) +- [NVIDIA Container Toolkit v1.17.0](https://github.com/NVIDIA/nvidia-container-toolkit/releases/tag/v1.17.0) +- [Docker Scout CLI v1.15.0](https://github.com/docker/scout-cli/releases/tag/v1.15.0) +- Docker Init v1.4.0 +- Linux kernel `v6.10.13` + +### Bug fixes and enhancements + +#### For all platforms + +- Fixed a bug where the `docker events` command would not terminate after streaming the events. +- Docker Init: Improved Dockerfile caching for PHP applications that don't use Docker Compose. +- Synchronized file shares now respects the `filesharingAllowedDirectories` setting in `admin-settings.json`. +- Fixed an issue where if Docker Desktop is configured to use a proxy, it fails to start due to an internal timeout while fetching authentication tokens. +- Added a recovery banner to retry an update if the download failed. +- Fixed an issue where if the `umask` is set to `577` it would cause `rpmbuild` failure. Fixes [docker/for-mac#6511](https://github.com/docker/for-mac/issues/6511). +- Fixed a bug that restricted containers using `--network=host` to 18 open host ports. +- Fixed bind mount ownership for non-root containers. Fixes [docker/for-mac#6243](https://github.com/docker/for-mac/issues/6243). +- Docker Desktop will not unpause automatically after a manual pause. The system will stay paused until you manually resume the Docker engine. This fixes a bug where other software would accidentally trigger a resume by running a CLI command in the background. Fixes [for-mac/#6908](https://github.com/docker/for-mac/issues/6908) + +#### For Mac + +- Fixed a bug in Docker VMM that prevented MySQL and other databases containers to start. Fixes reports from [docker/for-mac#7464](https://github.com/docker/for-mac/issues/7464). +- The minimum memory requirement is now automatically adjusted for Docker VMM, improving the user experience and addressing reports from [docker/for-mac#7464](https://github.com/docker/for-mac/issues/7464), [docker/for-mac#7482](https://github.com/docker/for-mac/issues/7482). +- Fixed a bug where the advanced option **Allowed privileged port mapping** was not working as expected. Fixes [docker/for-mac#7460](https://github.com/docker/for-mac/issues/7460). +- Docker Desktop can now automatically configure shell completion scripts for zsh, bash and fish inside the install wizard and settings screen. +- Fixed a bug where the in-app update would fail if Docker Desktop was installed by a non-admin user or if the current user was previously an administrator. Fixes [for-mac/#7403](https://github.com/docker/for-mac/issues/7403) and [for-mac/#6920](https://github.com/docker/for-mac/issues/6920) + +#### For Windows + +- Fixed a bug preventing UDP port 53 to be bound. +- Fixed a bug where Windows daemon options were overwritten at startup. + ## 4.35.1 {{< release-date date="2024-10-30" >}} @@ -41,7 +158,7 @@ Take a look at the [Docker Public Roadmap](https://github.com/orgs/docker/projec ### New -- Support for [Docker Desktop on Red Hat Enterprise Linux](/manuals/desktop/install/linux/rhel.md) is now generally available. +- Support for [Docker Desktop on Red Hat Enterprise Linux](/manuals/desktop/setup/install/linux/rhel.md) is now generally available. - Volume Backup and Share is now generally available and can be found in the **Volumes** view. - Terminal support within Docker Desktop using system shells is now generally available. - Beta release of Docker VMM - the more performant alternative to Apple Virtualization Framework on macOS (requires Apple Silicon and macOS 12.5 or later). @@ -164,8 +281,8 @@ Take a look at the [Docker Public Roadmap](https://github.com/orgs/docker/projec - [Host networking](/manuals/engine/network/drivers/host.md#docker-desktop) support on Docker Desktop is now generally available. - If you authenticate via the CLI, you can now authenticate through a browser-based flow, removing the need for manual PAT generation. -- Windows now supports automatic reclamation of disk space in Docker Desktop for WSL2 installations [using a managed virtual hard disk](/manuals/desktop/wsl/best-practices.md). -- Deploying Docker Desktop via the [MSI installer](/manuals/desktop/install/msi/_index.md) is now generally available. +- Windows now supports automatic reclamation of disk space in Docker Desktop for WSL2 installations [using a managed virtual hard disk](/manuals/desktop/features/wsl/best-practices.md). +- Deploying Docker Desktop via the [MSI installer](/manuals/desktop/setup/install/enterprise-deployment/msi-install-and-configure.md) is now generally available. - Two new methods to [enforce sign-in](/manuals/security/for-admins/enforce-sign-in/_index.md) (windows registry key and `.plist` file) are now generally available. - Fresh installations of Docker Desktop now use the containerd image store by default. - [Compose Bridge](/manuals/compose/bridge/_index.md) (Experimental) is now available from the Compose file viewer. Easily convert and deploy your Compose project to a Kubernetes cluster. @@ -202,7 +319,7 @@ Take a look at the [Docker Public Roadmap](https://github.com/orgs/docker/projec - Fixed a bug where Docker Desktop would reset docker's `credsStore` to `desktop` when the user's intention is to keep it empty. Fixes [docker/for-win#9843](https://github.com/docker/for-win/issues/9843). - Fixed a bug that would cause Docker Desktop to not start in the WSL2 engine [docker/for-win#14034](https://github.com/docker/for-win/issues/14034). -- Fixed a bug that caused WSL distro to terminate abruptly. Fixes [docker/for-win/14230](https://github.com/docker/for-win/issues/14230). +- Fixed a bug that caused WSL distribution to terminate abruptly. Fixes [docker/for-win/14230](https://github.com/docker/for-win/issues/14230). - Fixed an issue that caused WSL to update in each startup. Fixes [docker/for-win/13868](https://github.com/docker/for-win/issues/13868), [docker/for-win/13806](https://github.com/docker/for-win/issues/13806). ### Known issues @@ -239,7 +356,7 @@ Take a look at the [Docker Public Roadmap](https://github.com/orgs/docker/projec - [Docker Debug](/reference/cli/docker/debug.md) is now generally available. - BuildKit now evaluates Dockerfile rules to inform you of potential issues. - **Resource Allocation** settings can now be accessed directly from the resource usage data displayed in the Dashboard footer. -- New and improved experience for [troubleshooting](/manuals/desktop/troubleshoot/_index.md). +- New and improved experience for [troubleshooting](/manuals/desktop/troubleshoot-and-support/troubleshoot/_index.md). ### Upgrades @@ -275,7 +392,7 @@ Take a look at the [Docker Public Roadmap](https://github.com/orgs/docker/projec #### For Mac -- The Configuration integrity check feature now provides more context around what has changed with your Docker Desktop configuration. For more information, see the [FAQs](faqs/macfaqs.md). +- The Configuration integrity check feature now provides more context around what has changed with your Docker Desktop configuration. For more information, see the [FAQs](/manuals/desktop/troubleshoot-and-support/faqs/macfaqs.md). - The Configuration integrity check feature shows an error when it fails to repair Docker Desktop. - Fixed a bug where the IPv6 TCP was set to `host.docker.internal`. Fixes [docker/for-mac#7332](https://github.com/docker/for-mac/issues/7332). - Fixed an issue where the `docker-compose` symlink pointed to an empty location. Fixes [docker/for-mac#7345](https://github.com/docker/for-mac/issues/7345). @@ -347,7 +464,7 @@ For more information, see [microsoft/WSL#11794](https://github.com/microsoft/WSL #### For Windows - Fixed an issue on the WSL 2 engine where Docker Desktop would not detect the existence of the `docker-desktop-data` distribution if it had been manually moved by the user. -- The Windows on ARM installer and the [privileged service](/manuals/desktop/install/windows-permission-requirements.md#privileged-helper) are now built for ARM64. +- The Windows on ARM installer and the [privileged service](/manuals/desktop/setup/install/windows-permission-requirements.md#privileged-helper) are now built for ARM64. #### For Mac @@ -474,24 +591,22 @@ For more information, see [microsoft/WSL#11794](https://github.com/microsoft/WSL {{< release-date date="2024-05-06" >}} -{{< desktop-install all=true beta_win_arm=true version="4.30.0" build_path="/149282/" >}} - ### New #### For all platforms -- Docker Desktop now supports [SOCKS5 proxies](networking.md#socks5-proxy-support). Requires a Business subscription. +- Docker Desktop now supports [SOCKS5 proxies](/manuals/desktop/features/networking.md#socks5-proxy-support). Requires a Business subscription. - Added a new setting to manage the onboarding survey in [Settings Management](/manuals/security/for-admins/hardened-desktop/settings-management/_index.md). #### For Windows -- Added support for [Kerberos and NTLM proxy authentication](/manuals/desktop/settings.md#proxy-authentication) on Windows. Requires a Business subscription. +- Added support for [Kerberos and NTLM proxy authentication](/manuals/desktop/settings-and-maintenance/settings.md#proxy-authentication) on Windows. Requires a Business subscription. ### Upgrades - [Docker Compose v2.27.0](https://github.com/docker/compose/releases/tag/v2.27.0) - [Docker Engine v26.1.1](https://docs.docker.com/engine/release-notes/26.1/#2611) -- [Wasm](/manuals/desktop/wasm/_index.md) runtimes: +- [Wasm](/manuals/desktop/features/wasm.md) runtimes: - Updated `runwasi` shims to `v0.4.0` - Updated `deislabs` shims to `v0.11.1` - Updated `spin` shim to `v0.13.1` @@ -556,15 +671,13 @@ This can be resolved by adding the user to the **docker-users** group. Before st {{< release-date date="2024-04-08" >}} -{{< desktop-install all=true version="4.29.0" build_path="/145265/" >}} - ### New -- You can now enforce Rosetta usage via [Settings Management](/manuals/security/for-admins/hardened-desktop/settings-management/configure.md). +- You can now enforce Rosetta usage via [Settings Management](/manuals/security/for-admins/hardened-desktop/settings-management/_index.md). - [Docker socket mount restrictions](/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/config.md) with ECI is now generally available. - Docker Engine and CLI updated to [Moby 26.0](https://github.com/moby/moby/releases/tag/v26.0.0). This includes Buildkit 0.13, sub volumes mounts, networking updates, and improvements to the containerd multi-platform image store UX. - New and improved Docker Desktop error screens: swift troubleshooting, easy diagnostics uploads, and actionable remediation. -- Compose supports [Synchronized file shares (experimental)](synchronized-file-sharing.md). +- Compose supports [Synchronized file shares (experimental)](/manuals/desktop/features/synchronized-file-sharing.md). - New [interactive Compose CLI (experimental)](/manuals/compose/how-tos/environment-variables/envvars.md#compose_menu). - Beta release of: - Air-Gapped Containers with [Settings Management](/manuals/security/for-admins/hardened-desktop/air-gapped-containers/_index.md). @@ -592,7 +705,7 @@ This can be resolved by adding the user to the **docker-users** group. Before st - Fixed an issue with `.dockerignore` to avoid ignoring application files that start with "compose". - Improved how Java applications are started based on Spring Boot version. Fixes [docker/for-mac#7171](https://github.com/docker/for-mac/issues/7171). - Removed non-official Docker image used for Rust cross-compilation. -- The maximum number of files per [Synchronized file share](synchronized-file-sharing.md) now exceeds 2 million. +- The maximum number of files per [Synchronized file share](/manuals/desktop/features/synchronized-file-sharing.md) now exceeds 2 million. - Fixed an issue that caused the warning: "_The value provided to Autocomplete is invalid._" when selecting the **Export to local image** field. - **Run Cloud** can now be accessed from the Docker Desktop Dashboard. - Opting out from sending analytics will now also disable collecting data for bug reports. @@ -615,7 +728,7 @@ This can be resolved by adding the user to the **docker-users** group. Before st #### For Windows - Fixed a bug where `docker run -v` would fail after switching between WSL 2 and Hyper-V. -- Fixed a bug where Docker Desktop was not stopping its WSL distros (`docker-desktop` and `docker-desktop-data`) when it was shutdown. Fixes [docker/for-win/issues/13443](https://github.com/docker/for-win/issues/13443) and [docker/for-win/issues/13938](https://github.com/docker/for-win/issues/13938). +- Fixed a bug where Docker Desktop was not stopping its WSL distributions (`docker-desktop` and `docker-desktop-data`) when it was shutdown. Fixes [docker/for-win/issues/13443](https://github.com/docker/for-win/issues/13443) and [docker/for-win/issues/13938](https://github.com/docker/for-win/issues/13938). #### For Linux @@ -639,7 +752,7 @@ This can be resolved by adding the user to the **docker-users** group. Before st ### New - [Settings Management](/manuals/security/for-admins/hardened-desktop/settings-management/_index.md) now allows admins to set the default file-sharing implementation and specify which paths developer can add file shares to. -- Added support for `socks5://` HTTP and HTTPS proxy URLs when the [`SOCKS` proxy support beta feature](networking.md) is enabled. +- Added support for `socks5://` HTTP and HTTPS proxy URLs when the [`SOCKS` proxy support beta feature](/manuals/desktop/features/networking.md) is enabled. - Users can now filter volumes to see which ones are in use in the **Volumes** tab. ### Upgrades @@ -648,7 +761,7 @@ This can be resolved by adding the user to the **docker-users** group. Before st - [Docker Engine v25.0.3](https://docs.docker.com/engine/release-notes/25.0/#2503) - [Docker Scout CLI v1.5.0](https://github.com/docker/scout-cli/releases/tag/v1.5.0) - [Qemu 8.1.5](https://wiki.qemu.org/ChangeLog/8.1) -- [Wasm](/manuals/desktop/wasm/_index.md) runtimes: +- [Wasm](/manuals/desktop/features/wasm.md) runtimes: - Updated runwasi shims to `v0.4.0`, including: - wasmtime `v17.0`, with initial support for WASI preview 2 - wasmedge `v0.13.5` @@ -689,7 +802,7 @@ This can be resolved by adding the user to the **docker-users** group. Before st #### For Windows - Fixed an issue with DNS timeouts on Windows. -- Added support for Enhanced Container Isolation Docker socket mount permission on WSL user distros. +- Added support for Enhanced Container Isolation Docker socket mount permission on WSL user distributions. - Fixed an issue that caused the `failed to get console mode` error when redirecting output from the CLI. - Fixed an issue with the engine socket permissions when mounted inside containers. Fixes [docker/for-win#13898](https://github.com/docker/for-win/issues/13898) @@ -756,9 +869,9 @@ This can be resolved by adding the user to the **docker-users** group. Before st ### New - Docker init now supports Java and is generally available to all users. -- [Synchronized File Shares](synchronized-file-sharing.md) provides fast and flexible host-to-VM file sharing within Docker Desktop. Utilizing the technology behind [Docker’s acquisition of Mutagen](https://www.docker.com/blog/mutagen-acquisition/), this feature provides an alternative to virtual bind mounts that uses synchronized filesystem caches, improving performance for developers working with large codebases. +- [Synchronized File Shares](/manuals/desktop/features/synchronized-file-sharing.md) provides fast and flexible host-to-VM file sharing within Docker Desktop. Utilizing the technology behind [Docker’s acquisition of Mutagen](https://www.docker.com/blog/mutagen-acquisition/), this feature provides an alternative to virtual bind mounts that uses synchronized filesystem caches, improving performance for developers working with large codebases. - Organization admins can now [configure Docker socket mount permissions](/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/config.md) when ECI is enabled. -- [Containerd Image Store](containerd.md) support is now generally available to all users. +- [Containerd Image Store](/manuals/desktop/features/containerd.md) support is now generally available to all users. - Get a debug shell into any container or image with the new [`docker debug` command](/reference/cli/docker/debug.md) (Beta). - Organization admins, with a Docker Business subscription, can now configure a custom list of extensions with [Private Extensions Marketplace](/manuals/extensions/private-marketplace.md) enabled (Beta) @@ -858,7 +971,7 @@ This can be resolved by adding the user to the **docker-users** group. Before st ### New -- Administrators can now control access to beta and experimental features in the **Features in development** tab with [Settings Management](/manuals/security/for-admins/hardened-desktop/settings-management/configure.md). +- Administrators can now control access to beta and experimental features in the **Features in development** tab with [Settings Management](/manuals/security/for-admins/hardened-desktop/settings-management/_index.md). - Introduced four new version update states in the footer. - `docker init` (Beta) now supports PHP with Apache + Composer. - The [**Builds** view](use-desktop/builds.md) is now GA. You can now inspect builds, troubleshoot errors, and optimize build speed. @@ -868,7 +981,7 @@ This can be resolved by adding the user to the **docker-users** group. Before st - [Compose v2.23.3](https://github.com/docker/compose/releases/tag/v2.23.3) - [Docker Scout CLI v1.2.0](https://github.com/docker/scout-cli/releases/tag/v1.2.0). - [Buildx v0.12.0](https://github.com/docker/buildx/releases/tag/v0.12.0) -- [Wasm](/manuals/desktop/wasm/_index.md) runtimes: +- [Wasm](/manuals/desktop/features/wasm.md) runtimes: - wasmtime, wasmedge and wasmer `v0.3.1`. - lunatic, slight, spin, and wws `v0.10.0`. - Wasmtime is now based on wasmtime `v14.0` and supports wasi preview-2 components @@ -965,10 +1078,10 @@ This can be resolved by adding the user to the **docker-users** group. Before st ### New -- Rosetta is now Generally Available for all users on macOS 13 or later. It provides faster emulation of Intel-based images on Apple Silicon. To use Rosetta, see [Settings](/manuals/desktop/settings.md). Rosetta is enabled by default on macOS 14.1 and later. +- Rosetta is now Generally Available for all users on macOS 13 or later. It provides faster emulation of Intel-based images on Apple Silicon. To use Rosetta, see [Settings](/manuals/desktop/settings-and-maintenance/settings.md). Rosetta is enabled by default on macOS 14.1 and later. - Docker Desktop now detects if a WSL version is out of date. If an out dated version of WSL is detected, you can allow Docker Desktop to automatically update the installation or you can manually update WSL outside of Docker Desktop. - New installations of Docker Desktop for Windows now require a Windows version of 19044 or later. -- Administrators now have the ability to control Docker Scout image analysis in [Settings Management](/manuals/security/for-admins/hardened-desktop/settings-management/configure.md). +- Administrators now have the ability to control Docker Scout image analysis in [Settings Management](/manuals/security/for-admins/hardened-desktop/settings-management/_index.md). ### Upgrades @@ -1026,7 +1139,7 @@ This can be resolved by adding the user to the **docker-users** group. Before st #### For Windows -- **Switch to Windows containers** option in the tray menu may not show up on Windows. As a workaround, edit the [`settings.json` file](/manuals/desktop/settings.md) and set `"displaySwitchWinLinContainers": true`. +- **Switch to Windows containers** option in the tray menu may not show up on Windows. As a workaround, edit the [`settings.json` file](/manuals/desktop/settings-and-maintenance/settings.md) and set `"displaySwitchWinLinContainers": true`. #### For all platforms @@ -1070,7 +1183,7 @@ This can be resolved by adding the user to the **docker-users** group. Before st - [Compose v2.22.0](https://github.com/docker/compose/releases/tag/v2.22.0) - [Go 1.21.1](https://github.com/golang/go/releases/tag/go1.21.1) -- [Wasm](/manuals/desktop/wasm.md) runtimes: +- [Wasm](/manuals/desktop/features/wasm.md) runtimes: - wasmtime, wasmedge `v0.2.0`. - lunatic, slight, spin, and wws`v0.9.1`. - Added wasmer wasm shims. @@ -1131,7 +1244,7 @@ This can be resolved by adding the user to the **docker-users** group. Before st - [Compose v2.21.0](https://github.com/docker/compose/releases/tag/v2.21.0) - [Docker Engine v24.0.6](https://docs.docker.com/engine/release-notes/24.0/#2406) - [Docker Scout CLI v0.24.1](https://github.com/docker/scout-cli/releases/tag/v0.24.1). -- [Wasm](/manuals/desktop/wasm.md) runtimes: +- [Wasm](/manuals/desktop/features/wasm.md) runtimes: - wasmtime, wasmedge revision `d0a1a1cd`. - slight and spin wasm `v0.9.0`. @@ -1250,13 +1363,13 @@ This can be resolved by adding the user to the **docker-users** group. Before st #### For Mac - Fixed a bug that prevented Docker Desktop from starting. [docker/for-mac#6890](https://github.com/docker/for-mac/issues/6890) -- Resource Saver is now available on Mac. It optimises Docker Desktop's usage of your system resources when no containers are running. To access this feature, make sure you have [turned on access to experimental features](/manuals/desktop/settings.md) in settings. +- Resource Saver is now available on Mac. It optimises Docker Desktop's usage of your system resources when no containers are running. To access this feature, make sure you have [turned on access to experimental features](/manuals/desktop/settings-and-maintenance/settings.md) in settings. #### For Windows - Fixed a bug where the self-diagnose tool showed a false-positive failure when vpnkit is expected to be not running. Fixes [docker/for-win#13479](https://github.com/docker/for-win/issues/13479). - Fixed a bug where an invalid regular expression in the search bar caused an error. Fixes [docker/for-win#13592](https://github.com/docker/for-win/issues/13592). -- Resource Saver is now available on Windows Hyper-V. It optimises Docker Desktop's usage of your system resources when no containers are running. To access this feature, make sure you have [turned on access to experimental features](/manuals/desktop/settings.md) in settings. +- Resource Saver is now available on Windows Hyper-V. It optimises Docker Desktop's usage of your system resources when no containers are running. To access this feature, make sure you have [turned on access to experimental features](/manuals/desktop/settings-and-maintenance/settings.md) in settings. ## 4.21.1 @@ -1312,13 +1425,13 @@ This can be resolved by adding the user to the **docker-users** group. Before st - Fixed a bug on WSL 2 where if Desktop is paused, killed, and then restarted, the startup hangs unless WSL is shut down first with `wsl --shutdown`. - Fixed the WSL engine in cases where wsl.exe is not on the PATH [docker/for-win#13547](https://github.com/docker/for-win/issues/13547). -- Fixed the WSL engine's ability to detect cases where one of the Docker Desktop distros' drive is missing [docker/for-win#13554](https://github.com/docker/for-win/issues/13554). +- Fixed the WSL engine's ability to detect cases where one of the Docker Desktop distributions' drive is missing [docker/for-win#13554](https://github.com/docker/for-win/issues/13554). - A slow or unresponsive WSL integration no longer prevents Docker Desktop from starting. Fixes [docker/for-win#13549](https://github.com/docker/for-win/issues/13549). - Fixed a bug that caused Docker Desktop to crash on startup [docker/for-win#6890](https://github.com/docker/for-mac/issues/6890). - Added the following installer flags: - `--hyper-v-default-data-root` which specifies the default location for Hyper-V VM disk. - `--windows-containers-default-data-root` which specifies the default data root for Windows Containers. - - `--wsl-default-data-root` which specifies the default location for WSL distro disks. + - `--wsl-default-data-root` which specifies the default location for WSL distribution disks. ## 4.20.1 @@ -1367,8 +1480,8 @@ This can be resolved by adding the user to the **docker-users** group. Before st #### For Windows - Fixed a bug that meant WSL data could not be moved to a different disk. Fixes [docker/for-win#13269](https://github.com/docker/for-win/issues/13269). -- Fixed a bug where Docker Desktop was not stopping its WSL distros (docker-desktop and docker-desktop-data) when it was shutdown, consuming host memory unnecessarily. -- Added a new setting that allows the Windows Docker daemon to use Docker Desktop's internal proxy when running Windows containers. See [Windows proxy settings](/manuals/desktop/settings.md#proxies). +- Fixed a bug where Docker Desktop was not stopping its WSL distributions (docker-desktop and docker-desktop-data) when it was shutdown, consuming host memory unnecessarily. +- Added a new setting that allows the Windows Docker daemon to use Docker Desktop's internal proxy when running Windows containers. See [Windows proxy settings](/manuals/desktop/settings-and-maintenance/settings.md#proxies). #### For Linux @@ -1406,7 +1519,7 @@ This can be resolved by adding the user to the **docker-users** group. Before st - Improved `docker scout compare` command to compare two images, now also aliased under `docker scout diff`. - Added more details to dashboard errors when a `docker-compose` action fails ([docker/for-win#13378](https://github.com/docker/for-win/issues/13378)). -- Added support for setting HTTP proxy configuration during installation. This can be done via the `--proxy-http-mode`, `--overrider-proxy-http`, `--override-proxy-https` and `--override-proxy-exclude` installer flags in the case of installation from the CLI on [Mac](install/mac-install.md#install-from-the-command-line) and [Windows](install/windows-install.md#install-from-the-command-line), or alternatively by setting the values in the `install-settings.json` file. +- Added support for setting HTTP proxy configuration during installation. This can be done via the `--proxy-http-mode`, `--overrider-proxy-http`, `--override-proxy-https` and `--override-proxy-exclude` installer flags in the case of installation from the CLI on [Mac](/manuals/desktop/setup/install/mac-install.md#install-from-the-command-line) and [Windows](/manuals/desktop/setup/install/windows-install.md#install-from-the-command-line), or alternatively by setting the values in the `install-settings.json` file. - Docker Desktop now stops overriding .docker/config.json `credsStore` keys on application start. Note that if you use a custom credential helper then the CLI `docker login` and `docker logout` does not affect whether the UI is signed in to Docker or not. In general, it is better to sign into Docker via the UI since the UI supports multi-factor authentication. - Added a warning about the [forthcoming removal of Compose V1 from Docker Desktop](/manuals/compose/releases/migrate.md). Can be suppressed with `COMPOSE_V1_EOL_SILENT=1`. - In the Compose config, boolean fields in YAML should be either `true` or `false`. Deprecated YAML 1.1 values such as “on” or “no” now produce a warning. @@ -1581,11 +1694,11 @@ This can be resolved by adding the user to the **docker-users** group. Before st ### For Windows -- Added statical linking of WSL integration tools against `musl` so there is no need to install `alpine-pkg-glibc` in user distros. +- Added statical linking of WSL integration tools against `musl` so there is no need to install `alpine-pkg-glibc` in user distributions. - Added support for running under cgroupv2 on WSL 2. This is activated by adding `kernelCommandLine = systemd.unified_cgroup_hierarchy=1 cgroup_no_v1=all` to your `%USERPROFILE%\.wslconfig` file in the `[wsl2]` section. - Fixed an issue that caused Docker Desktop to get stuck in the "starting" phase when in WSL 2 mode (introduced in 4.16). - Fixed Docker Desktop failing to start the WSL 2 backend when file system compression or encryption is enabled on `%LOCALAPPDATA%`. -- Fixed Docker Desktop failing to report a missing or outdated (incapable of running WSL version 2 distros) WSL installation when starting. +- Fixed Docker Desktop failing to report a missing or outdated (incapable of running WSL version 2 distributions) WSL installation when starting. - Fixed a bug where opening in Visual Studio Code fails if the target path has a space. - Fixed a bug that causes `~/.docker/context` corruption and the error message "unexpected end of JSON input". You can also remove `~/.docker/context` to work around this problem. - Ensured the credential helper used in WSL 2 is properly signed. Related to [docker/for-win#10247](https://github.com/docker/for-win/issues/10247). @@ -1715,7 +1828,7 @@ This can be resolved by adding the user to the **docker-users** group. Before st - Substantial performance improvements for macOS users with the option of enabling the new VirtioFS file sharing technology. Available for macOS 12.5 and above. - Docker Desktop for Mac no longer needs to install the privileged helper process `com.docker.vmnetd` on install or on the first run. For more information see [Permission requirements for Mac](https://docs.docker.com/desktop/mac/permission-requirements/). -- Added [WebAssembly capabilities](wasm/_index.md). Use with the [containerd integration](containerd/_index.md). +- Added [WebAssembly capabilities](/manuals/desktop/features/wasm.md). Use with the [containerd integration](/manuals/desktop/features/containerd.md). - Improved the descriptions for beta and experimental settings to clearly explain the differences and how people can access them. - Available disk space of VM now displays in the footer of Docker Desktop Dashboard for Mac and Linux. - A disk space warning now displays in the footer if available space is below 3GB. @@ -2012,7 +2125,7 @@ This can be resolved by adding the user to the **docker-users** group. Before st #### For Windows -- Fixed `docker login` to private registries from WSL2 distro [docker/for-win#12871](https://github.com/docker/for-win/issues/12871) +- Fixed `docker login` to private registries from WSL2 distribution [docker/for-win#12871](https://github.com/docker/for-win/issues/12871) ## 4.11.0 @@ -2020,7 +2133,7 @@ This can be resolved by adding the user to the **docker-users** group. Before st ### New -- Docker Desktop is now fully supported for Docker Business customers inside VMware ESXi and Azure VMs. For more information, see [Run Docker Desktop inside a VM or VDI environment](/manuals/desktop/vm-vdi.md) +- Docker Desktop is now fully supported for Docker Business customers inside VMware ESXi and Azure VMs. For more information, see [Run Docker Desktop inside a VM or VDI environment](/manuals/desktop/setup/vm-vdi.md) - Added two new extensions ([vcluster](https://hub.docker.com/extensions/loftsh/vcluster-dd-extension) and [PGAdmin4](https://hub.docker.com/extensions/mochoa/pgadmin4-docker-extension)) to the Extensions Marketplace. - The ability to sort extensions has been added to the Extensions Marketplace. - Fixed a bug that caused some users to be asked for feedback too frequently. You'll now only be asked for feedback twice a year. @@ -2238,7 +2351,7 @@ This can be resolved by adding the user to the **docker-users** group. Before st ### New -- Released [Docker Desktop for Linux](/manuals/desktop/install/linux/_index.md). +- Released [Docker Desktop for Linux](/manuals/desktop/setup/install/linux/_index.md). - Beta release of [Docker Extensions](/manuals/extensions/_index.md) and Extensions SDK. - Created a Docker Homepage where you can run popular images and discover how to use them. - [Compose V2 is now GA](https://www.docker.com/blog/announcing-compose-v2-general-availability/) @@ -2259,7 +2372,7 @@ This can be resolved by adding the user to the **docker-users** group. Before st ### New -- Released [Docker Desktop for Linux](/manuals/desktop/install/linux/_index.md). +- Released [Docker Desktop for Linux](/manuals/desktop/setup/install/linux/_index.md). - Beta release of [Docker Extensions](/manuals/extensions/_index.md) and Extensions SDK. - Created a Docker Homepage where you can run popular images and discover how to use them. - [Compose V2 is now GA](https://www.docker.com/blog/announcing-compose-v2-general-availability/) @@ -2397,7 +2510,7 @@ This can be resolved by adding the user to the **docker-users** group. Before st #### For Mac -- Docker Desktop 4.6.0 gives macOS users the option of enabling a new experimental file sharing technology called VirtioFS. During testing VirtioFS has been shown to drastically reduce the time taken to sync changes between the host and VM, leading to substantial performance improvements. For more information, see [VirtioFS](/manuals/desktop/settings.md#beta-features). +- Docker Desktop 4.6.0 gives macOS users the option of enabling a new experimental file sharing technology called VirtioFS. During testing VirtioFS has been shown to drastically reduce the time taken to sync changes between the host and VM, leading to substantial performance improvements. For more information, see [VirtioFS](/manuals/desktop/settings-and-maintenance/settings.md#beta-features). ### Updates @@ -2676,7 +2789,7 @@ CVE-2021-44228](https://www.docker.com/blog/apache-log4j-2-cve-2021-44228/). #### For Mac -- Docker Desktop on Apple silicon no longer requires Rosetta 2, with the exception of [three optional command line tools](troubleshoot/known-issues.md). +- Docker Desktop on Apple silicon no longer requires Rosetta 2, with the exception of [three optional command line tools](/manuals/desktop/troubleshoot-and-support/troubleshoot/known-issues.md). #### For Windows @@ -2758,7 +2871,7 @@ actual memory usage. See #### For Windows -- Fixed a regression in WSL 2 integrations for some distros (e.g. Arch or Alpine). Fixes [docker/for-win#12229](https://github.com/docker/for-win/issues/12229) +- Fixed a regression in WSL 2 integrations for some distributions (e.g. Arch or Alpine). Fixes [docker/for-win#12229](https://github.com/docker/for-win/issues/12229) - Fixed update notification overlay sometimes getting out of sync between the Settings button and the Software update button in the Dashboard. ## 4.1.0 @@ -2779,7 +2892,7 @@ actual memory usage. See - [Go 1.17.1](https://github.com/golang/go/releases/tag/go1.17.1) - [Alpine 3.14](https://alpinelinux.org/posts/Alpine-3.14.0-released.html) - [Qemu 6.1.0](https://wiki.qemu.org/ChangeLog/6.1) -- Base distro to debian:bullseye +- Base distribution to debian:bullseye ### Bug fixes and minor changes @@ -2791,7 +2904,7 @@ actual memory usage. See - Fixed CLI context switch sync with UI. See [docker/for-win#11721](https://github.com/docker/for-win/issues/11721). - Added the key `vpnKitMaxPortIdleTime` to `settings.json` to allow the idle network connection timeout to be disabled or extended. - Fixed a crash on exit. See [docker/for-win#12128](https://github.com/docker/for-win/issues/12128). -- Fixed a bug where the CLI tools would not be available in WSL 2 distros. +- Fixed a bug where the CLI tools would not be available in WSL 2 distributions. - Fixed switching from Linux to Windows containers that was stuck because access rights on panic.log. See [for-win#11899](https://github.com/docker/for-win/issues/11899). ### Known Issues @@ -2857,5 +2970,5 @@ For more information, see [Docker subscription overview](../subscription/_index. #### For Windows -- Fixed a bug where the CLI tools would not be available in WSL 2 distros. +- Fixed a bug where the CLI tools would not be available in WSL 2 distributions. - Fixed a bug when switching from Linux to Windows containers due to access rights on `panic.log`. [for-win#11899](https://github.com/docker/for-win/issues/11899) diff --git a/content/manuals/desktop/settings-and-maintenance/_index.md b/content/manuals/desktop/settings-and-maintenance/_index.md new file mode 100644 index 00000000000..22c1acffff4 --- /dev/null +++ b/content/manuals/desktop/settings-and-maintenance/_index.md @@ -0,0 +1,6 @@ +--- +build: + render: never +title: Settings and maintenance +weight: 40 +--- \ No newline at end of file diff --git a/content/manuals/desktop/backup-and-restore.md b/content/manuals/desktop/settings-and-maintenance/backup-and-restore.md similarity index 91% rename from content/manuals/desktop/backup-and-restore.md rename to content/manuals/desktop/settings-and-maintenance/backup-and-restore.md index dcd326ad863..b985426334c 100644 --- a/content/manuals/desktop/backup-and-restore.md +++ b/content/manuals/desktop/settings-and-maintenance/backup-and-restore.md @@ -2,7 +2,9 @@ title: How to back up and restore your Docker Desktop data keywords: Docker Desktop, backup, restore, migration, reinstall, containers, images, volumes -weight: 130 +weight: 20 +aliases: + - /desktop/backup-and-restore.md --- Use the following procedure to save and restore your images and container data. This is useful if you want to reset your VM disk or to move your Docker environment to a new @@ -27,16 +29,16 @@ computer, for example. If you used a [named volume](/manuals/engine/storage/_index.md#more-details-about-mount-types) to store container data, such as databases, refer to the [back up, restore, or migrate data volumes](/manuals/engine/storage/volumes.md#back-up-restore-or-migrate-data-volumes) page in the storage section. 2. Use [`docker push`](/reference/cli/docker/image/push.md) to push any - images you have built locally and want to keep to the [Docker Hub registry](../docker-hub/_index.md). + images you have built locally and want to keep to the [Docker Hub registry](/manuals/docker-hub/_index.md). - Make sure to configure the [repository's visibility as "private"](../docker-hub/repos/_index.md) + Make sure to configure the [repository's visibility as "private"](/manuals/docker-hub/repos/_index.md) for images that should not be publicly accessible. Alternatively, use [`docker image save -o images.tar image1 [image2 ...]`](/reference/cli/docker/image/save.md) to save any images you want to keep to a local tar file. After backing up your data, you can uninstall the current version of Docker Desktop -and [install a different version](release-notes.md) or reset Docker Desktop to factory defaults. +and [install a different version](/manuals/desktop/release-notes.md) or reset Docker Desktop to factory defaults. ## Restore your data diff --git a/content/manuals/desktop/settings.md b/content/manuals/desktop/settings-and-maintenance/settings.md similarity index 94% rename from content/manuals/desktop/settings.md rename to content/manuals/desktop/settings-and-maintenance/settings.md index b508546d0e2..9080ee5e2e8 100644 --- a/content/manuals/desktop/settings.md +++ b/content/manuals/desktop/settings-and-maintenance/settings.md @@ -8,12 +8,13 @@ aliases: - /desktop/settings/mac/ - /desktop/settings/windows/ - /desktop/settings/linux/ -weight: 160 + - /desktop/settings/ +weight: 10 --- To navigate to **Settings** either: -- Select the Docker menu {{< inline-image src="images/whale-x.svg" alt="whale menu" >}} and then **Settings** +- Select the Docker menu {{< inline-image src="../images/whale-x.svg" alt="whale menu" >}} and then **Settings** - Select the **Settings** icon from the Docker Desktop Dashboard. You can also locate the `settings-store.json` file (or `settings.json` for Docker Desktop versions 4.34 and earlier) at: @@ -49,7 +50,7 @@ If you choose the integrated terminal, you can run commands in a running contain execution attacks. - {{< badge color=blue text="Windows only" >}}**Use the WSL 2 based engine**. WSL 2 provides better performance than the - Hyper-V backend. For more information, see [Docker Desktop WSL 2 backend](/manuals/desktop/wsl/_index.md). + Hyper-V backend. For more information, see [Docker Desktop WSL 2 backend](/manuals/desktop/features/wsl/_index.md). - {{< badge color=blue text="Windows only" >}}**Add the `*.docker.internal` names to the host's `/etc/hosts` file (Password required)**. Lets you resolve `*.docker.internal` DNS names from both the host and your containers. @@ -57,7 +58,7 @@ If you choose the integrated terminal, you can run commands in a running contain Turns on the containerd image store. This brings new features like faster container startup performance by lazy-pulling images, and the ability to run Wasm applications with Docker. - For more information, see [containerd image store](containerd.md). + For more information, see [containerd image store](/manuals/desktop/features/containerd.md). - {{< badge color=blue text="Mac only" >}} **Choose Virtual Machine Manager (VMM)**. Choose the Virtual Machine Manager for creating and managing the Docker Desktop Linux VM. - Select **Docker VMM** for the latest and most performant Hypervisor/Virtual Machine Manager. This option is available only on Apple Silicon Macs running macOS 12.5 or later and is currently in Beta. @@ -66,7 +67,7 @@ If you choose the integrated terminal, you can run commands in a running contain > Turn this setting on to make Docker Desktop run faster. - Alternatively, you can choose **Apple Virtualization framework**, **QEMU** (for Apple Silicon), or **HyperKit** (for Intel Macs). For macOS 12.5 and later, Apple Virtualization framework is the default setting. - For more information, see [Virtual Machine Manager](/manuals/desktop/vmm.md). + For more information, see [Virtual Machine Manager](/manuals/desktop/features/vmm.md). - {{< badge color=blue text="Mac only" >}}**Choose file sharing implementation for your containers**. Choose whether you want to share files using **VirtioFS**, **gRPC FUSE**, or **osxfs (Legacy)**. VirtioFS is only available for macOS 12.5 and later, and is turned on by default. > [!TIP] @@ -98,7 +99,7 @@ If you choose the integrated terminal, you can run commands in a running contain - The symlink of the default Docker socket. Additionally, Docker Desktop ensures that the context is switched to `desktop-linux` on startup. - You are notified if changes are found and are able to restore the configuration directly from the notification. For more information, see the [FAQs](/manuals/desktop/faqs/macfaqs.md#why-do-i-keep-getting-a-notification-telling-me-an-application-has-changed-my-desktop-configurations). + You are notified if changes are found and are able to restore the configuration directly from the notification. For more information, see the [FAQs](/manuals/desktop/troubleshoot-and-support/faqs/macfaqs.md#why-do-i-keep-getting-a-notification-telling-me-an-application-has-changed-my-desktop-configurations). ## Resources @@ -170,7 +171,7 @@ the host while running and testing the code in a container. Synchronized file shares is an alternative file sharing mechanism that provides fast and flexible host-to-VM file sharing, enhancing bind mount performance through the use of synchronized filesystem caches. Available with Pro, Team, and Business subscriptions. -To learn more, see [Synchronized file share](/manuals/desktop/synchronized-file-sharing.md). +To learn more, see [Synchronized file share](/manuals/desktop/features/synchronized-file-sharing.md). #### Virtual file shares @@ -213,7 +214,7 @@ File share settings are: > once a file called `test` is created, attempts to create a second file called > `Test` will fail. > -> For more information, see [Volume mounting requires file sharing for any project directories outside of `/Users`](/manuals/desktop/troubleshoot/topics.md) +> For more information, see [Volume mounting requires file sharing for any project directories outside of `/Users`](/manuals/desktop/troubleshoot-and-support/troubleshoot/topics.md) #### Shared folders on demand @@ -226,11 +227,11 @@ popup asking if you want to share the specified folder. You can select to **Share it**, in which case it is added to your Docker Desktop Shared Folders list and available to containers. Alternatively, you can opt not to share it by selecting **Cancel**. -![Shared folder on demand](images/shared-folder-on-demand.png) +![Shared folder on demand](../images/shared-folder-on-demand.png) ### Proxies -Docker Desktop supports the use of HTTP/HTTPS and [SOCKS5 proxies](/manuals/desktop/networking.md#socks5-proxy-support). +Docker Desktop supports the use of HTTP/HTTPS and [SOCKS5 proxies](/manuals/desktop/features/networking.md#socks5-proxy-support). HTTP/HTTPS proxies can be used when: @@ -312,13 +313,13 @@ On Windows in WSL 2 mode, you can configure which WSL 2 distributions will have WSL integration. By default, the integration is enabled on your default WSL distribution. -To change your default WSL distro, run `wsl --set-default `. (For example, -to set Ubuntu as your default WSL distro, run `wsl --set-default ubuntu`). +To change your default WSL distribution, run `wsl --set-default `. (For example, +to set Ubuntu as your default WSL distribution, run `wsl --set-default ubuntu`). You can also select any additional distributions you would like to enable the WSL 2 integration on. For more details on configuring Docker Desktop to use WSL 2, see -[Docker Desktop WSL 2 backend](/manuals/desktop/wsl/_index.md). +[Docker Desktop WSL 2 backend](/manuals/desktop/features/wsl/_index.md). ## Docker Engine @@ -430,7 +431,7 @@ using Docker commands. Select **Reset Kubernetes cluster** to delete all stacks and Kubernetes resources. For more information about using the Kubernetes integration with Docker Desktop, -see [Deploy on Kubernetes](/manuals/desktop/kubernetes.md). +see [Deploy on Kubernetes](/manuals/desktop/features/kubernetes.md). ## Software Updates @@ -493,7 +494,7 @@ Use the **Notifications** tab to turn on or turn off notifications for the follo By default, all notifications are turned on. You'll always receive error notifications and notifications about new Docker Desktop releases and updates. -Notifications momentarily appear in the lower-right of the Docker Desktop Dashboard and then move to the **Notifications** drawer. To open the **Notifications** drawer, select {{< inline-image src="images/notifications.svg" alt="notifications" >}}. +Notifications momentarily appear in the lower-right of the Docker Desktop Dashboard and then move to the **Notifications** drawer. To open the **Notifications** drawer, select {{< inline-image src="../images/notifications.svg" alt="notifications" >}}. ## Advanced @@ -509,8 +510,8 @@ On Mac, you can reconfigure your initial installation settings on the **Advance ``` 3. Save and the close the file. Restart your shell to apply the changes to the PATH variable. -- **Enable default Docker socket (Requires password)**. Creates `/var/run/docker.sock` which some third party clients may use to communicate with Docker Desktop. For more information, see [permission requirements for macOS](/manuals/desktop/install/mac-permission-requirements.md#installing-symlinks). +- **Enable default Docker socket (Requires password)**. Creates `/var/run/docker.sock` which some third party clients may use to communicate with Docker Desktop. For more information, see [permission requirements for macOS](/manuals/desktop/setup/install/mac-permission-requirements.md#installing-symlinks). -- **Enable privileged port mapping (Requires password)**. Starts the privileged helper process which binds the ports that are between 1 and 1024. For more information, see [permission requirements for macOS](/manuals/desktop/install/mac-permission-requirements.md#binding-privileged-ports). +- **Enable privileged port mapping (Requires password)**. Starts the privileged helper process which binds the ports that are between 1 and 1024. For more information, see [permission requirements for macOS](/manuals/desktop/setup/install/mac-permission-requirements.md#binding-privileged-ports). - For more information on each configuration and use case, see [Permission requirements](/manuals/desktop/install/mac-permission-requirements.md). + For more information on each configuration and use case, see [Permission requirements](/manuals/desktop/setup/install/mac-permission-requirements.md). diff --git a/content/manuals/desktop/install/_index.md b/content/manuals/desktop/setup/_index.md similarity index 66% rename from content/manuals/desktop/install/_index.md rename to content/manuals/desktop/setup/_index.md index 186d97b05dd..676f6ca7c18 100644 --- a/content/manuals/desktop/install/_index.md +++ b/content/manuals/desktop/setup/_index.md @@ -1,6 +1,6 @@ --- build: render: never -title: Install +title: Setup weight: 10 ---- +--- \ No newline at end of file diff --git a/content/manuals/desktop/allow-list.md b/content/manuals/desktop/setup/allow-list.md similarity index 95% rename from content/manuals/desktop/allow-list.md rename to content/manuals/desktop/setup/allow-list.md index 8c859a8d04b..78b7ea3e6a4 100644 --- a/content/manuals/desktop/allow-list.md +++ b/content/manuals/desktop/setup/allow-list.md @@ -2,7 +2,10 @@ description: Allowlist for Docker Desktop for Business customers keywords: Docker Desktop, allowlist, allow list, firewall title: Allowlist for Docker Desktop +linkTitle: Allowlist weight: 100 +aliases: + - /desktop/allow-list/ --- This page contains the domain URLs that you need to add to a firewall allowlist to ensure Docker Desktop works properly within your organization. diff --git a/content/manuals/desktop/setup/install/_index.md b/content/manuals/desktop/setup/install/_index.md new file mode 100644 index 00000000000..3b6650ef5cd --- /dev/null +++ b/content/manuals/desktop/setup/install/_index.md @@ -0,0 +1,8 @@ +--- +build: + render: never +title: Install +weight: 10 +aliases: +- /desktop/install/ +--- diff --git a/content/manuals/desktop/setup/install/enterprise-deployment/_index.md b/content/manuals/desktop/setup/install/enterprise-deployment/_index.md new file mode 100644 index 00000000000..6797126bab1 --- /dev/null +++ b/content/manuals/desktop/setup/install/enterprise-deployment/_index.md @@ -0,0 +1,11 @@ +--- +title: Enterprise deployment +weight: 50 +description: If you're an IT admin, learn how to deploy Docker Desktop at scale +keywords: msi, docker desktop, windows, installation, mac, pkg, enterprise +build: + render: never +aliases: +- /desktop/install/msi/ +- /desktop/setup/install/msi/ +--- \ No newline at end of file diff --git a/content/manuals/desktop/install/msi/faq.md b/content/manuals/desktop/setup/install/enterprise-deployment/faq.md similarity index 86% rename from content/manuals/desktop/install/msi/faq.md rename to content/manuals/desktop/setup/install/enterprise-deployment/faq.md index 94565b4c8e6..2ca516dbcf1 100644 --- a/content/manuals/desktop/install/msi/faq.md +++ b/content/manuals/desktop/setup/install/enterprise-deployment/faq.md @@ -1,13 +1,18 @@ --- -title: MSI FAQs -description: Frequently asked questions for deploying Docker Desktop with Microsoft installer -keywords: msi, deploy, docker desktop, faqs +title: FAQs +description: Frequently asked questions for deploying Docker Desktop at scale +keywords: msi, deploy, docker desktop, faqs, pkg tags: [FAQ] +aliases: +- /desktop/install/msi/faq/ +- /desktop/setup/install/msi/faq/ --- +## MSI + ### What happens to user data if they have an older Docker Desktop installation (i.e. `.exe`)? -If they have an older `.exe` installation, users must [uninstall](../../uninstall.md) this version before using the new MSI version. This deletes all Docker containers, images, volumes, and other Docker-related data local to the machine, and removes the files generated by the application. For older versions, users should [backup](../../backup-and-restore.md) any containers that they want to keep. +If they have an older `.exe` installation, users must [uninstall](/manuals/desktop/uninstall.md) this version before using the new MSI version. This deletes all Docker containers, images, volumes, and other Docker-related data local to the machine, and removes the files generated by the application. For older versions, users should [backup](/manuals/desktop/settings-and-maintenance/backup-and-restore.md) any containers that they want to keep. For Docker Desktop versions 4.30 and later of the `exe` installer, a `-keep-data` flag is available. It removes Docker Desktop but keeps underlying data, such as the VMs that run containers. diff --git a/content/manuals/desktop/install/msi/install-and-configure.md b/content/manuals/desktop/setup/install/enterprise-deployment/msi-install-and-configure.md similarity index 92% rename from content/manuals/desktop/install/msi/install-and-configure.md rename to content/manuals/desktop/setup/install/enterprise-deployment/msi-install-and-configure.md index f96de559fd1..e17641c0aba 100644 --- a/content/manuals/desktop/install/msi/install-and-configure.md +++ b/content/manuals/desktop/setup/install/enterprise-deployment/msi-install-and-configure.md @@ -1,21 +1,26 @@ --- -title: Install and configure +title: Use the MSI installer description: Understand how to use the MSI installer. Also explore additional configuration options. keywords: msi, windows, docker desktop, install, deploy, configure +weight: 10 +aliases: +- /desktop/install/msi/install-and-configure/ +- /desktop/setup/install/msi/install-and-configure/ --- +> [!NOTE] +> +> The MSI installer is available to all company and organization owners with a Business subscription and Docker Desktop version 4.32 and later. + +The MSI package supports various MDM (Mobile Device Management) solutions, making it ideal for bulk installations and eliminating the need for manual setups by individual users. With this package, IT administrators can ensure standardized, policy-driven installations of Docker Desktop, enhancing efficiency and software management across their organizations. + ## Install interactively 1. In the [Docker Admin Console](http://admin.docker.com/), navigate to your organization. - 2. Under **Security and access**, select the **Deploy Docker Desktop** page. - -3. Select the **Download MSI installer** button. - +3. From the **Windows OS** tab, select the **Download MSI installer** button. 4. Once downloaded, double-click `Docker Desktop Installer.msi` to run the installer. - 5. Once you've accepted the license agreement, you can choose the install location. By default, Docker Desktop is installed at `C:\Program Files\Docker\Docker`. - 6. Configure the Docker Desktop installation. You can: - Create a desktop shortcut @@ -25,9 +30,7 @@ keywords: msi, windows, docker desktop, install, deploy, configure - Disable Windows Container usage - Select the engine for Docker Desktop. Either WSL or Hyper-V. If your system only supports one of the two options, you won't be able to select which backend to use. - 7. Follow the instructions on the installation wizard to authorize the installer and proceed with the install. - 8. When the installation is successful, select **Finish** to complete the installation process. If your administrator account is different to your user account, you must add the user to the **docker-users** group: @@ -42,7 +45,7 @@ If your administrator account is different to your user account, you must add th > > Docker Desktop notifies you when an update is available. To update Docker Desktop, download the latest installer from the Docker Admin Console. Navigate to the **Deploy Docker Desktop** page > under **Security and access**. > -> To keep up to date with new releases, check the [release notes](https://docs.docker.com/desktop/release-notes/) page. +> To keep up to date with new releases, check the [release notes](/manuals/desktop/release-notes.md) page. ## Install from the command line diff --git a/content/manuals/desktop/setup/install/enterprise-deployment/pkg-install-and-configure.md b/content/manuals/desktop/setup/install/enterprise-deployment/pkg-install-and-configure.md new file mode 100644 index 00000000000..34f9c9c31b9 --- /dev/null +++ b/content/manuals/desktop/setup/install/enterprise-deployment/pkg-install-and-configure.md @@ -0,0 +1,55 @@ +--- +title: Use the PKG installer +description: Understand how to use the PKG installer. Also explore additional configuration options. +keywords: PKG, mac, docker desktop, install, deploy, configure +weight: 20 +params: + sidebar: + badge: + color: violet + text: EA +--- + +{{% restricted title="Early Access" %}} +The PKG installer is currently an [Early Access](/manuals/release-lifecycle.md) feature and is available to all company and organization owners with a Business subscription and Docker Desktop version 4.36 and later. +{{% /restricted %}} + +The PKG package supports various MDM (Mobile Device Management) solutions, making it ideal for bulk installations and eliminating the need for manual setups by individual users. With this package, IT administrators can ensure standardized, policy-driven installations of Docker Desktop, enhancing efficiency and software management across their organizations. + +## Install interactively + +1. In the [Docker Admin Console](http://admin.docker.com/), navigate to your organization. +2. Under **Security and access**, select the **Deploy Docker Desktop** page. +3. From the **macOS** tab, select the **Download PKG installer** button. +4. Once downloaded, double-click `Docker.pkg` to run the installer. +5. Follow the instructions on the installation wizard to authorize the installer and proceed with the install. + - **Introduction**: Select `Continue`. + - **License**: Review the license agreement and select `Agree`. + - **Destination Select**: This step is optional. It is recommended that you don't change the default installation destination (usually `Macintosh HD`). Select `Continue`. + - **Installation Type**: Select `Install`. + - **Installation**: Authenticate using your administrator password or Touch ID. + - **Summary**: After the installation completes, select `Close`. + +> [!NOTE] +> +> When installing Docker Desktop with the PKG, in-app updates are automatically disabled. This feature ensures your organization maintains the required Docker Desktop version. For Docker Desktop installed with the .dmg installer, in-app updates remain supported. +> +> Docker Desktop notifies you when an update is available. To update Docker Desktop, download the latest installer from the Docker Admin Console. Navigate to the **Deploy Docker Desktop** page > under **Security and access**. +> +> To keep up to date with new releases, check the [release notes](/manuals/desktop/release-notes.md) page. + +## Install from the command line + +1. In the [Docker Admin Console](http://admin.docker.com/), navigate to your organization. +2. Under **Security and access**, select the **Deploy Docker Desktop** page. +3. From the **macOS** tab, select the **Download PKG installer** button. +4. From your terminal, run the following command: + + ```console + $ sudo installer -pkg "/path/to/Docker.pkg" -target /Applications + ``` + +## Additional resources + +- See how you can deploy Docker Desktop for Mac via [Intune](use-intune.md) or [Jamf Pro](use-jamf-pro.md) +- Explore how to [Enforce sign-in](/manuals/security/for-admins/enforce-sign-in/methods.md#plist-method-mac-only) for your users. \ No newline at end of file diff --git a/content/manuals/desktop/install/msi/use-intune.md b/content/manuals/desktop/setup/install/enterprise-deployment/use-intune.md similarity index 55% rename from content/manuals/desktop/install/msi/use-intune.md rename to content/manuals/desktop/setup/install/enterprise-deployment/use-intune.md index 1e9fdda03b7..7e7637c4e2b 100644 --- a/content/manuals/desktop/install/msi/use-intune.md +++ b/content/manuals/desktop/setup/install/enterprise-deployment/use-intune.md @@ -1,17 +1,24 @@ --- title: Use Intune description: Use Intune, Microsoft's cloud-based device management tool, to deploy Docker Desktop -keywords: microsoft, windows, docker desktop, deploy, mdm, enterprise, administrator, +keywords: microsoft, windows, docker desktop, deploy, mdm, enterprise, administrator +weight: 30 +aliases: +- /desktop/install/msi/use-intune/ +- /desktop/setup/install/msi/use-intune/ --- -Learn how to deploy Docker Desktop using Intune, Microsoft's cloud-based device management tool. +Learn how to deploy Docker Desktop for Windows and Mac using Intune, Microsoft's cloud-based device management tool. + +{{< tabs >}} +{{< tab name="Windows" >}} 1. Sign in to your Intune admin center. 2. Add a new app. Select **Apps**, then **Windows**, then **Add**. 3. For the app type, select **Windows app (Win32)** 4. Select the `intunewin` package. 5. Complete any relevant details such as the description, publisher, or app version and then select **Next**. -6. Optional: On the **Program** tab, you can update the **Install command** field to suit your needs. The field is pre-populated with `msiexec /i "DockerDesktop.msi" /qn`. See the [Common installation scenarios](install-and-configure.md) for examples on the changes you can make. +6. Optional: On the **Program** tab, you can update the **Install command** field to suit your needs. The field is pre-populated with `msiexec /i "DockerDesktop.msi" /qn`. See the [Common installation scenarios](msi-install-and-configure.md) for examples on the changes you can make. > [!TIP] > @@ -23,6 +30,26 @@ Learn how to deploy Docker Desktop using Intune, Microsoft's cloud-based device 7. Complete the rest of the tabs and then review and create the app. +{{< /tab >}} +{{< tab name="Mac" >}} + +First, upload the package: + +1. Sign in to your Intune admin center. +2. Add a new app. Select **Apps**, then **macOSs**, then **Add**. +3. Select **Line-of-business app** and then **Select**. +4. Upload the `Docker.pkg` file and fill in the required details. + +Next, assign the app: + +1. Once the app is added, navigate to **Assignments** in Intune. +2. Select **Add group** and choose the user or device groups you want to assign the app to. +3. Select **Save**. + +{{< /tab >}} +{{< /tabs >}} + ## Additional resources - [Explore the FAQs](faq.md). +- Learn how to [Enforce sign-in](/manuals/security/for-admins/enforce-sign-in/_index.md) for your users. \ No newline at end of file diff --git a/content/manuals/desktop/setup/install/enterprise-deployment/use-jamf-pro.md b/content/manuals/desktop/setup/install/enterprise-deployment/use-jamf-pro.md new file mode 100644 index 00000000000..2aa0e6ace14 --- /dev/null +++ b/content/manuals/desktop/setup/install/enterprise-deployment/use-jamf-pro.md @@ -0,0 +1,29 @@ +--- +title: Use Jamf Pro +description: Use Jamf Pro to deploy Docker Desktop +keywords: jamf, mac, docker desktop, deploy, mdm, enterprise, administrator, +weight: 40 +--- + +Learn how to deploy Docker Desktop for Mac using Jamf Pro. + +First, upload the package: + +1. From the Jamf pro console, Navigate to **Computers** > **Management Settings** > **Computer Management** > **Packages**. +2. Select **New** to add a new package. +3. Upload the `Docker.pkg` file. + +Next, create a policy for deployment: + +1. Navigate to **Computers** > **Policies**. +2. Select **New**to create a new policy. +3. Enter a name for the policy, for example "Deploy Docker Desktop". +4. Under the **Packages** tab, add the Docker package you uploaded. +5. Configure the scope to target the devices or device groups you want to install Docker on. +6. Save the policy and deploy. + +For more information, see [Jamf Pro's official documentation](https://learn.jamf.com/en-US/bundle/jamf-pro-documentation-current/page/Policies.html). + +## Additional resources + +- Learn how to [Enforce sign-in](/manuals/security/for-admins/enforce-sign-in/_index.md) for your users. \ No newline at end of file diff --git a/content/manuals/desktop/install/images/whale-x.svg b/content/manuals/desktop/setup/install/images/whale-x.svg similarity index 100% rename from content/manuals/desktop/install/images/whale-x.svg rename to content/manuals/desktop/setup/install/images/whale-x.svg diff --git a/content/manuals/desktop/install/linux/_index.md b/content/manuals/desktop/setup/install/linux/_index.md similarity index 91% rename from content/manuals/desktop/install/linux/_index.md rename to content/manuals/desktop/setup/install/linux/_index.md index b6c364d70aa..5cd8e9f3ab9 100644 --- a/content/manuals/desktop/install/linux/_index.md +++ b/content/manuals/desktop/setup/install/linux/_index.md @@ -10,6 +10,7 @@ weight: 60 aliases: - /desktop/linux/install/ - /desktop/install/linux-install/ +- /desktop/install/linux/ --- > **Docker Desktop terms** @@ -39,7 +40,7 @@ Docker Desktop for Linux provides a user-friendly graphical interface that simpl Docker Desktop for Linux and Docker Engine can be installed side-by-side on the same machine. Docker Desktop for Linux stores containers and images in an isolated storage location within a VM and offers -controls to restrict [its resources](/manuals/desktop/settings.md#resources). Using a dedicated storage +controls to restrict [its resources](/manuals/desktop/settings-and-maintenance/settings.md#resources). Using a dedicated storage location for Docker Desktop prevents it from interfering with a Docker Engine installation on the same machine. @@ -137,12 +138,12 @@ To install Docker Desktop successfully, your Linux host must meet the following - QEMU must be version 5.2 or later. We recommend upgrading to the latest version. - systemd init system. - Gnome, KDE, or MATE Desktop environment. - - For many Linux distros, the Gnome environment does not support tray icons. To add support for tray icons, you need to install a Gnome extension. For example, [AppIndicator](https://extensions.gnome.org/extension/615/appindicator-support/). + - For many Linux distributions, the Gnome environment does not support tray icons. To add support for tray icons, you need to install a Gnome extension. For example, [AppIndicator](https://extensions.gnome.org/extension/615/appindicator-support/). - At least 4 GB of RAM. -- Enable configuring ID mapping in user namespaces, see [File sharing](/manuals/desktop/faqs/linuxfaqs.md#how-do-i-enable-file-sharing). Note that for Docker Desktop version 4.35 and later, this is not required anymore. -- Recommended: [Initialize `pass`](/manuals/desktop/get-started.md#credentials-management-for-linux-users) for credentials management. +- Enable configuring ID mapping in user namespaces, see [File sharing](/manuals/desktop/troubleshoot-and-support/faqs/linuxfaqs.md#how-do-i-enable-file-sharing). Note that for Docker Desktop version 4.35 and later, this is not required anymore. +- Recommended: [Initialize `pass`](/manuals/desktop/setup/sign-in.md#credentials-management-for-linux-users) for credentials management. -Docker Desktop for Linux runs a Virtual Machine (VM). For more information on why, see [Why Docker Desktop for Linux runs a VM](/manuals/desktop/faqs/linuxfaqs.md#why-does-docker-desktop-for-linux-run-a-vm). +Docker Desktop for Linux runs a Virtual Machine (VM). For more information on why, see [Why Docker Desktop for Linux runs a VM](/manuals/desktop/troubleshoot-and-support/faqs/linuxfaqs.md#why-does-docker-desktop-for-linux-run-a-vm). > [!NOTE] > diff --git a/content/manuals/desktop/install/linux/archlinux.md b/content/manuals/desktop/setup/install/linux/archlinux.md similarity index 80% rename from content/manuals/desktop/install/linux/archlinux.md rename to content/manuals/desktop/setup/install/linux/archlinux.md index 214036ed504..055960f4b7d 100644 --- a/content/manuals/desktop/install/linux/archlinux.md +++ b/content/manuals/desktop/setup/install/linux/archlinux.md @@ -8,6 +8,7 @@ linkTitle: Arch aliases: - /desktop/linux/install/archlinux/ - /desktop/install/archlinux/ +- /desktop/install/linux/archlinux/ --- > **Docker Desktop terms** @@ -51,11 +52,11 @@ To install Docker Desktop successfully, you must meet the [general system requir ## Next steps -- Explore [Docker's core subscriptions](https://www.docker.com/pricing/) to see what Docker can offer you. +- Explore [Docker's subscriptions](https://www.docker.com/pricing/) to see what Docker can offer you. - Take a look at the [Docker workshop](/get-started/workshop/_index.md) to learn how to build an image and run it as a containerized application. - [Explore Docker Desktop](/manuals/desktop/use-desktop/_index.md) and all its features. -- [Troubleshooting](/manuals/desktop/troubleshoot/_index.md) describes common problems, workarounds, how to run and submit diagnostics, and submit issues. -- [FAQs](/manuals/desktop/faqs/general.md) provide answers to frequently asked questions. +- [Troubleshooting](/manuals/desktop/troubleshoot-and-support/troubleshoot/_index.md) describes common problems, workarounds, how to run and submit diagnostics, and submit issues. +- [FAQs](/manuals/desktop/troubleshoot-and-support/faqs/general.md) provide answers to frequently asked questions. - [Release notes](/manuals/desktop/release-notes.md) lists component updates, new features, and improvements associated with Docker Desktop releases. -- [Back up and restore data](/manuals/desktop/backup-and-restore.md) provides instructions +- [Back up and restore data](/manuals/desktop/settings-and-maintenance/backup-and-restore.md) provides instructions on backing up and restoring data related to Docker. diff --git a/content/manuals/desktop/install/linux/debian.md b/content/manuals/desktop/setup/install/linux/debian.md similarity index 87% rename from content/manuals/desktop/install/linux/debian.md rename to content/manuals/desktop/setup/install/linux/debian.md index be1642eb302..32892d384b4 100644 --- a/content/manuals/desktop/install/linux/debian.md +++ b/content/manuals/desktop/setup/install/linux/debian.md @@ -9,6 +9,7 @@ toc_max: 4 aliases: - /desktop/linux/install/debian/ - /desktop/install/debian/ +- /desktop/install/linux/debian/ --- > **Docker Desktop terms** @@ -86,11 +87,11 @@ Don't forget to substitute `` with the architecture you want. ## Next steps -- Explore [Docker's core subscriptions](https://www.docker.com/pricing/) to see what Docker can offer you. +- Explore [Docker's subscriptions](https://www.docker.com/pricing/) to see what Docker can offer you. - Take a look at the [Docker workshop](/get-started/workshop/_index.md) to learn how to build an image and run it as a containerized application. - [Explore Docker Desktop](/manuals/desktop/use-desktop/_index.md) and all its features. -- [Troubleshooting](/manuals/desktop/troubleshoot/_index.md) describes common problems, workarounds, how to run and submit diagnostics, and submit issues. -- [FAQs](/manuals/desktop/faqs/general.md) provide answers to frequently asked questions. +- [Troubleshooting](/manuals/desktop/troubleshoot-and-support/troubleshoot/_index.md) describes common problems, workarounds, how to run and submit diagnostics, and submit issues. +- [FAQs](/manuals/desktop/troubleshoot-and-support/faqs/general.md) provide answers to frequently asked questions. - [Release notes](/manuals/desktop/release-notes.md) lists component updates, new features, and improvements associated with Docker Desktop releases. -- [Back up and restore data](/manuals/desktop/backup-and-restore.md) provides instructions +- [Back up and restore data](/manuals/desktop/settings-and-maintenance/backup-and-restore.md) provides instructions on backing up and restoring data related to Docker. diff --git a/content/manuals/desktop/install/linux/fedora.md b/content/manuals/desktop/setup/install/linux/fedora.md similarity index 85% rename from content/manuals/desktop/install/linux/fedora.md rename to content/manuals/desktop/setup/install/linux/fedora.md index 9dc03aba71b..8b713a37e8f 100644 --- a/content/manuals/desktop/install/linux/fedora.md +++ b/content/manuals/desktop/setup/install/linux/fedora.md @@ -9,6 +9,7 @@ toc_max: 4 aliases: - /desktop/linux/install/fedora/ - /desktop/install/fedora/ +- /desktop/install/linux/fedora/ --- > **Docker Desktop terms** @@ -24,7 +25,7 @@ This page contains information on how to install, launch and upgrade Docker Desk To install Docker Desktop successfully, you must: - Meet the [general system requirements](_index.md#general-system-requirements). -- Have a 64-bit version of Fedora 39 or Fedora 40. +- Have a 64-bit version of Fedora 40 or Fedora 41. Additionally, for a GNOME desktop environment you must install AppIndicator and KStatusNotifierItem [GNOME extensions](https://extensions.gnome.org/extension/615/appindicator-support/). @@ -77,11 +78,11 @@ Don't forget to substitute `` with the architecture you want. ## Next steps -- Explore [Docker's core subscriptions](https://www.docker.com/pricing/) to see what Docker can offer you. +- Explore [Docker's subscriptions](https://www.docker.com/pricing/) to see what Docker can offer you. - Take a look at the [Docker workshop](/get-started/workshop/_index.md) to learn how to build an image and run it as a containerized application. - [Explore Docker Desktop](/manuals/desktop/use-desktop/_index.md) and all its features. -- [Troubleshooting](/manuals/desktop/troubleshoot/_index.md) describes common problems, workarounds, how to run and submit diagnostics, and submit issues. -- [FAQs](/manuals/desktop/faqs/general.md) provide answers to frequently asked questions. +- [Troubleshooting](/manuals/desktop/troubleshoot-and-support/troubleshoot/_index.md) describes common problems, workarounds, how to run and submit diagnostics, and submit issues. +- [FAQs](/manuals/desktop/troubleshoot-and-support/faqs/general.md) provide answers to frequently asked questions. - [Release notes](/manuals/desktop/release-notes.md) lists component updates, new features, and improvements associated with Docker Desktop releases. -- [Back up and restore data](/manuals/desktop/backup-and-restore.md) provides instructions +- [Back up and restore data](/manuals/desktop/settings-and-maintenance/backup-and-restore.md) provides instructions on backing up and restoring data related to Docker. diff --git a/content/manuals/desktop/install/linux/rhel.md b/content/manuals/desktop/setup/install/linux/rhel.md similarity index 90% rename from content/manuals/desktop/install/linux/rhel.md rename to content/manuals/desktop/setup/install/linux/rhel.md index 5fdba5ea02e..a2e3db85bc8 100644 --- a/content/manuals/desktop/install/linux/rhel.md +++ b/content/manuals/desktop/setup/install/linux/rhel.md @@ -11,6 +11,8 @@ params: badge: color: green text: New +aliases: +- /desktop/install/linux/rhel/ --- > **Docker Desktop terms** @@ -138,11 +140,11 @@ $ sudo dnf install ./docker-desktop--rhel.rpm ## Next steps -- Explore [Docker's core subscriptions](https://www.docker.com/pricing/) to see what Docker can offer you. +- Explore [Docker's subscriptions](https://www.docker.com/pricing/) to see what Docker can offer you. - Take a look at the [Docker workshop](/get-started/workshop/_index.md) to learn how to build an image and run it as a containerized application. - [Explore Docker Desktop](/manuals/desktop/use-desktop/_index.md) and all its features. -- [Troubleshooting](/manuals/desktop/troubleshoot/_index.md) describes common problems, workarounds, how to run and submit diagnostics, and submit issues. -- [FAQs](/manuals/desktop/faqs/general.md) provide answers to frequently asked questions. +- [Troubleshooting](/manuals/desktop/troubleshoot-and-support/troubleshoot/_index.md) describes common problems, workarounds, how to run and submit diagnostics, and submit issues. +- [FAQs](/manuals/desktop/troubleshoot-and-support/faqs/general.md) provide answers to frequently asked questions. - [Release notes](/manuals/desktop/release-notes.md) lists component updates, new features, and improvements associated with Docker Desktop releases. -- [Back up and restore data](/manuals/desktop/backup-and-restore.md) provides instructions +- [Back up and restore data](/manuals/desktop/settings-and-maintenance/backup-and-restore.md) provides instructions on backing up and restoring data related to Docker. diff --git a/content/manuals/desktop/install/linux/ubuntu.md b/content/manuals/desktop/setup/install/linux/ubuntu.md similarity index 88% rename from content/manuals/desktop/install/linux/ubuntu.md rename to content/manuals/desktop/setup/install/linux/ubuntu.md index 1a6f3ed846c..b41a6abceb8 100644 --- a/content/manuals/desktop/install/linux/ubuntu.md +++ b/content/manuals/desktop/setup/install/linux/ubuntu.md @@ -12,6 +12,7 @@ toc_max: 4 aliases: - /desktop/linux/install/ubuntu/ - /desktop/install/ubuntu/ +- /desktop/install/linux/ubuntu/ --- > **Docker Desktop terms** @@ -86,11 +87,11 @@ Don't forget to substitute `` with the architecture you want. ## Next steps -- Explore [Docker's core subscriptions](https://www.docker.com/pricing/) to see what Docker can offer you. +- Explore [Docker's subscriptions](https://www.docker.com/pricing/) to see what Docker can offer you. - Take a look at the [Docker workshop](/get-started/workshop/_index.md) to learn how to build an image and run it as a containerized application. - [Explore Docker Desktop](/manuals/desktop/use-desktop/_index.md) and all its features. -- [Troubleshooting](/manuals/desktop/troubleshoot/_index.md) describes common problems, workarounds, how to run and submit diagnostics, and submit issues. -- [FAQs](/manuals/desktop/faqs/general.md) provide answers to frequently asked questions. +- [Troubleshooting](/manuals/desktop/troubleshoot-and-support/troubleshoot/_index.md) describes common problems, workarounds, how to run and submit diagnostics, and submit issues. +- [FAQs](/manuals/desktop/troubleshoot-and-support/faqs/general.md) provide answers to frequently asked questions. - [Release notes](/manuals/desktop/release-notes.md) lists component updates, new features, and improvements associated with Docker Desktop releases. -- [Back up and restore data](/manuals/desktop/backup-and-restore.md) provides instructions +- [Back up and restore data](/manuals/desktop/settings-and-maintenance/backup-and-restore.md) provides instructions on backing up and restoring data related to Docker. diff --git a/content/manuals/desktop/install/mac-install.md b/content/manuals/desktop/setup/install/mac-install.md similarity index 81% rename from content/manuals/desktop/install/mac-install.md rename to content/manuals/desktop/setup/install/mac-install.md index 22469971857..815f0672a07 100644 --- a/content/manuals/desktop/install/mac-install.md +++ b/content/manuals/desktop/setup/install/mac-install.md @@ -15,6 +15,7 @@ aliases: - /docker-for-mac/apple-m1/ - /docker-for-mac/apple-silicon/ - /desktop/mac/apple-silicon/ +- /desktop/install/mac-install/ --- > **Docker Desktop terms** @@ -28,7 +29,7 @@ This page contains download URLs, information about system requirements, and ins {{< button text="Docker Desktop for Mac with Apple silicon" url="https://desktop.docker.com/mac/main/arm64/Docker.dmg?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-mac-arm64" >}} {{< button text="Docker Desktop for Mac with Intel chip" url="https://desktop.docker.com/mac/main/amd64/Docker.dmg?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-mac-amd64" >}} -*For checksums, see [Release notes](../release-notes.md).* +*For checksums, see [Release notes](/manuals/desktop/release-notes.md).* ## System requirements @@ -53,7 +54,7 @@ This page contains download URLs, information about system requirements, and ins > Docker supports Docker Desktop on the most recent versions of macOS. That is, the current release of macOS and the previous two releases. As new major versions of macOS are made generally available, Docker stops supporting the oldest version and supports the newest version of macOS (in addition to the previous two releases). - At least 4 GB of RAM. -- For the best experience, it's recommended that you install Rosetta 2. There is no longer a hard requirement to install Rosetta 2, however there are a few optional command line tools that still require Rosetta 2 when using Darwin/AMD64. See [Known issues](../troubleshoot/known-issues.md). To install Rosetta 2 manually from the command line, run the following command: +- For the best experience, it's recommended that you install Rosetta 2. There is no longer a hard requirement to install Rosetta 2, however there are a few optional command line tools that still require Rosetta 2 when using Darwin/AMD64. See [Known issues](/manuals/desktop/troubleshoot-and-support/troubleshoot/known-issues.md). To install Rosetta 2 manually from the command line, run the following command: ```console $ softwareupdate --install-rosetta @@ -65,11 +66,11 @@ This page contains download URLs, information about system requirements, and ins > [!TIP] > -> See the [FAQs](/manuals/desktop/faqs/general.md#how-do-I-run-docker-desktop-without-administrator-privileges) on how to install and run Docker Desktop without needing administrator privileges. +> See the [FAQs](/manuals/desktop/troubleshoot-and-support/faqs/general.md#how-do-I-run-docker-desktop-without-administrator-privileges) on how to install and run Docker Desktop without needing administrator privileges. ### Install interactively -1. Download the installer using the download buttons at the top of the page, or from the [release notes](../release-notes.md). +1. Download the installer using the download buttons at the top of the page, or from the [release notes](/manuals/desktop/release-notes.md). 2. Double-click `Docker.dmg` to open the installer, then drag the Docker icon to the **Applications** folder. By default, Docker Desktop is installed at `/Applications/Docker.app`. @@ -91,12 +92,12 @@ This page contains download URLs, information about system requirements, and ins 6. From the installation window, select either: - **Use recommended settings (Requires password)**. This lets Docker Desktop automatically set the necessary configuration settings. - - **Use advanced settings**. You can then set the location of the Docker CLI tools either in the system or user directory, enable the default Docker socket, and enable privileged port mapping. See [Settings](/manuals/desktop/settings.md#advanced), for more information and how to set the location of the Docker CLI tools. + - **Use advanced settings**. You can then set the location of the Docker CLI tools either in the system or user directory, enable the default Docker socket, and enable privileged port mapping. See [Settings](/manuals/desktop/settings-and-maintenance/settings.md#advanced), for more information and how to set the location of the Docker CLI tools. 7. Select **Finish**. If you have applied any of the previous configurations that require a password in step 6, enter your password to confirm your choice. ### Install from the command line -After downloading `Docker.dmg` from either the download buttons at the top of the page or from the [release notes](../release-notes.md), run the following commands in a terminal to install Docker Desktop in the **Applications** folder: +After downloading `Docker.dmg` from either the download buttons at the top of the page or from the [release notes](/manuals/desktop/release-notes.md), run the following commands in a terminal to install Docker Desktop in the **Applications** folder: ```console $ sudo hdiutil attach Docker.dmg @@ -109,7 +110,7 @@ By default, Docker Desktop is installed at `/Applications/Docker.app`. As macOS The `install` command accepts the following flags: - `--accept-license`: Accepts the [Docker Subscription Service Agreement](https://www.docker.com/legal/docker-subscription-service-agreement) now, rather than requiring it to be accepted when the application is first run. - `--allowed-org=`: Requires the user to sign in and be part of the specified Docker Hub organization when running the application -- `--user=`: Performs the privileged configurations once during installation. This removes the need for the user to grant root privileges on first run. For more information, see [Privileged helper permission requirements](/manuals/desktop/install/mac-permission-requirements.md#permission-requirements). To find the username, enter `ls /Users` in the CLI. +- `--user=`: Performs the privileged configurations once during installation. This removes the need for the user to grant root privileges on first run. For more information, see [Privileged helper permission requirements](/manuals/desktop/setup/install/mac-permission-requirements.md#permission-requirements). To find the username, enter `ls /Users` in the CLI. - `--admin-settings`: Automatically creates an `admin-settings.json` file which is used by administrators to control certain Docker Desktop settings on client machines within their organization. For more information, see [Settings Management](/manuals/security/for-admins/hardened-desktop/settings-management/_index.md). - It must be used together with the `--allowed-org=` flag. - For example: `--allowed-org= --admin-settings="{'configurationFileVersion': 2, 'enhancedContainerIsolation': {'value': true, 'locked': false}}"` @@ -127,14 +128,14 @@ The `install` command accepts the following flags: > - [Kolide](https://www.kolide.com/features/device-inventory/properties/mac-apps) > - [Workspace One](https://blogs.vmware.com/euc/2022/11/how-to-use-workspace-one-intelligence-to-manage-app-licenses-and-reduce-costs.html) -## Where to go next +## Where to go next -- Explore [Docker's core subscriptions](https://www.docker.com/pricing/) to see what Docker can offer you. +- Explore [Docker's subscriptions](https://www.docker.com/pricing/) to see what Docker can offer you. - [Get started with Docker](/get-started/introduction/_index.md). -- [Explore Docker Desktop](../use-desktop/_index.md) and all its features. -- [Troubleshooting](/manuals/desktop/troubleshoot/_index.md) describes common problems, workarounds, how +- [Explore Docker Desktop](/manuals/desktop/use-desktop/_index.md) and all its features. +- [Troubleshooting](/manuals/desktop/troubleshoot-and-support/troubleshoot/_index.md) describes common problems, workarounds, how to run and submit diagnostics, and submit issues. -- [FAQs](../faqs/general.md) provide answers to frequently asked questions. -- [Release notes](../release-notes.md) lists component updates, new features, and improvements associated with Docker Desktop releases. -- [Back up and restore data](../backup-and-restore.md) provides instructions +- [FAQs](/manuals/desktop/troubleshoot-and-support/faqs/general.md) provide answers to frequently asked questions. +- [Release notes](/manuals/desktop/release-notes.md) lists component updates, new features, and improvements associated with Docker Desktop releases. +- [Back up and restore data](/manuals/desktop/settings-and-maintenance/backup-and-restore.md) provides instructions on backing up and restoring data related to Docker. diff --git a/content/manuals/desktop/install/mac-permission-requirements.md b/content/manuals/desktop/setup/install/mac-permission-requirements.md similarity index 97% rename from content/manuals/desktop/install/mac-permission-requirements.md rename to content/manuals/desktop/setup/install/mac-permission-requirements.md index 9f039a0ebcb..9f24fe9d1ca 100644 --- a/content/manuals/desktop/install/mac-permission-requirements.md +++ b/content/manuals/desktop/setup/install/mac-permission-requirements.md @@ -7,6 +7,7 @@ aliases: - /docker-for-mac/privileged-helper/ - /desktop/mac/privileged-helper/ - /desktop/mac/permission-requirements/ +- /desktop/install/mac-permission-requirements/ weight: 20 --- @@ -64,7 +65,7 @@ The Docker binaries are installed by default in `/Applications/Docker.app/Conten With version 4.18 and later, you can choose whether to install symlinks either in `/usr/local/bin` or `$HOME/.docker/bin` during installation of Docker Desktop. -If `/usr/local/bin` is chosen, and this location is not writable by unprivileged users, Docker Desktop requires authorization to confirm this choice before the symlinks to Docker binaries are created in `/usr/local/bin`. If `$HOME/.docker/bin` is chosen, authorization is not required, but then you must [manually add `$HOME/.docker/bin`](/manuals/desktop/settings.md#advanced) to their PATH. +If `/usr/local/bin` is chosen, and this location is not writable by unprivileged users, Docker Desktop requires authorization to confirm this choice before the symlinks to Docker binaries are created in `/usr/local/bin`. If `$HOME/.docker/bin` is chosen, authorization is not required, but then you must [manually add `$HOME/.docker/bin`](/manuals/desktop/settings-and-maintenance/settings.md#advanced) to their PATH. You are also given the option to enable the installation of the `/var/run/docker.sock` symlink. Creating this symlink ensures various Docker clients relying on the default Docker socket path work without additional changes. @@ -134,7 +135,7 @@ On first run, Docker Desktop checks if `localhost` is resolved to `127.0.0.1`. I ## Installing from the command line -In version 4.11 and later of Docker Desktop for Mac, privileged configurations are applied during the installation with the `--user` flag on the [install command](/manuals/desktop/install/mac-install.md#install-from-the-command-line). In this case, you are not prompted to grant root privileges on the first run of Docker Desktop. Specifically, the `--user` flag: +In version 4.11 and later of Docker Desktop for Mac, privileged configurations are applied during the installation with the `--user` flag on the [install command](/manuals/desktop/setup/install/mac-install.md#install-from-the-command-line). In this case, you are not prompted to grant root privileges on the first run of Docker Desktop. Specifically, the `--user` flag: - Uninstalls the previous `com.docker.vmnetd` if present - Sets up symlinks - Ensures that `localhost` is resolved to `127.0.0.1` diff --git a/content/manuals/desktop/install/windows-install.md b/content/manuals/desktop/setup/install/windows-install.md similarity index 89% rename from content/manuals/desktop/install/windows-install.md rename to content/manuals/desktop/setup/install/windows-install.md index d7e733e1347..580a92e545f 100644 --- a/content/manuals/desktop/install/windows-install.md +++ b/content/manuals/desktop/setup/install/windows-install.md @@ -19,6 +19,7 @@ aliases: - /install/windows/ee-preview/ - /installation/windows/ - /desktop/win/configuring-wsl/ +- /desktop/install/windows-install/ --- > **Docker Desktop terms** @@ -32,7 +33,7 @@ This page contains the download URL, information about system requirements, and {{< button text="Docker Desktop for Windows - x86_64" url="https://desktop.docker.com/win/main/amd64/Docker%20Desktop%20Installer.exe?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-win-amd64" >}} {{< button text="Docker Desktop for Windows - Arm (Beta)" url="https://desktop.docker.com/win/main/arm64/Docker%20Desktop%20Installer.exe?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-win-arm64" >}} -_For checksums, see [Release notes](../release-notes.md)_ +_For checksums, see [Release notes](/manuals/desktop/release-notes.md)_ ## System requirements @@ -55,9 +56,9 @@ _For checksums, see [Release notes](../release-notes.md)_ - 64-bit processor with [Second Level Address Translation (SLAT)](https://en.wikipedia.org/wiki/Second_Level_Address_Translation) - 4GB system RAM - Enable hardware virtualization in BIOS. For more information, see - [Virtualization](../troubleshoot/topics.md#virtualization). + [Virtualization](/manuals/desktop/troubleshoot-and-support/troubleshoot/topics.md#virtualization). -For more information on setting up WSL 2 with Docker Desktop, see [WSL](../wsl/_index.md). +For more information on setting up WSL 2 with Docker Desktop, see [WSL](/manuals/desktop/features/wsl/_index.md). > [!NOTE] > @@ -81,7 +82,7 @@ For more information on setting up WSL 2 with Docker Desktop, see [WSL](../wsl/_ - 4GB system RAM - Turn on BIOS-level hardware virtualization support in the BIOS settings. For more information, see - [Virtualization](../troubleshoot/topics.md#virtualization). + [Virtualization](/manuals/desktop/troubleshoot-and-support/troubleshoot/topics.md#virtualization). > [!NOTE] > @@ -105,7 +106,7 @@ For more information on setting up WSL 2 with Docker Desktop, see [WSL](../wsl/_ - 64-bit processor with [Second Level Address Translation (SLAT)](https://en.wikipedia.org/wiki/Second_Level_Address_Translation) - 4GB system RAM - Enable hardware virtualization in BIOS. For more information, see - [Virtualization](../troubleshoot/topics.md#virtualization). + [Virtualization](/manuals/desktop/troubleshoot-and-support/troubleshoot/topics.md#virtualization). > [!IMPORTANT] > @@ -120,7 +121,7 @@ accounts use the same VM to build and run containers. Note that it is not possib Running Docker Desktop inside a VMware ESXi or Azure VM is supported for Docker Business customers. It requires enabling nested virtualization on the hypervisor first. -For more information, see [Running Docker Desktop in a VM or VDI environment](../vm-vdi.md). +For more information, see [Running Docker Desktop in a VM or VDI environment](/manuals/desktop/setup/vm-vdi.md). {{< accordion title="How do I switch between Windows and Linux containers?" >}} @@ -142,7 +143,7 @@ For more information on Windows containers, refer to the following documentation [forked here to use containers](https://github.com/friism/MusicStore), is a good example of a multi-container application. - To understand how to connect to Windows containers from the local host, see - [I want to connect to a container from Windows](../networking.md#i-want-to-connect-to-a-container-from-the-host) + [I want to connect to a container from Windows](/manuals/desktop/features/networking.md#i-want-to-connect-to-a-container-from-the-host) > [!NOTE] > @@ -160,11 +161,11 @@ again when you switch back. > [!TIP] > -> See the [FAQs](/manuals/desktop/faqs/general.md#how-do-I-run-docker-desktop-without-administrator-privileges) on how to install and run Docker Desktop without needing administrator privileges. +> See the [FAQs](/manuals/desktop/troubleshoot-and-support/faqs/general.md#how-do-i-run-docker-desktop-without-administrator-privileges) on how to install and run Docker Desktop without needing administrator privileges. ### Install interactively -1. Download the installer using the download button at the top of the page, or from the [release notes](../release-notes.md). +1. Download the installer using the download button at the top of the page, or from the [release notes](/manuals/desktop/release-notes.md). 2. Double-click `Docker Desktop Installer.exe` to run the installer. By default, Docker Desktop is installed at `C:\Program Files\Docker\Docker`. @@ -259,7 +260,7 @@ Docker Desktop does not start automatically after installation. To start Docker > [!TIP] > -> As an IT administrator, you can use endpoint management (MDM) software to identify the number of Docker Desktop instances and their versions within your environment. This can provide accurate license reporting, help ensure your machines use the latest version of Docker Desktop, and enable you to [enforce sign-in](../../security/for-admins/enforce-sign-in/_index.md). +> As an IT administrator, you can use endpoint management (MDM) software to identify the number of Docker Desktop instances and their versions within your environment. This can provide accurate license reporting, help ensure your machines use the latest version of Docker Desktop, and enable you to [enforce sign-in](/manuals/security/for-admins/enforce-sign-in/_index.md). > - [Intune](https://learn.microsoft.com/en-us/mem/intune/apps/app-discovered-apps) > - [Jamf](https://docs.jamf.com/10.25.0/jamf-pro/administrator-guide/Application_Usage.html) > - [Kandji](https://support.kandji.io/support/solutions/articles/72000559793-view-a-device-application-list) @@ -268,11 +269,11 @@ Docker Desktop does not start automatically after installation. To start Docker ## Where to go next -- Explore [Docker's core subscriptions](https://www.docker.com/pricing/) to see what Docker can offer you. +- Explore [Docker's subscriptions](https://www.docker.com/pricing/) to see what Docker can offer you. - [Get started with Docker](/get-started/introduction/_index.md). -- [Explore Docker Desktop](../use-desktop/_index.md) and all its features. -- [Troubleshooting](/manuals/desktop/troubleshoot/_index.md) describes common problems, workarounds, and +- [Explore Docker Desktop](/manuals/desktop/use-desktop/_index.md) and all its features. +- [Troubleshooting](/manuals/desktop/troubleshoot-and-support/troubleshoot/_index.md) describes common problems, workarounds, and how to get support. -- [FAQs](../faqs/general.md) provide answers to frequently asked questions. -- [Release notes](../release-notes.md) lists component updates, new features, and improvements associated with Docker Desktop releases. -- [Back up and restore data](../backup-and-restore.md) provides instructions on backing up and restoring data related to Docker. +- [FAQs](/manuals/desktop/troubleshoot-and-support/faqs/general.md) provide answers to frequently asked questions. +- [Release notes](/manuals/desktop/release-notes.md) lists component updates, new features, and improvements associated with Docker Desktop releases. +- [Back up and restore data](/manuals/desktop/settings-and-maintenance/backup-and-restore.md) provides instructions on backing up and restoring data related to Docker. diff --git a/content/manuals/desktop/install/windows-permission-requirements.md b/content/manuals/desktop/setup/install/windows-permission-requirements.md similarity index 99% rename from content/manuals/desktop/install/windows-permission-requirements.md rename to content/manuals/desktop/setup/install/windows-permission-requirements.md index d3c27d4c8b5..aded11b07d4 100644 --- a/content/manuals/desktop/install/windows-permission-requirements.md +++ b/content/manuals/desktop/setup/install/windows-permission-requirements.md @@ -5,6 +5,7 @@ title: Understand permission requirements for Windows aliases: - /desktop/windows/privileged-helper/ - /desktop/windows/permission-requirements/ +- /desktop/install/windows-permission-requirements/ weight: 40 --- diff --git a/content/manuals/desktop/get-started.md b/content/manuals/desktop/setup/sign-in.md similarity index 90% rename from content/manuals/desktop/get-started.md rename to content/manuals/desktop/setup/sign-in.md index 77012a569ba..0fcac9e92a5 100644 --- a/content/manuals/desktop/get-started.md +++ b/content/manuals/desktop/setup/sign-in.md @@ -5,7 +5,7 @@ keywords: Docker Dashboard, manage, containers, gui, dashboard, images, user man learning center, guide, sign in title: Sign in to Docker Desktop linkTitle: Sign in -weight: 20 +weight: 40 aliases: - /desktop/linux/ - /desktop/linux/index/ @@ -27,11 +27,12 @@ aliases: - /windows/ - /winkit/ - /winkit/getting-started/ +- /desktop/get-started/ --- Docker recommends that you authenticate using the **Sign in** option in the top-right corner of the Docker Dashboard. -In large enterprises where admin access is restricted, administrators can [enforce sign-in](../security/for-admins/enforce-sign-in/_index.md). +In large enterprises where admin access is restricted, administrators can [enforce sign-in](/manuals/security/for-admins/enforce-sign-in/_index.md). > [!TIP] > @@ -41,7 +42,7 @@ In large enterprises where admin access is restricted, administrators can [enfor - You can access your Docker Hub repositories directly from Docker Desktop. -- Authenticated users also get a higher pull rate limit compared to anonymous users. For example, if you are authenticated, you get 200 pulls per 6 hour period, compared to 100 pulls per 6 hour period per IP address for anonymous users. For more information, see [Download rate limit](../docker-hub/download-rate-limit.md). +- Authenticated users also get a higher pull rate limit compared to anonymous users. For example, if you are authenticated, you get 200 pulls per 6 hour period, compared to 100 pulls per 6 hour period per IP address for anonymous users. For more information, see [Download rate limit](/manuals/docker-hub/download-rate-limit.md). - Improve your organization’s security posture for containerized development by taking advantage of [Hardened Desktop](/manuals/security/for-admins/hardened-desktop/_index.md). @@ -107,6 +108,6 @@ docker.io/molly/privateimage:latest ## What's next? -- [Explore Docker Desktop](use-desktop/_index.md) and its features. +- [Explore Docker Desktop](/manuals/desktop/use-desktop/_index.md) and its features. - Change your Docker Desktop settings -- [Browse common FAQs](faqs/general.md) +- [Browse common FAQs](/manuals/desktop/troubleshoot-and-support/faqs/general.md) diff --git a/content/manuals/desktop/vm-vdi.md b/content/manuals/desktop/setup/vm-vdi.md similarity index 95% rename from content/manuals/desktop/vm-vdi.md rename to content/manuals/desktop/setup/vm-vdi.md index bf18e97c0c0..4e315c0bac0 100644 --- a/content/manuals/desktop/vm-vdi.md +++ b/content/manuals/desktop/setup/vm-vdi.md @@ -3,8 +3,9 @@ description: Instructions on how to enable nested virtualization keywords: nested virtualization, Docker Desktop, windows, VM, VDI environment title: Run Docker Desktop for Windows in a VM or VDI environment aliases: -- /desktop/nested-virtualization/ -weight: 140 + - /desktop/nested-virtualization/ + - /desktop/vm-vdi/ +weight: 30 --- In general, we recommend running Docker Desktop natively on either Mac, Linux, or Windows. However, Docker Desktop for Windows can run inside a virtual desktop provided the virtual desktop is properly configured. @@ -17,7 +18,7 @@ To run Docker Desktop in a virtual desktop environment, it is essential nested v > > Support for running Docker Desktop on a virtual desktop is available to Docker Business customers, on VMware ESXi or Azure VMs only. -The support available from Docker extends to installing and running Docker Desktop inside the VM, once the nested virtualization is set up correctly. The only hypervisors we have successfully tested are VMware ESXi and Azure, and there is no support for other VMs. For more information on Docker Desktop support, see [Get support](support.md). +The support available from Docker extends to installing and running Docker Desktop inside the VM, once the nested virtualization is set up correctly. The only hypervisors we have successfully tested are VMware ESXi and Azure, and there is no support for other VMs. For more information on Docker Desktop support, see [Get support](/manuals/desktop/troubleshoot-and-support/support.md). For troubleshooting problems and intermittent failures that are outside of Docker's control, you should contact your hypervisor vendor. Each hypervisor vendor offers different levels of support. For example, Microsoft supports running nested Hyper-V both on-prem and on Azure, with some version constraints. This may not be the case for VMWare ESXi. diff --git a/content/manuals/desktop/support.md b/content/manuals/desktop/support.md deleted file mode 100644 index da98960154c..00000000000 --- a/content/manuals/desktop/support.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -description: See what support is available for Docker Desktop -keywords: Support, Docker Desktop, Linux, Mac, Windows -title: Get support -weight: 170 ---- - -Find information on how to get support, and the scope of Docker Desktop support. - -{{< cta - header-text="This feature requires a paid Docker subscription" - body="Docker Desktop offers support for developers subscribed to a Pro, Team, or a Business tier. Upgrade now to benefit from Docker Support." - url="https://www.docker.com/pricing?utm_source=docker&utm_medium=webreferral&utm_campaign=docs_driven_upgrade_desktop_support" - cta="Upgrade now" ->}} - -### How do I get Docker Desktop support? - -If you have a paid Docker subscription, raise a ticket through [Docker Desktop support](https://hub.docker.com/support/desktop/). - -Docker Community users can get support through our Github repos for-win, for-mac, for-linux, where we respond on a best-effort basis. - -### What support can I get? - -If you have a paid Docker subscription, you can request for support on the following types of issues: - -* Desktop upgrade issues -* Desktop installation issues - * Installation crashes - * Failure to launch Docker Desktop on first run -* Usage issues - * Crash closing software - * Docker Desktop not behaving as expected -* Configuration issues -* Basic product ‘how to’ questions - -For Windows users, you can also request support on: -* Enabling virtualization in BIOS -* Enabling Windows features - -### What is not supported? - -Docker Desktop excludes support for the following types of issues: - -* Use on or in conjunction with hardware or software other than that specified in the applicable documentation -* Running on unsupported operating systems, including beta/preview versions of operating systems -* Running containers of a different architecture using emulation -* Support for the Docker engine, Docker CLI, or other bundled Linux components -* Support for Kubernetes -* Features labeled as experimental -* System/Server administration activities -* Supporting Desktop as a production runtime -* Scale deployment/multi-machine installation of Desktop -* Routine product maintenance (data backup, cleaning disk space and configuring log rotation) -* Third-party applications not provided by Docker -* Altered or modified Docker software -* Defects in the Docker software due to hardware malfunction, abuse, or improper use -* Any version of the Docker software other than the latest version -* Reimbursing and expenses spent for third-party services not provided by Docker -* Docker Support excludes training, customization, and integration - ->Note -> -> Support for [running Docker Desktop in a VM or VDI environment](vm-vdi.md) is only available to Docker Business customers. - -### What versions are supported? - -We currently only offer support for the latest version of Docker Desktop. If you are running an older version, you may be asked to upgrade before we investigate your support request. - -### How many machines can I get support for Docker Desktop on? - -As a Pro user you can get support for Docker Desktop on a single machine. -As a Team, you can get support for Docker Desktop for the number of machines equal to the number of seats as part of your plan. - -### What OS’s are supported? - -Docker Desktop is available for Mac, Linux, and Windows. The supported version information can be found on the following pages: - -* [Mac system requirements](install/mac-install.md#system-requirements) -* [Windows system requirements](install/windows-install.md#system-requirements) -* [Linux system requirements](install/linux/_index.md#system-requirements) - -### How is personal diagnostic data handled in Docker Desktop? - -When uploading diagnostics to help Docker with investigating issues, the uploaded diagnostics bundle may contain personal data such as usernames and IP addresses. The diagnostics bundles are only accessible to Docker, Inc. -employees who are directly involved in diagnosing Docker Desktop issues. - -By default, Docker, Inc. will delete uploaded diagnostics bundles after 30 days. You may also request the removal of a diagnostics bundle by either specifying the diagnostics ID or via your GitHub ID (if the diagnostics ID is mentioned in a GitHub issue). Docker, Inc. will only use the data in the diagnostics bundle to investigate specific user issues but may derive high-level (non personal) metrics such as the rate of issues from it. - -For more information, see [Docker Data Processing Agreement](https://www.docker.com/legal/data-processing-agreement). diff --git a/content/manuals/desktop/troubleshoot-and-support/_index.md b/content/manuals/desktop/troubleshoot-and-support/_index.md new file mode 100644 index 00000000000..7cb0a4cd1ca --- /dev/null +++ b/content/manuals/desktop/troubleshoot-and-support/_index.md @@ -0,0 +1,6 @@ +--- +build: + render: never +title: Troubleshoot and support +weight: 50 +--- \ No newline at end of file diff --git a/content/manuals/desktop/faqs/_index.md b/content/manuals/desktop/troubleshoot-and-support/faqs/_index.md similarity index 53% rename from content/manuals/desktop/faqs/_index.md rename to content/manuals/desktop/troubleshoot-and-support/faqs/_index.md index 6f93f42c9dc..026ecb56855 100644 --- a/content/manuals/desktop/faqs/_index.md +++ b/content/manuals/desktop/troubleshoot-and-support/faqs/_index.md @@ -2,5 +2,7 @@ build: render: never title: FAQs -weight: 190 +weight: 30 +aliases: + - /desktop/faqs/ --- diff --git a/content/manuals/desktop/faqs/general.md b/content/manuals/desktop/troubleshoot-and-support/faqs/general.md similarity index 75% rename from content/manuals/desktop/faqs/general.md rename to content/manuals/desktop/troubleshoot-and-support/faqs/general.md index 6fbdaa921f4..54f80dd9545 100644 --- a/content/manuals/desktop/faqs/general.md +++ b/content/manuals/desktop/troubleshoot-and-support/faqs/general.md @@ -19,17 +19,17 @@ cannot access features that require an active internet connection. Additionally, any functionality that requires you to sign in won't work while using Docker Desktop offline or in air-gapped environments. This includes: -- The resources in the [Learning Center](../use-desktop/_index.md) +- The resources in the [Learning Center](/manuals/desktop/use-desktop/_index.md) - Pulling or pushing an image to Docker Hub -- [Image Access Management](../../security/for-developers/access-tokens.md) -- [Static vulnerability scanning](../../docker-hub/vulnerability-scanning.md) +- [Image Access Management](/manuals/security/for-developers/access-tokens.md) +- [Static vulnerability scanning](/manuals/docker-hub/repos/manage/vulnerability-scanning.md) - Viewing remote images in the Docker Dashboard -- Setting up [Dev Environments](../dev-environments/_index.md) +- Setting up [Dev Environments](/manuals/desktop/features/dev-environments/_index.md) - Docker Build when using [BuildKit](/manuals/build/buildkit/_index.md#getting-started). You can work around this by disabling BuildKit. Run `DOCKER_BUILDKIT=0 docker build .` to disable BuildKit. -- [Kubernetes](../kubernetes.md) (Images are download when you enable Kubernetes for the first time) +- [Kubernetes](/manuals/desktop/features/kubernetes.md) (Images are download when you enable Kubernetes for the first time) - Checking for updates -- [In-app diagnostics](/manuals/desktop/troubleshoot/_index.md#diagnose-from-the-app) (including the [Self-diagnose tool](/manuals/desktop/troubleshoot/_index.md#diagnose-from-the-app)) +- [In-app diagnostics](/manuals/desktop/troubleshoot-and-support/troubleshoot/_index.md#diagnose-from-the-app) (including the [Self-diagnose tool](/manuals/desktop/troubleshoot-and-support/troubleshoot/_index.md#diagnose-from-the-app)) - Sending usage statistics ### How do I connect to the remote Docker Engine API? @@ -59,12 +59,11 @@ The host has a changing IP address, or none if you have no network access. We recommend that you connect to the special DNS name `host.docker.internal`, which resolves to the internal IP address used by the host. -For more information and examples, see [how to connect from a container to a service on the host](../networking.md#i-want-to-connect-from-a-container-to-a-service-on-the-host). +For more information and examples, see [how to connect from a container to a service on the host](/manuals/desktop/features/networking.md#i-want-to-connect-from-a-container-to-a-service-on-the-host). ### Can I pass through a USB device to a container? -It is not possible to pass through a USB device (or a -serial port) to a container as it requires support at the hypervisor level. +Docker Desktop does not support direct USB device passthrough. However, you can use USB over IP to connect common USB devices to the Docker Desktop VM and in turn be forwarded to a container. For more details, see [Using USB/IP with Docker Desktop](/manuals/desktop/features/usbip.md). ### How do I run Docker Desktop without administrator privileges? @@ -90,7 +89,7 @@ You can then sign in to your machine with the user ID specified, and launch Dock > [!NOTE] > -> If you are using the WSL 2 backend, first make sure that you meet the [minimum required version](/manuals/desktop/wsl/best-practices.md) for WSL 2. Otherwise, update WSL 2 first. +> If you are using the WSL 2 backend, first make sure that you meet the [minimum required version](/manuals/desktop/features/wsl/best-practices.md) for WSL 2. Otherwise, update WSL 2 first. To run Docker Desktop on Windows without requiring administrator privileges, install via the command line and pass the `—always-run-service` installer flag. diff --git a/content/manuals/desktop/faqs/linuxfaqs.md b/content/manuals/desktop/troubleshoot-and-support/faqs/linuxfaqs.md similarity index 100% rename from content/manuals/desktop/faqs/linuxfaqs.md rename to content/manuals/desktop/troubleshoot-and-support/faqs/linuxfaqs.md diff --git a/content/manuals/desktop/faqs/macfaqs.md b/content/manuals/desktop/troubleshoot-and-support/faqs/macfaqs.md similarity index 99% rename from content/manuals/desktop/faqs/macfaqs.md rename to content/manuals/desktop/troubleshoot-and-support/faqs/macfaqs.md index b0730d96ce4..84b109f4a24 100644 --- a/content/manuals/desktop/faqs/macfaqs.md +++ b/content/manuals/desktop/troubleshoot-and-support/faqs/macfaqs.md @@ -67,7 +67,7 @@ To move the disk image file to a different location: 3. Select **Apply & Restart** for the changes to take effect. ->**Important** +> [!IMPORTANT] > > Do not move the file directly in Finder as this can cause Docker Desktop to lose track of the file. diff --git a/content/manuals/desktop/faqs/releases.md b/content/manuals/desktop/troubleshoot-and-support/faqs/releases.md similarity index 100% rename from content/manuals/desktop/faqs/releases.md rename to content/manuals/desktop/troubleshoot-and-support/faqs/releases.md diff --git a/content/manuals/desktop/faqs/windowsfaqs.md b/content/manuals/desktop/troubleshoot-and-support/faqs/windowsfaqs.md similarity index 92% rename from content/manuals/desktop/faqs/windowsfaqs.md rename to content/manuals/desktop/troubleshoot-and-support/faqs/windowsfaqs.md index 010fd2b27cf..949fc957435 100644 --- a/content/manuals/desktop/faqs/windowsfaqs.md +++ b/content/manuals/desktop/troubleshoot-and-support/faqs/windowsfaqs.md @@ -22,14 +22,14 @@ No, running Docker Desktop on Windows Server is not supported. ### Can I change permissions on shared volumes for container-specific deployment requirements? Docker Desktop does not enable you to control (`chmod`) -the Unix-style permissions on [shared volumes](/manuals/desktop/settings.md#file-sharing) for +the Unix-style permissions on [shared volumes](/manuals/desktop/settings-and-maintenance/settings.md#file-sharing) for deployed containers, but rather sets permissions to a default value of [0777](https://chmodcommand.com/chmod-0777/) (`read`, `write`, `execute` permissions for `user` and for `group`) which is not configurable. For workarounds and to learn more, see -[Permissions errors on data directories for shared volumes](../troubleshoot/topics.md#permissions-errors-on-data-directories-for-shared-volumes). +[Permissions errors on data directories for shared volumes](/manuals/desktop/troubleshoot-and-support/troubleshoot/topics.md#permissions-errors-on-data-directories-for-shared-volumes). ### How do symlinks work on Windows? @@ -71,7 +71,7 @@ You need to restart Docker Desktop after making any changes to the keychain or to the `~/.docker/certs.d` directory in order for the changes to take effect. The registry cannot be listed as an insecure registry (see -[Docker Daemon](/manuals/desktop/settings.md#docker-engine)). Docker Desktop ignores +[Docker Daemon](/manuals/desktop/settings-and-maintenance/settings.md#docker-engine)). Docker Desktop ignores certificates listed under insecure registries, and does not send client certificates. Commands like `docker run` that attempt to pull from the registry produce error messages on the command line, as well as on the registry. diff --git a/content/manuals/desktop/feedback.md b/content/manuals/desktop/troubleshoot-and-support/feedback.md similarity index 99% rename from content/manuals/desktop/feedback.md rename to content/manuals/desktop/troubleshoot-and-support/feedback.md index c0154b54377..513ef1e307e 100644 --- a/content/manuals/desktop/feedback.md +++ b/content/manuals/desktop/troubleshoot-and-support/feedback.md @@ -3,7 +3,7 @@ description: Find a way to provide feedback that's right for you keywords: Feedback, Docker Desktop, Linux, Mac, Windows, Dev Environments, Extensions, Community forum, bugs, problems, issues title: Give feedback -weight: 180 +weight: 40 --- There are many ways you can provide feedback on Docker Desktop or Docker Desktop features. diff --git a/content/manuals/support.md b/content/manuals/desktop/troubleshoot-and-support/support.md similarity index 52% rename from content/manuals/support.md rename to content/manuals/desktop/troubleshoot-and-support/support.md index afad26228d5..6d53c2bf928 100644 --- a/content/manuals/support.md +++ b/content/manuals/desktop/troubleshoot-and-support/support.md @@ -1,14 +1,18 @@ --- -description: Get support -keywords: Support, Docker Desktop, Docker Hub, Hub, Linux, Mac, Windows +description: See what support is available for Docker Desktop +keywords: Support, Docker Desktop, Linux, Mac, Windows title: Get support +weight: 20 aliases: -- /desktop/support/ + - /desktop/support/ + - /support/ --- -Find information on how to get support, and the scope of support. +> [!NOTE] +> +> Docker Desktop offers support for developers with a [Pro, Team, or Business subscription](https://www.docker.com/pricing?utm_source=docker&utm_medium=webreferral&utm_campaign=docs_driven_upgrade_desktop_support). -## How do I get support? +### How do I get Docker Desktop support? If you have a paid Docker subscription, you can [contact the Support team](https://hub.docker.com/support/contact/). @@ -19,12 +23,9 @@ All Docker users can seek support through the following resources, where Docker - [Docker Community Forums](https://forums.docker.com/) - [Docker Community Slack](http://dockr.ly/comm-slack) +### What support can I get? -## What support can I get? - -If you have a paid Docker subscription, you can get support for the following types of issues: - - * Account management related issues +* Account management related issues * Automated builds * Basic product 'how to' questions * Billing or subscription issues @@ -42,50 +43,54 @@ If you have a paid Docker subscription, you can get support for the following ty For Windows users, you can also request support on: * Turning on virtualization in BIOS * Turning on Windows features - * Running inside [certain VM or VDI environments](/manuals/desktop/vm-vdi.md) (Docker Business customers only) - - -## What is not supported? - -Docker excludes support for the following types of issues: - * Altered or modified Docker software - * Any version of the Docker software other than the latest version - * Defects in the Docker software due to hardware malfunction, abuse, or improper use - * Docker support excludes training, customization, and integration - * Features labeled as experimental or beta - * Reimbursing and expenses spent for third-party services not provided by Docker - * Routine product maintenance (data backup, cleaning disk space and configuring log rotation) - * Running containers of a different architecture using emulation - * Running on unsupported operating systems, including beta or preview versions of operating systems - * Scale deployment/multi-machine installation of Desktop - * Support for Kubernetes - * Support for the Docker Engine, Docker CLI, or other bundled Linux components - * Supporting Desktop as a production runtime - * System/Server administration activities - * Third-party applications not provided by Docker - * Use on or in conjunction with hardware or software other than that specified in the applicable documentation - * Running multiple instances of Docker Desktop on a single machine - -## What Docker Desktop versions are supported? + * Running inside [certain VM or VDI environments](/manuals/desktop/setup/vm-vdi.md) (Docker Business customers only) + +### What is not supported? + +Docker Desktop excludes support for the following types of issues: + +* Use on or in conjunction with hardware or software other than that specified in the applicable documentation +* Running on unsupported operating systems, including beta/preview versions of operating systems +* Running containers of a different architecture using emulation +* Support for the Docker engine, Docker CLI, or other bundled Linux components +* Support for Kubernetes +* Features labeled as experimental +* System/Server administration activities +* Supporting Desktop as a production runtime +* Scale deployment/multi-machine installation of Desktop +* Routine product maintenance (data backup, cleaning disk space and configuring log rotation) +* Third-party applications not provided by Docker +* Altered or modified Docker software +* Defects in the Docker software due to hardware malfunction, abuse, or improper use +* Any version of the Docker software other than the latest version +* Reimbursing and expenses spent for third-party services not provided by Docker +* Docker support excludes training, customization, and integration +* Running multiple instances of Docker Desktop on a single machine + +> [!NOTE] +> +> Support for [running Docker Desktop in a VM or VDI environment](/manuals/desktop/setup/vm-vdi.md) is only available to Docker Business customers. + +### What versions are supported? For Docker Business customers, Docker offers support for versions up to six months older than the latest version, although any fixes will be on the latest version. For Pro and Team customers, Docker only offers support for the latest version of Docker Desktop. If you are running an older version, Docker may ask you to update before investigating your support request. -## How many machines can I get support for Docker Desktop on? +### How many machines can I get support for Docker Desktop on? As a Pro user you can get support for Docker Desktop on a single machine. -As a Team user, you can get support for Docker Desktop for the number of machines equal to the number of seats as part of your plan. +As a Team, you can get support for Docker Desktop for the number of machines equal to the number of seats as part of your plan. -## What OS’s are supported? +### What OS’s are supported? Docker Desktop is available for Mac, Linux, and Windows. The supported version information can be found on the following pages: -* [Mac system requirements](/manuals/desktop/install/mac-install.md#system-requirements) -* [Windows system requirements](/manuals/desktop/install/windows-install.md#system-requirements) -* [Linux system requirements](/manuals/desktop/install/linux/_index.md#system-requirements) +* [Mac system requirements](/manuals/desktop/setup/install/mac-install.md#system-requirements) +* [Windows system requirements](/manuals/desktop/setup/install/windows-install.md#system-requirements) +* [Linux system requirements](/manuals/desktop/setup/install/linux/_index.md#system-requirements) -## How is personal diagnostic data handled in Docker Desktop? +### How is personal diagnostic data handled in Docker Desktop? When uploading diagnostics to help Docker with investigating issues, the uploaded diagnostics bundle may contain personal data such as usernames and IP addresses. The diagnostics bundles are only accessible to Docker, Inc. employees who are directly involved in diagnosing Docker Desktop issues. @@ -93,9 +98,3 @@ employees who are directly involved in diagnosing Docker Desktop issues. By default, Docker, Inc. will delete uploaded diagnostics bundles after 30 days. You may also request the removal of a diagnostics bundle by either specifying the diagnostics ID or via your GitHub ID (if the diagnostics ID is mentioned in a GitHub issue). Docker, Inc. will only use the data in the diagnostics bundle to investigate specific user issues but may derive high-level (non personal) metrics such as the rate of issues from it. For more information, see [Docker Data Processing Agreement](https://www.docker.com/legal/data-processing-agreement). - -## What can I do before seeking support? - -Before seeking support, you can perform basic troubleshooting. See [Diagnose and troubleshooting](/manuals/desktop/troubleshoot/_index.md) for more information. - -You can also see if an answer already exists in the [FAQs](/tags/faq/). diff --git a/content/manuals/desktop/troubleshoot/_index.md b/content/manuals/desktop/troubleshoot-and-support/troubleshoot/_index.md similarity index 95% rename from content/manuals/desktop/troubleshoot/_index.md rename to content/manuals/desktop/troubleshoot-and-support/troubleshoot/_index.md index c0ebc886399..6ef3148e36b 100644 --- a/content/manuals/desktop/troubleshoot/_index.md +++ b/content/manuals/desktop/troubleshoot-and-support/troubleshoot/_index.md @@ -15,8 +15,9 @@ aliases: - /docker-for-win/troubleshoot/ - /docker-for-windows/troubleshoot/ - /desktop/troubleshoot/overview/ +- /desktop/troubleshoot/ tags: [ Troubleshooting ] -weight: 160 +weight: 10 --- This page contains information on how to diagnose and troubleshoot Docker Desktop, and how to check the logs. @@ -25,14 +26,14 @@ This page contains information on how to diagnose and troubleshoot Docker Deskto To navigate to **Troubleshoot** either: -- Select the Docker menu Docker menu {{< inline-image src="../images/whale-x.svg" alt="whale menu" >}} and then **Troubleshoot**. +- Select the Docker menu Docker menu {{< inline-image src="../../images/whale-x.svg" alt="whale menu" >}} and then **Troubleshoot**. - Select the **Troubleshoot** icon near the top-right corner of Docker Dashboard. The **Troubleshooting** menu contains the following options: - **Restart Docker Desktop**. -- **Reset Kubernetes cluster**. Select to delete all stacks and Kubernetes resources. For more information, see [Kubernetes](/manuals/desktop/settings.md#kubernetes). +- **Reset Kubernetes cluster**. Select to delete all stacks and Kubernetes resources. For more information, see [Kubernetes](/manuals/desktop/settings-and-maintenance/settings.md#kubernetes). - **Clean / Purge data**. This option resets all Docker data without a reset to factory defaults. Selecting this option results in the loss of existing settings. @@ -65,7 +66,7 @@ If you are a Mac or Linux user, you also have the option to **Uninstall** Docker - If you have a paid Docker subscription, select **Contact support**. This opens the Docker Desktop support form. Fill in the information required and add the ID you copied in step three to the **Diagnostics ID field**. Then, select **Submit ticket** to request Docker Desktop support. > [!NOTE] > - > You must be signed in to Docker Desktop to access the support form. For information on what's covered as part of Docker Desktop support, see [Support](../../support/_index.md). + > You must be signed in to Docker Desktop to access the support form. For information on what's covered as part of Docker Desktop support, see [Support](/manuals/desktop/troubleshoot-and-support/support.md). - If you don't have a paid Docker subscription, select **Report a Bug** to open a new Docker Desktop issue on GitHub. Complete the information required and ensure you add the diagnostic ID you copied in step three. ### Diagnose from an error message @@ -76,7 +77,7 @@ If you are a Mac or Linux user, you also have the option to **Uninstall** Docker - If you have a paid Docker subscription, select **Contact support**. This opens the Docker Desktop support form. Fill in the information required and add the ID you copied in step three to the **Diagnostics ID field**. Then, select **Submit ticket** to request Docker Desktop support. > [!NOTE] > - > You must be signed in to Docker Desktop to access the support form. For information on what's covered as part of Docker Desktop support, see [Support](../../support/_index.md). + > You must be signed in to Docker Desktop to access the support form. For information on what's covered as part of Docker Desktop support, see [Support](/manuals/desktop/troubleshoot-and-support/support.md). - If you don't have a paid Docker subscription, you can open a new Docker Desktop issue on GitHub for [Mac](https://github.com/docker/for-mac/issues), [Windows](https://github.com/docker/for-win/issues), or [Linux](https://github.com/docker/for-linux/issues). Complete the information required and ensure you add the diagnostic ID printed in step two. ### Diagnose from the terminal @@ -284,7 +285,7 @@ Spotlight Search. To read the Docker app log messages, type `docker` in the Console window search bar and press Enter. Then select `ANY` to expand the drop-down list next to your `docker` search entry, and select `Process`. -![Mac Console search for Docker app](../images/console.png) +![Mac Console search for Docker app](../../images/console.png) You can use the Console Log Query to search logs, filter the results in various ways, and create reports. diff --git a/content/manuals/desktop/troubleshoot/known-issues.md b/content/manuals/desktop/troubleshoot-and-support/troubleshoot/known-issues.md similarity index 99% rename from content/manuals/desktop/troubleshoot/known-issues.md rename to content/manuals/desktop/troubleshoot-and-support/troubleshoot/known-issues.md index 72e91f77b0f..6cef6929241 100644 --- a/content/manuals/desktop/troubleshoot/known-issues.md +++ b/content/manuals/desktop/troubleshoot-and-support/troubleshoot/known-issues.md @@ -4,6 +4,8 @@ keywords: mac, troubleshooting, known issues, Docker Desktop title: Known issues tags: [ Troubleshooting ] weight: 30 +aliases: + - /desktop/troubleshoot/known-issues/ --- {{< tabs >}} diff --git a/content/manuals/desktop/troubleshoot/topics.md b/content/manuals/desktop/troubleshoot-and-support/troubleshoot/topics.md similarity index 92% rename from content/manuals/desktop/troubleshoot/topics.md rename to content/manuals/desktop/troubleshoot-and-support/troubleshoot/topics.md index 03295f3b299..f43344eca3a 100644 --- a/content/manuals/desktop/troubleshoot/topics.md +++ b/content/manuals/desktop/troubleshoot-and-support/troubleshoot/topics.md @@ -6,6 +6,8 @@ linkTitle: Common topics toc_max: 4 tags: [ Troubleshooting ] weight: 10 +aliases: + - /desktop/troubleshoot/topics/ --- > [!TIP] @@ -57,7 +59,7 @@ After updating the `settings-store.json` file, close and restart Docker Desktop If you are using mounted volumes and get runtime errors indicating an application file is not found, access to a volume mount is denied, or a service cannot start, such as when using [Docker Compose](/manuals/compose/gettingstarted.md), -you might need to turn on [file sharing](/manuals/desktop/settings.md#file-sharing). +you might need to turn on [file sharing](/manuals/desktop/settings-and-maintenance/settings.md#file-sharing). Volume mounting requires shared drives for projects that live outside of the `/home/` directory. From **Settings**, select **Resources** and then **File sharing**. Share the drive that contains the Dockerfile and volume. @@ -103,7 +105,7 @@ If not, the command prints `kern.hv_support: 0`. See also, [Hypervisor Framework Reference](https://developer.apple.com/library/mac/documentation/DriversKernelHardware/Reference/Hypervisor/) -in the Apple documentation, and Docker Desktop [Mac system requirements](../install/mac-install.md#system-requirements). +in the Apple documentation, and Docker Desktop [Mac system requirements](/manuals/desktop/setup/install/mac-install.md#system-requirements). ### VPNKit keeps breaking @@ -117,7 +119,7 @@ To continue using VPNKit, add `"networkType":"vpnkit"` to your `settings-store.j #### Permissions errors on data directories for shared volumes -When sharing files from Windows, Docker Desktop sets permissions on [shared volumes](/manuals/desktop/settings.md#file-sharing) +When sharing files from Windows, Docker Desktop sets permissions on [shared volumes](/manuals/desktop/settings-and-maintenance/settings.md#file-sharing) to a default value of [0777](https://chmodcommand.com/chmod-0777/) (`read`, `write`, `execute` permissions for `user` and for `group`). @@ -128,7 +130,7 @@ volumes or find a way to make the applications work with the default file permissions. See also, -[Can I change permissions on shared volumes for container-specific deployment requirements?](../faqs/windowsfaqs.md#can-i-change-permissions-on-shared-volumes-for-container-specific-deployment-requirements) +[Can I change permissions on shared volumes for container-specific deployment requirements?](/manuals/desktop/troubleshoot-and-support/faqs/windowsfaqs.md#can-i-change-permissions-on-shared-volumes-for-container-specific-deployment-requirements) in the FAQs. #### Volume mounting requires shared folders for Linux containers @@ -136,14 +138,14 @@ in the FAQs. If you are using mounted volumes and get runtime errors indicating an application file is not found, access is denied to a volume mount, or a service cannot start, such as when using [Docker Compose](/manuals/compose/gettingstarted.md), -you might need to turn on [shared folders](/manuals/desktop/settings.md#file-sharing). +you might need to turn on [shared folders](/manuals/desktop/settings-and-maintenance/settings.md#file-sharing). With the Hyper-V backend, mounting files from Windows requires shared folders for Linux containers. From **Settings**, select **Shared Folders** and share the folder that contains the Dockerfile and volume. #### Support for symlinks -Symlinks work within and across containers. To learn more, see [How do symlinks work on Windows?](../faqs/windowsfaqs.md#how-do-symlinks-work-on-windows). +Symlinks work within and across containers. To learn more, see [How do symlinks work on Windows?](/manuals/desktop/troubleshoot-and-support/faqs/windowsfaqs.md#how-do-symlinks-work-on-windows). #### Avoid unexpected syntax errors, use Unix style line endings for files in containers @@ -263,7 +265,7 @@ Your machine must have the following features for Docker Desktop to function cor Note that many Windows devices already have virtualization enabled, so this may not apply. 4. Hypervisor enabled at Windows startup -![WSL 2 enabled](../images/wsl2-enabled.png) +![WSL 2 enabled](../../images/wsl2-enabled.png) #### Hyper-V @@ -275,7 +277,7 @@ On Windows 10 Pro or Enterprise, you can also use Hyper-V with the following fea Note that many Windows devices already have virtualization enabled, so this may not apply. 3. Hypervisor enabled at Windows startup -![Hyper-V on Windows features](../images/hyperv-enabled.png) +![Hyper-V on Windows features](../../images/hyperv-enabled.png) Docker Desktop requires Hyper-V as well as the Hyper-V Module for Windows PowerShell to be installed and enabled. The Docker Desktop installer enables @@ -290,15 +292,15 @@ In the subsequent screen, verify that Hyper-V is enabled. #### Virtualization must be turned on -In addition to [Hyper-V](#hyper-v) or [WSL 2](../wsl/_index.md), virtualization must be turned on. Check the +In addition to [Hyper-V](#hyper-v) or [WSL 2](/manuals/desktop/features/wsl/_index.md), virtualization must be turned on. Check the Performance tab on the Task Manager. Alternatively, you can type 'systeminfo' into your terminal. If you see 'Hyper-V Requirements: A hypervisor has been detected. Features required for Hyper-V will not be displayed', then virtualization is enabled. -![Task Manager](../images/virtualization-enabled.png) +![Task Manager](../../images/virtualization-enabled.png) If you manually uninstall Hyper-V, WSL 2 or turn off virtualization, Docker Desktop cannot start. -To turn on nested virtualization, see [Run Docker Desktop for Windows in a VM or VDI environment](../vm-vdi.md#turn-on-nested-virtualization). +To turn on nested virtualization, see [Run Docker Desktop for Windows in a VM or VDI environment](/manuals/desktop/setup/vm-vdi.md#turn-on-nested-virtualization). #### Hypervisor enabled at Windows startup @@ -321,13 +323,13 @@ If you are using Hyper-V and you get the following error message when running Do The Virtual Machine Management Service failed to start the virtual machine 'DockerDesktopVM' because one of the Hyper-V components is not running ``` -Try [enabling nested virtualization](../vm-vdi.md#turn-on-nested-virtualization). +Try [enabling nested virtualization](/manuals/desktop/setup/vm-vdi.md#turn-on-nested-virtualization). ### Windows containers and Windows Server Docker Desktop is not supported on Windows Server. If you have questions about how to run Windows containers on Windows 10, see -[Switch between Windows and Linux containers](../faqs/windowsfaqs.md#how-do-i-switch-between-windows-and-linux-containers). +[Switch between Windows and Linux containers](/manuals/desktop/troubleshoot-and-support/faqs/windowsfaqs.md#how-do-i-switch-between-windows-and-linux-containers). A full tutorial is available in [docker/labs](https://github.com/docker/labs) on [Getting Started with Windows Containers](https://github.com/docker/labs/blob/master/windows/windows-containers/README.md). diff --git a/content/manuals/desktop/troubleshoot/workarounds.md b/content/manuals/desktop/troubleshoot-and-support/troubleshoot/workarounds.md similarity index 97% rename from content/manuals/desktop/troubleshoot/workarounds.md rename to content/manuals/desktop/troubleshoot-and-support/troubleshoot/workarounds.md index ac4f55f0131..8720454e17e 100644 --- a/content/manuals/desktop/troubleshoot/workarounds.md +++ b/content/manuals/desktop/troubleshoot-and-support/troubleshoot/workarounds.md @@ -4,6 +4,8 @@ keywords: linux, mac, windows, troubleshooting, workarounds, Docker Desktop title: Workarounds for common problems tags: [ Troubleshooting ] weight: 20 +aliases: + - /desktop/troubleshoot/workarounds/ --- ### Reboot diff --git a/content/manuals/desktop/uninstall.md b/content/manuals/desktop/uninstall.md index 8551bfa7615..d394967be91 100644 --- a/content/manuals/desktop/uninstall.md +++ b/content/manuals/desktop/uninstall.md @@ -10,7 +10,7 @@ weight: 210 > > Uninstalling Docker Desktop destroys Docker containers, images, volumes, and > other Docker-related data local to the machine, and removes the files generated -> by the application. To learn how to preserve important data before uninstalling, refer to the [back up and restore data](backup-and-restore.md) section . +> by the application. To learn how to preserve important data before uninstalling, refer to the [back up and restore data](/manuals/desktop/settings-and-maintenance/backup-and-restore.md) section . {{< tabs >}} {{< tab name="Windows" >}} diff --git a/content/manuals/desktop/use-desktop/_index.md b/content/manuals/desktop/use-desktop/_index.md index 70d13dcf225..b7b309cf6b1 100644 --- a/content/manuals/desktop/use-desktop/_index.md +++ b/content/manuals/desktop/use-desktop/_index.md @@ -20,7 +20,7 @@ The **Volumes** view displays a list of volumes and allows you to easily create The **Builds** view lets you inspect your build history and manage builders. By default, it displays a list of all your ongoing and completed builds. [Explore builds](builds.md). -In addition, the Docker Desktop Dashboard let you: +In addition, the Docker Desktop Dashboard lets you: - Navigate to the **Settings** menu to configure your Docker Desktop settings. Select the **Settings** icon in the Dashboard header. - Access the **Troubleshoot** menu to debug and perform restart operations. Select the **Troubleshoot** icon in the Dashboard header. @@ -30,6 +30,8 @@ In addition, the Docker Desktop Dashboard let you: For a more detailed guide about getting started, see [Get started](/get-started/introduction/_index.md). - Get to the [Docker Scout](../../scout/_index.md) dashboard. - Check the status of Docker services. +- Access [Docker Hub](/manuals/docker-hub/_index.md) to search, browse, pull, run, or view details + of images. ## Quick search diff --git a/content/manuals/desktop/use-desktop/builds.md b/content/manuals/desktop/use-desktop/builds.md index 4d0b066dd35..ed469449a25 100644 --- a/content/manuals/desktop/use-desktop/builds.md +++ b/content/manuals/desktop/use-desktop/builds.md @@ -211,4 +211,4 @@ The **Builder settings** view in the Docker Desktop settings lets you: ![Builder settings drop-down](../images/build-ui-manage-builders.webp) -For more information about managing builders, see [Change settings](/manuals/desktop/settings.md#builders) +For more information about managing builders, see [Change settings](/manuals/desktop/settings-and-maintenance/settings.md#builders) diff --git a/content/manuals/desktop/use-desktop/images.md b/content/manuals/desktop/use-desktop/images.md index 7fbfe2c0c98..c44b7b477d8 100644 --- a/content/manuals/desktop/use-desktop/images.md +++ b/content/manuals/desktop/use-desktop/images.md @@ -87,10 +87,10 @@ To remove individual images, select the bin icon. The **Images** view also allows you to manage and interact with images in Docker Hub repositories. By default, when you go to **Images** in Docker Desktop, you see a list of images that exist in your local image store. -The **Local** and **Hub** tabs near the top toggles between viewing images in your local image store, +The **Local** and **Hub repositories** tabs near the top toggles between viewing images in your local image store, and images in remote Docker Hub repositories that you have access to. -Switching to the **Hub** tab prompts you to sign in to your Docker Hub account, if you're not already signed in. +Switching to the **Hub repositories** tab prompts you to sign in to your Docker Hub account, if you're not already signed in. When signed in, it shows you a list of images in Docker Hub organizations and repositories that you have access to. Select an organization from the drop-down to view a list of repositories for that organization. diff --git a/content/manuals/desktop/use-desktop/resource-saver.md b/content/manuals/desktop/use-desktop/resource-saver.md index 929163bf23e..4b14ec6dd2c 100644 --- a/content/manuals/desktop/use-desktop/resource-saver.md +++ b/content/manuals/desktop/use-desktop/resource-saver.md @@ -63,15 +63,15 @@ feature, as it results in much better CPU and memory savings. Resource Saver works a bit differently on Windows with WSL. Instead of stopping the WSL VM, it only pauses the Docker Engine inside the -`docker-desktop` WSL distro. That's because in WSL there's a single Linux VM -shared by all WSL distros, so Docker Desktop can't stop the Linux VM (i.e., +`docker-desktop` WSL distribution. That's because in WSL there's a single Linux VM +shared by all WSL distributions, so Docker Desktop can't stop the Linux VM (i.e., the WSL Linux VM is not owned by Docker Desktop). As a result, Resource Saver reduces CPU utilization on WSL, but it does not reduce Docker's memory utilization. To reduce memory utilization on WSL, we instead recommend that users enable WSL's `autoMemoryReclaim` feature as described in the -[Docker Desktop WSL docs](../wsl/_index.md). Finally, since Docker Desktop does not +[Docker Desktop WSL docs](/manuals/desktop/features/wsl/_index.md). Finally, since Docker Desktop does not stop the Linux VM on WSL, exit from Resource Saver mode is immediate (there's no exit delay). diff --git a/content/manuals/desktop/use-desktop/volumes.md b/content/manuals/desktop/use-desktop/volumes.md index 0b045ba705c..b065d83a5ef 100644 --- a/content/manuals/desktop/use-desktop/volumes.md +++ b/content/manuals/desktop/use-desktop/volumes.md @@ -119,10 +119,6 @@ To empty a volume: ## Export a volume -{{% experimental title="Beta feature" %}} -The export volume feature is currently in [Beta](../../release-lifecycle.md#beta). -{{% /experimental %}} - You can export the content of a volume to a local file, a local image, an to an image in Docker Hub, or to a supported cloud provider. When exporting content from a volume used by one or more running containers, the containers are @@ -148,15 +144,12 @@ You can either [export a volume now](#export-a-volume-now) or [schedule a recurr - **Local image**: Select a local image to export the content to. Any existing data in the image will be replaced by the exported content. - **New image**: Specify a name for the new image. - - **Registry**: Specify a Docker Hub repository. Note that Docker Hub - repositories can be publicly accessible which means your data can be - publicly accessible. For more details, see - [Change a repository from public to private](/docker-hub/repos/#change-a-repository-from-public-to-private). + - **Registry**: Specify a Docker Hub repository. {{< /tab >}} {{< tab name="External cloud storage" >}} - You must have a [Docker Business subscription](../../subscription/core-subscription/details.md) to export to an external cloud provider. + You must have a [Docker Business subscription](../../subscription/details.md) to export to an external cloud provider. Select your cloud provider and then specify the URL to upload to the storage. Refer to the following documentation for your cloud provider to learn how to @@ -173,7 +166,7 @@ You can either [export a volume now](#export-a-volume-now) or [schedule a recurr ### Schedule a volume export -1. Sign in to Docker Desktop. You must be signed in and have a paid [Docker subscription](../../subscription/core-subscription/details.md) to schedule a volume export. +1. Sign in to Docker Desktop. You must be signed in and have a paid [Docker subscription](../../subscription/details.md) to schedule a volume export. 2. In the **Volumes** view, select the volume you want to export. 3. Select the **Exports** tab. 4. Select **Schedule export**. @@ -197,15 +190,12 @@ You can either [export a volume now](#export-a-volume-now) or [schedule a recurr - **Local image**: Select a local image to export the content to. Any existing data in the image will be replaced by the exported content. - **New image**: Specify a name for the new image. - - **Registry**: Specify a Docker Hub repository. Note that Docker Hub - repositories can be publicly accessible which means your data can be - publicly accessible. For more details, see - [Change a repository from public to private](/docker-hub/repos/#change-a-repository-from-public-to-private). + - **Registry**: Specify a Docker Hub repository. {{< /tab >}} {{< tab name="External cloud storage" >}} - You must have a [Docker Business subscription](../../subscription/core-subscription/details.md) to export to an external cloud provider. + You must have a [Docker Business subscription](../../subscription/details.md) to export to an external cloud provider. Select your cloud provider and then specify the URL to upload to the storage. Refer to the following documentation for your cloud provider to learn how to diff --git a/content/manuals/docker-hub/_index.md b/content/manuals/docker-hub/_index.md index 43e867a23b0..c47f97f76dc 100644 --- a/content/manuals/docker-hub/_index.md +++ b/content/manuals/docker-hub/_index.md @@ -1,59 +1,56 @@ --- -description: Find a comprehensive overview of Docker Hub, including its features, administrative settings, how to get started quickly, and more -keywords: Docker, docker, docker hub, hub, repositories, docker account -title: Overview of Docker Hub -linkTitle: Docker Hub -weight: 100 +description: Get an overview on Docker Hub to find and share container images +keywords: docker hub, hub, repositories +title: Docker Hub +weight: 30 +params: + sidebar: + group: Products grid: - title: Quickstart description: Step-by-step instructions on getting started on Docker Hub. icon: explore link: /docker-hub/quickstart -- title: Create a repository +- title: Library + description: Explore the content library, featuring millions of images for operating systems, frameworks, databases, and more. + icon: book + link: /docker-hub/image-library/ +- title: Repositories description: Create a repository to share your images with your team, customers, or the Docker community. icon: inbox link: /docker-hub/repos -- title: Manage repository access - description: Manage access to push and pull to your repository and assign permissions. - icon: key - link: /docker-hub/repos/access -- title: Automated builds - description: Learn how you can automatically build images from source code to push to your repositories. - icon: build - link: /docker-hub/builds/how-builds-work +- title: Organizations + description: Learn about organization administration. + icon: store + link: /admin/ +- title: Usage + description: Explore usage limits and how to better utilize Docker Hub. + icon: leaderboard + link: /docker-hub/download-rate-limit/ - title: Release notes description: Find out about new features, improvements, and bug fixes. icon: note_add link: /docker-hub/release-notes --- -Docker Hub is a service provided by Docker for finding and sharing container images. +Docker Hub simplifies development with the world's largest container registry +for storing, managing, and sharing Docker images. By integrating seamlessly with +your tools, it enhances productivity and ensures reliable deployment, +distribution, and access to containerized applications. It also provides +developers with pre-built images and assets to speed up development workflows. -It's the world’s largest repository of container images with an array of content sources including container community developers, open source projects, and independent software vendors (ISV) building and distributing their code in containers. +Key features of Docker Hub: -Docker Hub is also where you can go to [carry out administrative tasks for organizations](/admin/). If you have a Docker Team or Business subscription, you can also carry out administrative tasks in the [Docker Admin Console](https://admin.docker.com). +* Unlimited public repositories +* Private repositories +* Webhooks to automate workflows +* GitHub and Bitbucket integrations +* Concurrent and automated builds +* Trusted content featuring high-quality, secure images -{{< tabs >}} -{{< tab name="What key features are included in Docker Hub?" >}} -* [Repositories](../docker-hub/repos/_index.md): Push and pull container images. -* [Builds](builds/_index.md): Automatically build container images from -GitHub and Bitbucket and push them to Docker Hub. -* [Webhooks](webhooks.md): Trigger actions after a successful push - to a repository to integrate Docker Hub with other services. -* [Docker Hub CLI](https://github.com/docker/hub-tool#readme) tool (currently experimental) and an API that allows you to interact with Docker Hub. - * Browse through the [Docker Hub API](/reference/api/hub/latest/) documentation to explore the supported endpoints. -{{< /tab >}} -{{< tab name="What administrative tasks can I perform in Docker Hub?" >}} -* [Create and manage teams and organizations](orgs.md) -* [Create a company](../admin/company/new-company.md) -* [Enforce sign in](../security/for-admins/enforce-sign-in/_index.md) -* Set up [SSO](../security/for-admins/single-sign-on/_index.md) and [SCIM](../security/for-admins/provisioning/scim.md) -* Use [Group mapping](group-mapping.md) -* [Carry out domain audits](domain-audit.md) -* [Use Image Access Management](/manuals/security/for-admins/hardened-desktop/image-access-management.md) to control developers' access to certain types of images -* [Turn on Registry Access Management](/manuals/security/for-admins/hardened-desktop/registry-access-management.md) -{{< /tab >}} -{{< /tabs >}} +In addition to the graphical interface, you can interact with Docker Hub using +the [Docker Hub API](../../reference/api/hub/latest.md) or experimental [Docker +Hub CLI tool](https://github.com/docker/hub-tool#readme). {{< grid >}} diff --git a/content/manuals/docker-hub/builds/images/index-report.png b/content/manuals/docker-hub/builds/images/index-report.png deleted file mode 100644 index 03b7c4a423b..00000000000 Binary files a/content/manuals/docker-hub/builds/images/index-report.png and /dev/null differ diff --git a/content/manuals/docker-hub/download-rate-limit.md b/content/manuals/docker-hub/download-rate-limit.md index 82afc75af2a..477d40625f4 100644 --- a/content/manuals/docker-hub/download-rate-limit.md +++ b/content/manuals/docker-hub/download-rate-limit.md @@ -1,21 +1,20 @@ --- description: Learn about usage and rate limits for Docker Hub. -keywords: Docker Hub, pulls, download, limit, usage +keywords: Docker Hub, pulls, download, limit, usage, storage title: Docker Hub usage and rate limits linkTitle: Usage and rate limits weight: 30 --- -{{< include "new-plans.md" >}} - Docker may impose usage and rate limits for Docker Hub to ensure fair resource consumption and maintain service quality. Understanding your usage helps you manage your and your organization's usage effectively. ## Usage -Usage refers to the amount of data transferred from Docker Hub and the amount of -data stored on Docker Hub. +Usage refers to both: +- Pulls: The amount of data transferred from Docker Hub +- Storage: The amount of data stored on Docker Hub ### Fair use @@ -27,23 +26,37 @@ exhibiting excessive data and storage consumption. ### View Docker Hub usage -You can download a CSV file of your or your organization's Docker Hub usage. To -download the file: +1. Sign in to [Docker Hub](https://hub.docker.com). + + If you want to download usage for all members of an organization, you must + sign in to an account that is an owner for that organization. Otherwise, + you can only view your own personal usage. + +2. In Docker Hub, select **Usage** from the top-level navigation menu. +3. In the drop-down, select whether you want to view your personal or organization data. +4. The usage page displays **Pulls** and **Storage** usage. +5. Select a usage type and use the available filters to view usage. + +### Download Docker Hub pulls usage + +You can download a CSV file of your or your organization's Docker Hub pulls usage. You can't download a CSV file for storage usage. + +To download the pulls usage file: 1. Sign in to [Docker Hub](https://hub.docker.com). If you want to download usage for all members of an organization, you must sign in to an account that is an owner for that organization. Otherwise, - you can only view your own usage. + you can only view your own personal usage. -2. In Docker Hub, navigate to the [**Usage** page](https://hub.docker.com/usage). -3. In the drop-down, select whether to download your personal data or - data for an organization. -4. In **From** and **To**, select a date range for the data. -5. Select **Send report to email** to have Docker email you a link to the data +2. In Docker Hub, select **Usage** from the top-level navigation menu. +3. In the drop-down, select whether you want to view your personal or organization data. +4. Optional. Use the **Filter by privacy** drop-down to select **Public** or **Private** pulls. +5. Use the **From** and **To** filters to select a date range for the data. +6. Select **Send report to email** to have Docker email you a link to the data file. Note that email processing time may vary. -The file contains the following comma separated values. +The file contains the following comma separated values: | CSV column | Definition | Usage guidance | |----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -53,15 +66,15 @@ The file contains the following comma separated values. | `access_token_name` | Name of the access token that was used for authentication with Docker CLI. `generated` tokens are automatically generated by the Docker client when a user signs in. | Personal access tokens are usually used to authenticate automated tools (Docker Desktop, CI/CD tools, etc.). This is useful for identifying which automated system issued the pull. | | `ips` | The IP address that was used to pull the image. This field is aggregated, so more than one IP address may appear, representing all the IPs used to pull an image within the same date and hour. | This helps you understand the origin of the data transfer, which is useful for diagnosing and identifying patterns in automated or manual pulls. | | `repository_privacy` | The privacy state of the image repository that was pulled. This can either be `public` or `private`. | This distinguishes between public and private repositories to identify which data transfer threshold the pull impacts. | -| `tag` | The tag for the image. The tag is only available if the pull request included a tag. | This helps in identifying the image. Tags are often used to identify specific versions or variants of an image. | +| `tag` | The tag for the image. The tag is only available if the pull included a tag. | This helps in identifying the image. Tags are often used to identify specific versions or variants of an image. | | `digest` | The unique image digest for the image. | This helps in identifying the image. | -| `version_checks` | The number of version checks accumulated for the date and hour of each image repository. Depending on the client, a pull request can do a version check to verify the existence of an image or tag without downloading it. | This helps identify the frequency of version checks, which you can use to analyze usage trends and potential unexpected behaviors. | +| `version_checks` | The number of version checks accumulated for the date and hour of each image repository. Depending on the client, a pull can do a version check to verify the existence of an image or tag without downloading it. | This helps identify the frequency of version checks, which you can use to analyze usage trends and potential unexpected behaviors. | | `pulls` | The number of pulls accumulated for the date and hour of each image repository. | This helps identify the frequency of repository pulls, which you can use to analyze usage trends and potential unexpected behaviors. | -### Optimize and manage Docker Hub usage +### Best practices for managing Docker Hub usage Use the following steps to help optimize and manage your Docker Hub usage for -both individuals and organizations. +both individuals and organizations: 1. [View your Docker Hub usage](#view-docker-hub-usage). @@ -77,7 +90,7 @@ both individuals and organizations. pipelines, may be causing higher pull rates, and configure them to avoid unnecessary image pulls. -3. Optimize image pulls by doing the following: +3. Optimize image pulls by: - Use caching: Implement local image caching via [mirroring](/docker-hub/mirror/) or within your CI/CD pipelines to reduce @@ -85,11 +98,13 @@ both individuals and organizations. - Automate manual workflows: Avoid unnecessary pulls by configuring automated systems to pull only when a new version of an image is available. -4. Optimize the size of repositories by regularly auditing and removing - untagged, unused, or outdated images. +4. Optimize your storage by: + + - Regularly audit and remove repositories with untagged, unused, or outdated images. + - Look for private repositories in Hub storage that exceed your plan's limits. -5. Increase your limits by upgrading or purchasing add-ons. For details, see - [Docker pricing](https://www.docker.com/pricing/). +5. Increase your limits by upgrading or purchasing additional consumption. For + details, see [Scale your subscription](../subscription/scale.md). 6. For organizations, monitor and enforce organizational policies by doing the following: @@ -97,101 +112,129 @@ both individuals and organizations. - Routinely [view Docker Hub usage](#view-docker-hub-usage) to monitor usage. - [Enforce sign-in](/security/for-admins/enforce-sign-in/) to ensure that you can monitor the usage of your users and users receive higher usage limits. + - Look for duplicate user accounts in Docker and remove accounts from your organization + as needed. + +## Storage and repository limits + +{{< include "hub-limits.md" >}} + +The following storage and repository limits apply based on your subscription, subject to fair use: + +| Plan | Public repositories | Public repository storage | Private repositories | Private repository storage | +|----------|---------------------|---------------------------|----------------------------|----------------------------| +| Personal | Unlimited | Unlimited | Up to 1 private repository | Up to 2 GB | +| Pro | Unlimited | Unlimited | Unlimited | Up to 5 GB | +| Team | Unlimited | Unlimited | Unlimited | Up to 50 GB | +| Business | Unlimited | Unlimited | Unlimited | Up to 500 GB | + -## Pull attribution +Private repository storage is calculated on a monthly basis based on the average +storage used throughout the month per organization. Docker measures your storage +usage in the amount of Bytes stored per hour, which are accumulated throughout +the month to determine your monthly storage. If a repository is private at any +point within an hour, it is counted as private for the full hour. The total +hours are calculated based on the actual number of days in the month. Any +storage usage beyond the included amounts in each paid subscription tier will be +charged at an on-demand rate. You can [scale your +limit](../subscription/scale.md) or [upgrade](../subscription/change.md) to get +a higher limit. + +For more information on how Docker Hub storage pricing is calculated, see the [Docker Hub storage pricing](/manuals/billing/docker-hub-pricing.md) guide. + +## Pull limit and rate limit + +A pull is defined as the following: + + - A Docker pull includes both a version check and any download that + occurs as a result of the pull. Depending on the client, a `docker pull` can + verify the existence of an image or tag without downloading it by performing + a version check. + - Version checks do not count towards usage pricing. + - A pull for a normal image makes one pull for a [single + manifest](https://github.com/opencontainers/image-spec/blob/main/manifest.md). + - A pull for a multi-arch image will count as one pull for each + different architecture. + +### Pull attribution Pulls can be attributed to either a personal or organization [namespace](https://docs.docker.com/contribute/style/terminology/#namespace). -### Private pulls +#### Private pulls Pulls for private repositories are attributed to the repository's namespace owner. -### Public pulls +#### Public pulls When pulling images from a public repository, attribution is determined based on domain affiliation and organization membership. -### Verified domain ownership +#### Verified domain ownership When pulling an image from an account linked to a verified domain, the attribution is set to be the owner of that [domain](https://docs.docker.com/security/faqs/single-sign-on/domain-faqs/) -### Single organization membership +#### Single organization membership - If the owner of the verified domain is a company and the user is part of only one organization within that [company](https://docs.docker.com/admin/faqs/company-faqs/#what-features-are-supported-at-the-company-level), the pull is attributed to that specific organization. - If the user is part of only one organization, the pull is attributed to that specific organization. -### Multiple organization memberships +#### Multiple organization memberships If the user is part of multiple organizations under the company, the pull is attributed to the user's personal namespace. -## Rate limit +### Pull limit -A user's rate limit is equal to the highest entitlement of their personal -account or any organization they belong to. To take advantage of this, you must -sign in to [Docker Hub](https://hub.docker.com/) as an authenticated user. For +Rate limits apply to pull usage. A user's rate limit is equal to the highest entitlement of their personal account or any organization they belong to. To take advantage of this, you must sign in to [Docker Hub](https://hub.docker.com/) as an authenticated user. For more information, see [How do I authenticate pull -requests](#how-do-i-authenticate-pull-requests). Unauthenticated (anonymous) +requests](#how-do-i-authenticate-pulls). Unauthenticated (anonymous) users will have the limits enforced via IP. -- Pulls are accounted to the user doing the pull, not to the owner of the image. -- A pull request is defined as up to two `GET` requests on registry manifest -URLs (`/v2/*/manifests/*`). -- A normal image pull makes a single manifest request. -- A pull request for a multi-arch image makes two manifest requests. -- `HEAD` requests aren't counted. -- Some images are unlimited through the [Docker Sponsored Open - Source](https://www.docker.com/blog/expanded-support-for-open-source-software-projects/) - and [Docker Verified Publisher](https://www.docker.com/partners/programs) - programs. +Pull limit refers to the total number of image pulls allowed within a specific time frame. For example, a Business plan has a total pull limit of 1M pulls per month. +The pull limit is calculated on a per month basis and only applies to +Docker Pro, Docker Team, and Docker Business users. The limit automatically +scales on-demand, but on-demand rates do apply. You can [scale your +limit](../subscription/scale.md) or [upgrade](../subscription/change.md) to get +a higher limit. -> [!IMPORTANT] -> -> Docker is introducing enhanced subscription plans. Our new plans are packed -> with more features, higher usage limits, and simplified pricing. The new -> subscription plans take effect at your next renewal date that occurs on or -> after November 1, 2024. No charges on Docker Hub image pulls or storage will -> be incurred between November 15, 2024, and January 31, 2025. See [Announcing -> Upgraded Docker -> Plans](https://www.docker.com/blog/november-2024-updated-plans-announcement/) -> for more details and learn how your usage fits into these updates. -> -> Note that when these changes take effect, the following new definition of a -> pull request and limits will take effect: -> -> - A Docker pull request includes both a version check and any download that -> occurs as a result of the pull. Depending on the client, a `docker pull` can -> verify the existence of an image or tag without downloading it by performing -> a version check. -> - A pull request for a normal image makes one pull for a [single -> manifest](https://github.com/opencontainers/image-spec/blob/main/manifest.md). -> - A pull request for a multi-arch image will count as one pull for each -> different architecture. -> - Pulls are accounted to the user doing the pull, not to the owner of the -> image. -> -> There will be no image pull rate limit for users or automated systems with a -> paid subscription. Anonymous and Docker Personal users using Docker Hub will -> experience rate limits on image pull requests. For authenticated users, there -> will be a 40 pull/hour rate limit per user; for unauthenticated usage, there -> will be a 10 pull/hour rate limit per IP address. -### What's the download rate limit on Docker Hub? +| User type | Pull count per month | +|--------------------------|----------------------| +| Business (authenticated) | 1M | +| Team (authenticated) | 100K | +| Pro (authenticated) | 25K | +| Personal (authenticated) | Not applicable | +| Unauthenticated users | Not applicable | -Docker Hub limits the number of Docker image downloads, or pulls, based on the -account type of the user pulling the image. Pull rate limits are based on -individual IP address. +### Pull rate limit -| User type | Rate limit | -|-------------------------------------------------------------------------|--------------------------------------| -| Anonymous users | 100 pulls per 6 hours per IP address | -| [Authenticated users](#how-do-i-authenticate-pull-requests) | 200 pulls per 6 hour period | -| Users with a paid [Docker subscription](https://www.docker.com/pricing) | Up to 5000 pulls per day | +Pull rate limit refers to the frequency of image pulls per unit of time, specifying how quickly you can pull images within a specific time. -If you require a higher number of pulls, you can also buy an [Enhanced Service Account add-on](service-accounts.md#enhanced-service-account-add-on-pricing). +The pull rate limit is calculated on a per hour basis. There is no +pull rate limit for users or automated systems with a paid subscription. +Unauthenticated and Docker Personal users using Docker Hub will experience rate +limits on image pulls. -### How do I know my pull requests are being limited? +The following table describes the pull rate limit per hour +for each subscription tier, subject to fair use: -When you issue a pull request and you are over the limit, Docker Hub returns a +| User type | Pull rate limit per hour | +|--------------------------|--------------------------| +| Business (authenticated) | No limit | +| Team (authenticated) | No limit | +| Pro (authenticated) | No limit | +| Personal (authenticated) | 40 | +| Unauthenticated users | 10 per IP address | + +> [!TIP] +> +> Always sign in to Docker. Authenticated Docker Personal users receive +> increased rate limits, while authenticated Docker Pro, Team, and Business +> users are not rate limited. For more information, see [How do I authenticate +> pulls](#how-do-i-authenticate-pulls). + +#### How do I know my pulls are being limited? + +When you issue a pull and you are over the limit, Docker Hub returns a `429` response code with the following body when the manifest is requested: ```text @@ -200,7 +243,7 @@ You have reached your pull rate limit. You may increase the limit by authenticat This error message appears in the Docker CLI or in the Docker Engine logs. -### How can I check my current rate? +#### How can I check my current rate? Valid API requests to Hub usually include the following rate limit headers in the response: @@ -213,7 +256,7 @@ docker-ratelimit-source These headers are returned on both GET and HEAD requests. ->**Note** +> [!NOTE] > > Using GET emulates a real pull and counts towards the limit. Using HEAD won't. > To check your limits, you need `curl`, `grep`, and `jq` installed. @@ -248,20 +291,17 @@ docker-ratelimit-source: 192.0.2.1 In the previous example, the pull limit is 100 pulls per 21600 seconds (6 hours), and there are 76 pulls remaining. -#### I don't see any RateLimit headers - If you don't see any RateLimit header, it could be because the image or your IP is unlimited in partnership with a publisher, provider, or an open source organization. It could also mean that the user you are pulling as is part of a -paid Docker plan. Pulling that image won’t count toward pull limits if you don’t -see these headers. However, users with a paid Docker subscription pulling more -than 5000 times daily require a [Service -Account](../docker-hub/service-accounts.md) subscription. +paid Docker plan. Pulling that image won’t count toward pull rate limits if you +don't see these headers. Note that users with a paid subscription have a monthly +pull limit that can be viewed in the Docker Hub [usage dashboard](#view-docker-hub-usage). -### I'm being limited to a lower rate even though I have a paid Docker subscription +#### I'm being limited to a lower rate even though I have a paid Docker subscription -To take advantage of the higher limits included in a paid Docker subscription, -you must [authenticate pulls](#how-do-i-authenticate-pull-requests) with your +To take advantage of the unlimited limits included in a paid Docker subscription, +you must [authenticate pulls](#how-do-i-authenticate-pulls) with your user account. A Pro, Team, or a Business tier doesn't increase limits on your images for other @@ -270,25 +310,25 @@ Source](https://www.docker.com/blog/expanded-support-for-open-source-software-pr [Publisher](https://www.docker.com/partners/programs), or [Large Organization](https://www.docker.com/pricing) offerings. -### Other limits +#### Other limits -Docker Hub also has an overall rate limit to protect the application and +Docker Hub also has an abuse rate limit to protect the application and infrastructure. This limit applies to all requests to Hub properties including web pages, APIs, and image pulls. The limit is applied per-IP, and while the limit changes over time depending on load and other factors, it's in the order -of thousands of requests per minute. The overall rate limit applies to all users +of thousands of requests per minute. The abuse limit applies to all users equally regardless of account level. You can differentiate between these limits by looking at the error code. The -"overall limit" returns a simple `429 Too Many Requests` response. The pull +"abuse limit" returns a simple `429 Too Many Requests` response. The pull limit returns a longer error message that includes a link to this page. -## How do I authenticate pull requests? +### How do I authenticate pulls? The following section contains information on how to sign in to Docker Hub to -authenticate pull requests. +authenticate pulls. -### Docker Desktop +#### Docker Desktop If you are using Docker Desktop, you can sign in to Docker Hub from the Docker Desktop menu. @@ -296,13 +336,13 @@ Desktop menu. Select **Sign in / Create Docker ID** from the Docker Desktop menu and follow the on-screen instructions to complete the sign-in process. -### Docker Engine +#### Docker Engine If you're using a standalone version of Docker Engine, run the `docker login` command from a terminal to authenticate with Docker Hub. For information on how to use the command, see [docker login](/reference/cli/docker/login.md). -### Docker Swarm +#### Docker Swarm If you're running Docker Swarm, you must use the `--with-registry-auth` flag to authenticate with Docker Hub. For more information, see [Create a @@ -310,21 +350,21 @@ service](/reference/cli/docker/service/create.md#with-registry-auth). If you are using a Docker Compose file to deploy an application stack, see [docker stack deploy](/reference/cli/docker/stack/deploy.md). -### GitHub Actions +#### GitHub Actions If you're using GitHub Actions to build and push Docker images to Docker Hub, see [login action](https://github.com/docker/login-action#dockerhub). If you are using another Action, you must add your username and access token in a similar way for authentication. -### Kubernetes +#### Kubernetes If you're running Kubernetes, follow the instructions in [Pull an Image from a Private Registry](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/) for information on authentication. -### Third-party platforms +#### Third-party platforms If you're using any third-party platforms, follow your provider’s instructions on using registry authentication. diff --git a/content/manuals/docker-hub/image-library/_index.md b/content/manuals/docker-hub/image-library/_index.md new file mode 100644 index 00000000000..3d41410ff1f --- /dev/null +++ b/content/manuals/docker-hub/image-library/_index.md @@ -0,0 +1,22 @@ +--- +description: Learn about Docker Hub's library of images, extensions, and plugins. +keywords: Docker Hub, Hub, content library +title: Content library +linkTitle: Library +weight: 20 +--- + +Docker Hub's content library is the world's largest collection of +container images, extensions, and plugins. It provides a central location to +discover pre-built images and tools designed to streamline your container +workflows, making it easier to share and collaborate. + +In this section, learn about: + +- [Search](./search.md): Discover how to browse and search Docker Hub's extensive resources. +- [Trusted content](./trusted-content.md): Dive into Docker Official Images, + Verified Publisher content, and Sponsored Open Source images, all vetted for + security and reliability to streamline your workflows. +- [Catalogs](./catalogs.md): Explore specialized collections like the generative AI catalog. +- [Mirroring](./mirror.md): Learn how to create a mirror of Docker Hub's + container image library as a pull-through cache. \ No newline at end of file diff --git a/content/manuals/docker-hub/image-library/catalogs.md b/content/manuals/docker-hub/image-library/catalogs.md new file mode 100644 index 00000000000..066ce8c5647 --- /dev/null +++ b/content/manuals/docker-hub/image-library/catalogs.md @@ -0,0 +1,59 @@ +--- +description: Explore specialized Docker Hub collections like the Generative AI catalog. +keywords: Docker Hub, Hub, catalog +title: Docker Hub catalogs +linkTitle: Catalogs +weight: 60 +--- + +Docker Hub catalogs are your go-to collections of trusted, ready-to-use +container images and resources, tailored to meet specific development needs. +They make it easier to find high-quality, pre-verified content so you can +quickly build, deploy, and manage your applications with confidence. Catalogs in +Docker Hub: + +- Simplify content discovery: Organized and curated content makes it easy to + discover tools and resources tailored to your specific domain or technology. +- Reduce complexity: Trusted resources, vetted by Docker and its partners, + ensure security, reliability, and adherence to best practices. +- Accelerate development: Quickly integrate advanced capabilities into your + applications without the hassle of extensive research or setup. + +The generative AI catalog is the first catalog in Docker Hub, offering +specialized content for AI development. + +## Generative AI catalog + +The [generative AI catalog](https://hub.docker.com/catalogs/gen-ai) makes it +easy to explore and add AI capabilities to your applications. With trusted, +ready-to-use content and comprehensive documentation, you can skip the hassle of +sorting through countless tools and configurations. Instead, focus your time and +energy on creating innovative AI-powered applications. + +The generative AI catalog provides a wide range of trusted content, organized +into key areas to support diverse AI development needs: + +- Demos: Ready-to-deploy examples showcasing generative AI capabilities. These + demos provide a hands-on way to explore AI tools and frameworks, making it + easier to understand how they can be integrated into real-world applications. +- Models: Pre-trained AI models for tasks like text generation, + Natural Language Processing (NLP), and conversational AI. These models + provide a foundation for + AI applications without requiring developers to train models from scratch. +- Applications and end-to-end platforms: Comprehensive platforms and tools that + simplify AI application development, including low-code solutions and + frameworks for building multi-agent and Retrieval-Augmented Generation (RAG) + applications. +- Model deployment and serving: Tools and frameworks that enable developers to + efficiently deploy and serve AI models in production environments. These + resources include pre-configured stacks for GPUs and other specialized + hardware, ensuring performance at scale. +- Orchestration: Solutions for managing complex AI workflows, such as workflow + engines, Large Language Model (LLM) application frameworks, and lifecycle management + tools, to help streamline development and operations. +- Machine learning frameworks: Popular frameworks like TensorFlow and PyTorch + that provide the building blocks for creating, training, and fine-tuning + machine learning models. +- Databases: Databases optimized for AI workloads, including vector databases + for similarity search, time-series databases for analytics, and NoSQL + solutions for handling unstructured data. \ No newline at end of file diff --git a/content/manuals/docker-hub/mirror.md b/content/manuals/docker-hub/image-library/mirror.md similarity index 97% rename from content/manuals/docker-hub/mirror.md rename to content/manuals/docker-hub/image-library/mirror.md index 71cd160db95..7b993055cc9 100644 --- a/content/manuals/docker-hub/mirror.md +++ b/content/manuals/docker-hub/image-library/mirror.md @@ -2,12 +2,13 @@ description: Setting-up a local mirror for Docker Hub images keywords: registry, on-prem, images, tags, repository, distribution, mirror, Hub, recipe, advanced -title: Registry as a pull through cache -linkTitle: Mirroring +title: Mirror the Docker Hub library +linkTitle: Mirror weight: 80 aliases: - /engine/admin/registry_mirror/ - /registry/recipes/mirror/ +- /docker-hub/mirror/ --- ## Use-case @@ -37,7 +38,7 @@ Hub can be mirrored. > [!NOTE] > -> Mirrors of Docker Hub are still subject to Docker's [fair use policy](./download-rate-limit.md#fair-use). +> Mirrors of Docker Hub are still subject to Docker's [fair use policy](/manuals/docker-hub/download-rate-limit.md#fair-use). ### Solution diff --git a/content/manuals/docker-hub/image-library/search.md b/content/manuals/docker-hub/image-library/search.md new file mode 100644 index 00000000000..fff381ae49d --- /dev/null +++ b/content/manuals/docker-hub/image-library/search.md @@ -0,0 +1,167 @@ +--- +description: Discover how to browse and search Docker Hub's extensive resources. +keywords: Docker Hub, Hub, explore, search, image library +title: Docker Hub search +linkTitle: Search +weight: 10 +--- + +The [Docker Hub search interface](https://hub.docker.com/search) lets you +explore millions of resources. To help you find exactly what you need, it offers +a variety of filters that let you narrow your results or discover different +types of content. + +## Filters + +The search functionality includes filters to narrow down +results based on your requirements, such as products, categories, and trusted +content. This ensures that you can quickly find and access the resources best +suited to your project. + +### Products + +Docker Hub's content library features three products, each designed to meet +specific needs of developers and organizations. These products include images, +plugins, and extensions. + +#### Images + +Docker Hub hosts millions of container images, making it the go-to repository +for containerized applications and solutions. These images include: + +- Operating system images: Foundational images for Linux distributions like + Ubuntu, Debian, and Alpine, or Windows Server images. +- Database and storage images: Pre-configured databases such as MySQL, + PostgreSQL, and MongoDB to simplify application development. +- Languages and frameworks-based images: Popular images for Java, Python, + Node.js, Ruby, .NET, and more, offering pre-built environments for faster + development. + +Images in Docker Hub simplify the development process by providing pre-built, +reusable building blocks, reducing the need to start from scratch. Whether +you're a beginner building your first container or an enterprise managing +complex architectures, Docker Hub images provide a reliable foundation. + +#### Plugins + +Plugins in Docker Hub let you extend and customize Docker Engine to suit +specialized requirements. Plugins integrate directly with the Docker Engine and +provide capabilities such as: + +- Network plugins: Enhance networking functionality, enabling integration with + complex network infrastructures. +- Volume plugins: Provide advanced storage options, supporting persistent and + distributed storage across various backends. +- Authorization plugins: Offer fine-grained access control to secure Docker + environments. + +By leveraging Docker plugins, teams can tailor Docker Engine to meet their +specific operational needs, ensuring compatibility with existing infrastructures +and workflows. + +To learn more about plugins, see [Docker Engine managed plugin +system](/manuals/engine/extend/_index.md). + +#### Extensions + +Docker Hub offers extensions for Docker Desktop, which enhance its core +functionality. These extensions are purpose-built to streamline the software +development lifecycle. Extensions provide tools for: + +- System optimization and monitoring: Manage resources and optimize Docker + Desktop’s performance. +- Container management: Simplify container deployment and monitoring. +- Database management: Facilitate efficient database operations within + containers. +- Kubernetes and cloud integration: Bridge local environments with cloud-native + and Kubernetes workflows. +- Visualization tools: Gain insights into container resource usage through + graphical representations. + +Extensions help developers and teams create a more efficient and unified +workflow by reducing context switching and bringing essential tools into Docker +Desktop's interface. + +To learn more about extensions, see [Docker +Extensions](/manuals/extensions/_index.md). + +### Trusted content + +Docker Hub's trusted content provides a curated selection of high-quality, +secure images designed to give developers confidence in the reliability and +security of the resources they use. These images are stable, regularly updated, +and adhere to industry best practices, making them a strong foundation for +building and deploying applications. Docker Hub's trusted content includes, +Docker Official Images, Verified Publisher images, and Docker-Sponsored Open +Source Software images. + +For more details, see [Trusted content](./trusted-content.md). + +### Categories + +Docker Hub makes it easy to find and explore container images with categories. +Categories group images based on their primary use case, helping you quickly +locate the tools and resources you need to build, deploy, and run your +applications. + +{{< include "hub-categories.md" >}} + +### Operating systems + +The **Operating systems** filter lets you narrow your search to container +images compatible with specific host operating systems. This filter ensures that +the images you use align with your target environment, whether you're developing +for Linux-based systems, Windows, or both. + +- **Linux**: Access a wide range of images tailored for Linux environments. + These images provide foundational environments for building and running + Linux-based applications in containers. +- **Windows**: Explore Windows container images. + +> [!NOTE] +> +> The **Operating systems** filter is only available for images. If you select +> the **Extensions** or **Plugins** filter, then the **Operating systems** +> filter isn't available. + +### Architectures + +The **Architectures** filter lets you find images built to support specific CPU +architectures. This ensures compatibility with your hardware environment, from +development machines to production servers. + +- **ARM**: Select images compatible with ARM processors, commonly used in IoT + devices and embedded systems. +- **ARM 64**: Locate 64-bit ARM-compatible images for modern ARM processors, + such as those in AWS Graviton or Apple Silicon. +- **IBM POWER**: Find images optimized for IBM Power Systems, offering + performance and reliability for enterprise workloads. +- **PowerPC 64 LE**: Access images designed for the little-endian PowerPC 64-bit + architecture. +- **IBM Z**: Discover images tailored for IBM Z mainframes, ensuring + compatibility with enterprise-grade hardware. +- **x86**: Choose images compatible with 32-bit x86 architectures, suitable for + older systems or lightweight environments. +- **x86-64**: Filter images for modern 64-bit x86 systems, widely used in + desktops, servers, and cloud infrastructures. + +> [!NOTE] +> +> The **Architectures** filter is only available for images. If you select the +> **Extensions** or **Plugins** filter, then the **Architectures** filter isn't +> available. + +### Reviewed by Docker + +The **Reviewed by Docker** filter provides an extra layer of assurance when +selecting extensions. This filter helps you identify whether a Docker Desktop +extension has been reviewed by Docker for quality and reliability. + +- **Reviewed**: Extensions that have undergone Docker's review process, ensuring + they meet high standards. +- **Not Reviewed**: Extensions that have not been reviewed by Docker. + +> [!NOTE] +> +> The **Reviewed by Docker** filter is only available for extensions. To make +> the filter available, you must select only the **Extensions** filter in **Products**. \ No newline at end of file diff --git a/content/manuals/trusted-content/official-images/using.md b/content/manuals/docker-hub/image-library/trusted-content.md similarity index 53% rename from content/manuals/trusted-content/official-images/using.md rename to content/manuals/docker-hub/image-library/trusted-content.md index 21d0a2689ba..518ccfce6db 100644 --- a/content/manuals/trusted-content/official-images/using.md +++ b/content/manuals/docker-hub/image-library/trusted-content.md @@ -1,18 +1,62 @@ --- -title: Using Docker Official Images -description: | - Learn about building applications with Docker Official images - and how to interpret the tag names they use. -keywords: docker official images, doi, tags, slim, feedback, troubleshooting -weight: 10 +description: Learn about Docker Hub's trusted content. +keywords: Docker Hub, Hub, trusted content +title: Trusted content +weight: 15 +aliases: +- /trusted-content/official-images/using/ +- /trusted-content/official-images/ --- -Docker recommends you use the Docker Official Images in your projects. -These images have clear documentation, promote best practices, and are regularly updated. -Docker Official Images support most common use cases, making them perfect for new Docker users. -Advanced users can benefit from more specialized image variants as well as review Docker Official Images as part of your `Dockerfile` learning process. +Docker Hub's trusted content provides a curated selection of high-quality, +secure images designed to give developers confidence in the reliability and +security of the resources they use. These images are stable, regularly updated, +and adhere to industry best practices, making them a strong foundation for +building and deploying applications. Docker Hub's trusted content includes, +Docker Official Images, Verified Publisher images, and Docker-Sponsored Open +Source Software images. -## Tags +## Docker Official Images + +The Docker Official Images are a curated set of Docker repositories hosted on +Docker Hub. + +Docker recommends you use the Docker Official Images in your projects. These +images have clear documentation, promote best practices, and are regularly +updated. Docker Official Images support most common use cases, making them +perfect for new Docker users. Advanced users can benefit from more specialized +image variants as well as review Docker Official Images as part of your +`Dockerfile` learning process. + +> [!NOTE] +> +> Use of Docker Official Images is subject to [Docker's Terms of Service](https://www.docker.com/legal/docker-terms-service/). + +These images provide essential base repositories that serve as the starting +point for the majority of users. + +These include operating systems such as +[Ubuntu](https://hub.docker.com/_/ubuntu/) and +[Alpine](https://hub.docker.com/_/alpine/), programming language runtimes such as +[Python](https://hub.docker.com/_/python) and +[Node](https://hub.docker.com/_/node), and other essential tools such as +[memcached](https://hub.docker.com/_/memcached) and +[MySQL](https://hub.docker.com/_/mysql). + +The images are some of the [most secure images](https://www.docker.com/blog/enhancing-security-and-transparency-with-docker-official-images/) +on Docker Hub. This is particularly important as Docker Official Images are +some of the most popular on Docker Hub. Typically, Docker Official images have +few or no packages containing CVEs. + +The images exemplify [Dockerfile best practices](/manuals/build/building/best-practices.md) +and provide clear documentation to serve as a reference for other Dockerfile authors. + +Images that are part of this program have a special badge on Docker Hub making +it easier for you to identify projects that are part of Docker Official Images. + +![Docker official image badge](../images/official-image-badge-iso.png) + +### Supported tags and respective Dockerfile links The repository description for each Docker Official Image contains a **Supported tags and respective Dockerfile links** section that lists all the @@ -34,7 +78,7 @@ use or are unfamiliar with the underlying software, you should probably start wi the `latest` image. As your understanding of the software and image variants advances, you may find other image variants better suit your needs. -## Slim images +### Slim images A number of language stacks such as [Node.js](https://hub.docker.com/_/node/), @@ -62,7 +106,7 @@ COPY --from=build /app /app CMD ["node", "app.js"] ``` -## Alpine images +### Alpine images Many Docker Official Images repositories also offer `alpine` variants. These images are built on top of the [Alpine Linux](https://www.alpinelinux.org/) @@ -90,7 +134,7 @@ to make your program compatible with Alpine Linux and musl: Refer to the `alpine` image [description](https://hub.docker.com/_/alpine) on Docker Hub for examples on how to install packages if you are unfamiliar. -## Codenames +### Codenames Tags with words that look like Toy Story characters (for example, `bookworm`, `bullseye`, and `trixie`) or adjectives (such as `focal`, `jammy`, and @@ -103,11 +147,37 @@ Linux distribution indicators are helpful because many Docker Official Images provide variants built upon multiple underlying distribution versions (for example, `postgres:bookworm` and `postgres:bullseye`). -## Other tags +### Other tags Docker Official Images tags may contain other hints to the purpose of their image variant in addition to those described here. Often these tag variants are explained in the Docker Official Images repository -documentation. Reading through the “How to use this image” and -“Image Variants” sections will help you to understand how to use these +documentation. Reading through the "How to use this image" and +"Image Variants" sections will help you to understand how to use these variants. + +## Verified Publisher images + +The Docker Verified Publisher program provides high-quality images from +commercial publishers verified by Docker. + +These images help development teams build secure software supply chains, +minimizing exposure to malicious content early in the process to save time and +money later. + +Images that are part of this program have a special badge on Docker Hub making +it easier for users to identify projects that Docker has verified as +high-quality commercial publishers. + +![Docker-Sponsored Open Source badge](../images/verified-publisher-badge-iso.png) + +## Docker-Sponsored Open Source Software images + +The Docker-Sponsored Open Source Software (OSS) program provides images that are +published and maintained by open-source projects sponsored by Docker. + +Images that are part of this program have a special badge on Docker Hub making +it easier for users to identify projects that Docker has verified as trusted, +secure, and active open-source projects. + +![Docker-Sponsored Open Source badge](../images/sponsored-badge-iso.png) \ No newline at end of file diff --git a/content/manuals/trusted-content/images/chart-share-icon.png b/content/manuals/docker-hub/images/chart-share-icon.png similarity index 100% rename from content/manuals/trusted-content/images/chart-share-icon.png rename to content/manuals/docker-hub/images/chart-share-icon.png diff --git a/content/manuals/trusted-content/images/chart.png b/content/manuals/docker-hub/images/chart.png similarity index 100% rename from content/manuals/trusted-content/images/chart.png rename to content/manuals/docker-hub/images/chart.png diff --git a/content/manuals/trusted-content/images/clear_logo_sm.png b/content/manuals/docker-hub/images/clear_logo_sm.png similarity index 100% rename from content/manuals/trusted-content/images/clear_logo_sm.png rename to content/manuals/docker-hub/images/clear_logo_sm.png diff --git a/content/manuals/trusted-content/images/default_logo_sm.png b/content/manuals/docker-hub/images/default_logo_sm.png similarity index 100% rename from content/manuals/trusted-content/images/default_logo_sm.png rename to content/manuals/docker-hub/images/default_logo_sm.png diff --git a/content/manuals/trusted-content/images/download-analytics-data.png b/content/manuals/docker-hub/images/download-analytics-data.png similarity index 100% rename from content/manuals/trusted-content/images/download-analytics-data.png rename to content/manuals/docker-hub/images/download-analytics-data.png diff --git a/content/manuals/docker-hub/images/index-tag.webp b/content/manuals/docker-hub/images/index-tag.webp deleted file mode 100644 index 078de74ae96..00000000000 Binary files a/content/manuals/docker-hub/images/index-tag.webp and /dev/null differ diff --git a/content/manuals/trusted-content/images/official-image-badge-iso.png b/content/manuals/docker-hub/images/official-image-badge-iso.png similarity index 100% rename from content/manuals/trusted-content/images/official-image-badge-iso.png rename to content/manuals/docker-hub/images/official-image-badge-iso.png diff --git a/content/manuals/trusted-content/images/organization-tabs.png b/content/manuals/docker-hub/images/organization-tabs.png similarity index 100% rename from content/manuals/trusted-content/images/organization-tabs.png rename to content/manuals/docker-hub/images/organization-tabs.png diff --git a/content/manuals/trusted-content/images/sponsored-badge-iso.png b/content/manuals/docker-hub/images/sponsored-badge-iso.png similarity index 100% rename from content/manuals/trusted-content/images/sponsored-badge-iso.png rename to content/manuals/docker-hub/images/sponsored-badge-iso.png diff --git a/content/manuals/trusted-content/images/sponsored-badge.png b/content/manuals/docker-hub/images/sponsored-badge.png similarity index 100% rename from content/manuals/trusted-content/images/sponsored-badge.png rename to content/manuals/docker-hub/images/sponsored-badge.png diff --git a/content/manuals/trusted-content/images/supported_tags.webp b/content/manuals/docker-hub/images/supported_tags.webp similarity index 100% rename from content/manuals/trusted-content/images/supported_tags.webp rename to content/manuals/docker-hub/images/supported_tags.webp diff --git a/content/manuals/trusted-content/images/upload_logo_sm.png b/content/manuals/docker-hub/images/upload_logo_sm.png similarity index 100% rename from content/manuals/trusted-content/images/upload_logo_sm.png rename to content/manuals/docker-hub/images/upload_logo_sm.png diff --git a/content/manuals/trusted-content/images/verified-publisher-badge-iso.png b/content/manuals/docker-hub/images/verified-publisher-badge-iso.png similarity index 100% rename from content/manuals/trusted-content/images/verified-publisher-badge-iso.png rename to content/manuals/docker-hub/images/verified-publisher-badge-iso.png diff --git a/content/manuals/trusted-content/images/verified-publisher-badge.png b/content/manuals/docker-hub/images/verified-publisher-badge.png similarity index 100% rename from content/manuals/trusted-content/images/verified-publisher-badge.png rename to content/manuals/docker-hub/images/verified-publisher-badge.png diff --git a/content/manuals/docker-hub/quickstart.md b/content/manuals/docker-hub/quickstart.md index 6930b9836ee..6d1f1d29fd0 100644 --- a/content/manuals/docker-hub/quickstart.md +++ b/content/manuals/docker-hub/quickstart.md @@ -1,148 +1,326 @@ --- description: Learn how to get started using Docker Hub -keywords: Docker, docker, registry, accounts, plans, Dockerfile, Docker Hub, accounts, - organizations, repositories, groups, teams +keywords: Docker Hub, push image, pull image, repositories title: Docker Hub quickstart linkTitle: Quickstart weight: 10 --- -The following section contains step-by-step instructions on how to get started with Docker Hub. +Docker Hub provides a vast library of pre-built images and resources, +accelerating development workflows and reducing setup time. You can build upon +pre-built images from Docker Hub and then use repositories to share and +distribute your own images with your team or millions of other developers. -### Step 1: Sign up for a free Docker account +This guide shows you how to find and run a pre-built image. It then walks you +through creating a custom image and sharing it through Docker Hub. -Start by creating a [Docker ID](https://hub.docker.com/signup). +## Prerequisites -A [Docker ID](/accounts/create-account/) grants you access to Docker Hub repositories and lets you explore available images from the community and verified publishers. You also need a Docker ID to share images on Docker Hub. +- [Download and install Docker](../../get-started/get-docker.md) +- [Create a Docker account](https://app.docker.com/signup) -> [!TIP] -> -> Explore [Docker's core subscriptions](https://www.docker.com/pricing/) to see what else Docker can offer you. +## Step 1: Find an image in Docker Hub's library -### Step 2: Create your first repository +You can search for content in Docker Hub itself, in the Docker Desktop +Dashboard, or by using the CLI. -To create a repository: +To search or browse for content on Docker Hub: -1. Sign in to [Docker Hub](https://hub.docker.com). -2. On the Repositories page, select **Create repository**. -3. Name it **<your-username>/my-private-repo**. -4. Set the visibility to **Private**. -5. Select **Create**. +{{< tabs >}} +{{< tab name="Docker Hub" >}} -You've created your first repository. +1. Navigate to the [Docker Hub Explore page](https://hub.docker.com/explore). -### Step 3: Download and install Docker Desktop + On the **Explore** page, you can browse by catalog or category, or use the search + to quickly find content. -You need to download Docker Desktop to build, push, and pull container images. +2. Under **Categories**, select **Web servers**. -1. Download and install [Docker Desktop](/manuals/desktop/_index.md). + After the results are displayed, you can further filter the results using the + filters on the left side of the page. -2. Sign in to Docker Desktop using the Docker ID you created in step one. +3. In the filters, select **Docker Official Image**. -### Step 4: Pull and run a container image from Docker Hub + Filtering by Trusted Content ensures that you see only high-quality, secure + images curated by Docker and verified publishing partners. -1. In your terminal, run `docker pull hello-world` to pull the image from Docker Hub. You should see output similar to: +4. In the results, select the **nginx** image. + + Selecting the image opens the image's page where you can learn more about how + to use the image. On the page, you'll also find the `docker pull` command to + pull the image. + +{{< /tab >}} +{{< tab name="Docker Desktop" >}} + +1. Open the Docker Desktop Dashboard. +2. Select the **Docker Hub** view. + + In the **Docker Hub** view, you can browse by catalog or category, or use the search + to quickly find content. + +3. Leave the search box empty and then select **Search**. + + The search results are shown with additional filters now next to the search box. + +4. Select the search filter icon, and then select **Docker Official Image** and **Web Servers**. +5. In the results, select the **nginx** image. + +{{< /tab >}} +{{< tab name="CLI" >}} + +1. Open a terminal window. + + > [!TIP] + > + > The Docker Desktop Dashboard contains a built-in terminal. At the bottom of + > the Dashboard, select **>_ Terminal** to open it. + +2. In the terminal, run the following command. ```console - $ docker pull hello-world - Using default tag: latest - latest: Pulling from library/hello-world - 2db29710123e: Pull complete - Digest: sha256:7d246653d0511db2a6b2e0436cfd0e52ac8c066000264b3ce63331ac66dca625 - Status: Downloaded newer image for hello-world:latest - docker.io/library/hello-world:latest + $ docker search --filter is-official=true nginx ``` -2. Run `docker run hello-world` to run the image locally. You should see output similar to: + Unlike the Docker Hub and Docker Desktop interfaces, you can't browse by + category using the `docker search` command. For more details about the + command, see [docker search](/reference/cli/docker/search/). + +{{< /tab >}} +{{< /tabs >}} + +Now that you've found an image, it's time to pull and run it on your device. + +## Step 2: Pull and run an image from Docker Hub + +You can run images from Docker Hub using the CLI or Docker Desktop Dashboard. - ```console - $ docker run hello-world - Hello from Docker! - This message shows that your installation appears to be working correctly. +{{< tabs >}} +{{< tab name="Docker Desktop" >}} - To generate this message, Docker took the following steps: - 1. The Docker client contacted the Docker daemon. - 2. The Docker daemon pulled the "hello-world" image from the Docker Hub. - (amd64) - 3. The Docker daemon created a new container from that image which runs the - executable that produces the output you are currently reading. - 4. The Docker daemon streamed that output to the Docker client, which sent - it to your terminal. +1. In the Docker Desktop Dashboard, select the **nginx** image in the **Docker + Hub** view. For more details, see [Step 1: Find an image in Docker Hub's + library](#step-1-find-an-image-in-docker-hubs-library). + +2. On the **nginx** screen, select **Run**. + + If the image doesn't exist on your device, it is automatically pulled from + Docker Hub. Pulling the image may take a few seconds or minutes depending on + your connection. After the image has been pulled, a window appears in Docker + Desktop and you can specify run options. + +3. In the **Host port** option, specify `8080`. +4. Select **Run**. + + The container logs appear after the container starts. + +5. Select the **8080:80** link to open the server, or visit + [https://localhost:8080](https://localhost:8080) in your web browser. + +6. In the Docker Desktop Dashboard, select the **Stop** button to stop the + container. + + +{{< /tab >}} +{{< tab name="CLI" >}} + +1. Open a terminal window. + + > [!TIP] + > + > The Docker Desktop Dashboard contains a built-in terminal. At the bottom of + > the Dashboard, select **>_ Terminal** to open it. + +2. In your terminal, run the following command to pull and run the Nginx image. + + ```console + $ docker run -p 8080:80 --rm nginx + ``` + + The `docker run` command automatically pulls and runs the image without the + need to run `docker pull` first. To learn more about the command and its + options, see the [`docker run` CLI + reference](../../reference/cli/docker/container/run.md). After running the + command, you should see output similar to the following. + + ```console {collapse=true} + Unable to find image 'nginx:latest' locally + latest: Pulling from library/nginx + a480a496ba95: Pull complete + f3ace1b8ce45: Pull complete + 11d6fdd0e8a7: Pull complete + f1091da6fd5c: Pull complete + 40eea07b53d8: Pull complete + 6476794e50f4: Pull complete + 70850b3ec6b2: Pull complete + Digest: sha256:28402db69fec7c17e179ea87882667f1e054391138f77ffaf0c3eb388efc3ffb + Status: Downloaded newer image for nginx:latest + /docker-entrypoint.sh: /docker-entrypoint.d/ is not empty, will attempt to perform configuration + /docker-entrypoint.sh: Looking for shell scripts in /docker-entrypoint.d/ + /docker-entrypoint.sh: Launching /docker-entrypoint.d/10-listen-on-ipv6-by-default.sh + 10-listen-on-ipv6-by-default.sh: info: Getting the checksum of /etc/nginx/conf.d/default.conf + 10-listen-on-ipv6-by-default.sh: info: Enabled listen on IPv6 in /etc/nginx/conf.d/default.conf + /docker-entrypoint.sh: Sourcing /docker-entrypoint.d/15-local-resolvers.envsh + /docker-entrypoint.sh: Launching /docker-entrypoint.d/20-envsubst-on-templates.sh + /docker-entrypoint.sh: Launching /docker-entrypoint.d/30-tune-worker-processes.sh + /docker-entrypoint.sh: Configuration complete; ready for start up + 2024/11/07 21:43:41 [notice] 1#1: using the "epoll" event method + 2024/11/07 21:43:41 [notice] 1#1: nginx/1.27.2 + 2024/11/07 21:43:41 [notice] 1#1: built by gcc 12.2.0 (Debian 12.2.0-14) + 2024/11/07 21:43:41 [notice] 1#1: OS: Linux 6.10.11-linuxkit + 2024/11/07 21:43:41 [notice] 1#1: getrlimit(RLIMIT_NOFILE): 1048576:1048576 + 2024/11/07 21:43:41 [notice] 1#1: start worker processes + 2024/11/07 21:43:41 [notice] 1#1: start worker process 29 + ... + ``` - To try something more ambitious, you can run an Ubuntu container with: - $ docker run -it ubuntu bash +3. Visit [https://localhost:8080](https://localhost:8080) to view the default + Nginx page and verify that the container is running. - Share images, automate workflows, and more with a free Docker ID: - https://hub.docker.com/ +4. In the terminal, press Ctrl+C to stop the container. - For more examples and ideas, visit: - https://docs.docker.com/get-started/ - ``` +{{< /tab >}} +{{< /tabs >}} -### Step 5: Build and push a container image to Docker Hub from your computer +You've now run a web server without any set up or configuration. Docker Hub +provides instant access to pre-built, ready-to-use container images, letting you +quickly pull and run applications without needing to install or configure +software manually. With Docker Hub's vast library of images, you can experiment +with and deploy applications effortlessly, boosting productivity and making it +easy to try out new tools, set up development environments, or build on top of +existing software. -1. Start by creating a [Dockerfile](/reference/dockerfile.md) to specify your application as shown below: +You can also extend images from Docker Hub, letting you quickly build and +customize your own images to suit specific needs. + + +## Step 3: Build and push an image to Docker Hub + +1. Create a [Dockerfile](/reference/dockerfile.md) to specify your application: ```dockerfile - # syntax=docker/dockerfile:1 - FROM busybox - CMD echo "Hello world! This is my first Docker image." + FROM nginx + RUN echo "

Hello world from Docker!

" > /usr/share/nginx/html/index.html + ``` + + This Dockerfile extends the Nginx image from Docker Hub to create a + simple website. With just a few lines, you can easily set up, customize, and + share a static website using Docker. + +2. Run the following command to build your image. Replace `` with your Docker ID. + + ```console + $ docker build -t /nginx-custom . ``` -2. Run `docker build -t /my-private-repo .` to build your Docker - image. + This command builds your image and tags it so that Docker understands which + repository to push it to in Docker Hub. To learn more about the command and + its options, see the [`docker build` CLI + reference](../../reference/cli/docker/buildx/build.md). After running the + command, you should see output similar to the following. + + ```console {collapse=true} + [+] Building 0.6s (6/6) FINISHED docker:desktop-linux + => [internal] load build definition from Dockerfile 0.0s + => => transferring dockerfile: 128B 0.0s + => [internal] load metadata for docker.io/library/nginx:latest 0.0s + => [internal] load .dockerignore 0.0s + => => transferring context: 2B 0.0s + => [1/2] FROM docker.io/library/nginx:latest 0.1s + => [2/2] RUN echo "

Hello world from Docker!

" > /usr/share/ 0.2s + => exporting to image 0.1s + => => exporting layers 0.0s + => => writing image sha256:f85ab68f4987847713e87a95c39009a5c9f4ad78 0.0s + => => naming to docker.io/mobyismyname/nginx-custom 0.0s + ``` + +3. Run the following command to test your image. Replace `` with + your Docker ID. + + ```console + $ docker run -p 8080:80 --rm /nginx-custom + ``` + +4. Visit [https://localhost:8080](https://localhost:8080) to view the page. You + should see `Hello world from Docker!`. -3. Run `docker run /my-private-repo` to test your -Docker image locally. +5. In the terminal, press CTRL+C to stop the container. -4. Run `docker push /my-private-repo` to push your Docker image to Docker Hub. You should see output similar to: +6. Sign in to Docker Desktop. You must be signed in before pushing an image to + Docker Hub. + +7. Run the following command to push your image to Docker Hub. Replace `` with your Docker ID. ```console - $ cat > Dockerfile < [internal] load build definition from Dockerfile - => => transferring dockerfile: 110B - => [internal] load .dockerignore - => => transferring context: 2B - => [internal] load metadata for docker.io/library/busybox:latest - => CACHED [1/1] FROM docker.io/library/busybox@sha256:a9286defaba7n3a519 - => exporting to image - => => exporting layers - => => writing image sha256:dcdb1fd928bf257bfc0122ea47accd911a3a386ce618 - => => naming to docker.io/mobythewhale/my-private-repo - $ docker run mobythewhale/my-private-repo - Hello world! This is my first Docker image. - $ docker push mobythewhale/my-private-repo - The push refers to repository [docker.io/mobythewhale/my-private-repo] - d2421964bad1: Layer already exists - latest: digest: sha256:7604fbf8eeb03d866fd005fa95cdbb802274bf9fa51f7dafba6658294 - efa9baa size: 526 + $ docker push /nginx-custom ``` - >**Note** + > [!NOTE] > > You must be signed in to Docker Hub through Docker Desktop or the command line, and you must also name your images correctly, as per the above steps. -5. Your repository in Docker Hub should now display a new `latest` tag under **Tags**: + The command pushes the image to Docker Hub and automatically + creates the repository if it doesn't exist. To learn more about the command, + see the [`docker push` CLI + reference](../../reference/cli/docker/image/push.md). After running the + command, you should see output similar to the following. + + ```console {collapse=true} + Using default tag: latest + The push refers to repository [docker.io/mobyismyname/nginx-custom] + d0e011850342: Pushed + e4e9e9ad93c2: Mounted from library/nginx + 6ac729401225: Mounted from library/nginx + 8ce189049cb5: Mounted from library/nginx + 296af1bd2844: Mounted from library/nginx + 63d7ce983cd5: Mounted from library/nginx + b33db0c3c3a8: Mounted from library/nginx + 98b5f35ea9d3: Mounted from library/nginx + latest: digest: sha256:7f5223ae866e725a7f86b856c30edd3b86f60d76694df81d90b08918d8de1e3f size: 1985 + ``` + + Now that you've created a repository and pushed your image, it's time to view + your repository and explore its options. + +## Step 4: View your repository on Docker Hub and explore options + +You can view your Docker Hub repositories in the Docker Hub or Docker Desktop interface. + +{{< tabs >}} +{{< tab name="Docker Hub" >}} + +1. Go to [Docker Hub](https://hub.docker.com) and sign in. + + After signing in, you should be on the **Repositories** page. If not, then go + to the [**Repositories**](https://hub.docker.com/repositories/) page. + +2. Find the **nginx-custom** repository and select that row. + + After selecting the repository, you should see more details and options for + your repository. + +{{< /tab >}} +{{< tab name="Docker Desktop" >}} + +1. Sign in to Docker Desktop. +2. Select the **Images** view. +3. Select the **Hub repositories** tab. + + A list of your Docker Hub repositories appears. + +4. Find the **nginx-custom** repository, hover over the row, and then select **View in Hub**. + + Docker Hub opens and you are able to view more details about the image. - ![Tag created](images/index-tag.webp) +{{< /tab >}} +{{< /tabs >}} -You've successfully: +You've now verified that your repository exists on Docker Hub, and you've +discovered more options for it. View the next steps to learn more about some of +these options. -- Signed up for a Docker account -- Created your first repository -- Pulled an existing container image from Docker Hub -- Built your own container image on your computer -- Pushed it successfully to Docker Hub +## Next steps -### Next steps +Add [repository information](./repos/manage/information.md) to help users find and use +your image. -- Create an [organization](orgs.md) to use Docker Hub with your team. -- Automatically build container images from code through [builds](builds/_index.md). -- [Explore](https://hub.docker.com/explore) official & publisher images. -- [Upgrade your subscription](https://www.docker.com/pricing) to push additional private Docker images to -Docker Hub. diff --git a/content/manuals/docker-hub/release-notes.md b/content/manuals/docker-hub/release-notes.md index 39d11fef69c..29361bcf66b 100644 --- a/content/manuals/docker-hub/release-notes.md +++ b/content/manuals/docker-hub/release-notes.md @@ -15,11 +15,23 @@ known issues for each Docker Hub release. Take a look at the [Docker Public Roadmap](https://github.com/orgs/docker/projects/51/views/1?filterQuery=) to see what's coming next. +## 2024-11-11 + +### New + +- [Personal access tokens](/security/for-developers/access-tokens/) (PATs) now support expiration dates. + +## 2024-10-15 + +### New + +- Beta: You can now create [organization access tokens](/security/for-admins/access-tokens/) (OATs) to enhance security for organizations and streamline access management for organizations. + ## 2024-03-23 ### New - - You can tag Docker Hub repositories with [categories](./repos/categories.md). + - You can tag Docker Hub repositories with [categories](./repos/manage/information.md#repository-categories). ## 2023-12-11 @@ -68,7 +80,7 @@ Take a look at the [Docker Public Roadmap](https://github.com/orgs/docker/projec ### New -- The new [autobuild feature](../docker-hub/builds/manage-builds.md#check-your-active-builds) lets you view your in-progress logs every 30 seconds instead of when the build is complete. +- The new [autobuild feature](../docker-hub/repos/manage/builds/manage-builds.md#check-your-active-builds) lets you view your in-progress logs every 30 seconds instead of when the build is complete. ## 2022-09-21 @@ -116,7 +128,7 @@ Take a look at the [Docker Public Roadmap](https://github.com/orgs/docker/projec ### New -- You can now purchase or upgrade to a Docker Business subscription using a credit card. To learn more, see [Upgrade your subscription](../subscription/core-subscription/upgrade.md). +- You can now purchase or upgrade to a Docker Business subscription using a credit card. To learn more, see [Upgrade your subscription](../subscription//change.md). ## 2021-08-31 @@ -179,7 +191,7 @@ For more information about this feature and for instructions on how to use it, s ### New feature -The **Repositories** view now shows which images have gone stale because they haven't been pulled or pushed recently. For more information, see [repository tags](repos/access/_index.md#view-repository-tags). +The **Repositories** view now shows which images have gone stale because they haven't been pulled or pushed recently. For more information, see [repository tags](repos/manage/access/_index.md#view-repository-tags). ## 2020-10-07 @@ -265,7 +277,7 @@ Each organization page now breaks down into these tabs: ### Enhancements -* The [billing page](../subscription/core-subscription/upgrade.md) for personal accounts has been updated. You can access the page at its new URL: [https://hub.docker.com/billing/plan](https://hub.docker.com/billing/plan). +* The [billing page](../subscription/change.md) for personal accounts has been updated. You can access the page at its new URL: [https://hub.docker.com/billing/plan](https://hub.docker.com/billing/plan). ### Known Issues diff --git a/content/manuals/docker-hub/repos/_index.md b/content/manuals/docker-hub/repos/_index.md index 868bbfb8974..7554387ac2f 100644 --- a/content/manuals/docker-hub/repos/_index.md +++ b/content/manuals/docker-hub/repos/_index.md @@ -1,88 +1,59 @@ --- description: Learn how to manage repositories on Docker Hub -keywords: Docker, docker, trusted, registry, accounts, plans, Dockerfile, Docker Hub, - webhooks, docs, documentation, manage, repos -title: Manage repositories +keywords: Docker Hub, Hub, repositories +title: Repositories weight: 20 aliases: - /engine/tutorials/dockerrepos/ +- /docker-hub/repos/configure/ --- -## Manage default repository settings - -You can manage the default repository settings for your personal account in Docker Hub. Select the **Settings** icon, then select **Repository Settings**. - -![Repository settings menu](../images/docker-hub-repo-settings-menu.png) - -Here you can manage the following: - -- Default privacy: set the default repository privacy to either **Public** or **Private**. -- Linked accounts: for users with a Docker Pro, Team, or Business subscription, manage your source provider accounts to enable Automated Builds. -- Notifications: for users with a Docker Pro, Team, or Business subscription, manage how you receive notifications from autobuilds. - -## Change a repository from public to private - -1. Navigate to your repository. -2. Select the **Settings** tab. -3. Select **Make private**. -4. Enter the name of your repository to confirm. - -You get one free private repository with your Docker Hub user account (not -available for organizations you're a member of). If you need more private -repositories for your user account, upgrade your Docker Hub subscription from your [Billing Information](https://hub.docker.com/billing/plan) page. - -## Move images between repositories - -### Personal to personal - -When consolidating personal repositories, you can pull private images from the initial repository and push them into another repository owned by you. To avoid losing your private images, perform the following steps: - -1. Navigate to [Docker Hub](https://hub.docker.com) create a new Docker ID and select a personal subscription. -2. Using `docker login` from the CLI, sign in using your original Docker ID and pull your private images. -3. Tag your private images with your newly created Docker ID, for example: - - ```console - $ docker tag namespace1/docker101tutorial new_namespace/docker101tutorial - ``` -4. Using `docker login` from the CLI, sign in with your newly created Docker ID, and push your newly tagged private images to your new Docker ID namespace: - - ```console - $ docker push new_namespace/docker101tutorial - ``` - -The private images that existed in your previous account are now available in your new account. - -### Personal to an organization - -To avoid losing your private images, you can pull your private images from your personal account and push them to an organization that's owned by you. - -1. Navigate to [Docker Hub](https://hub.docker.com) and select **Organizations**. -2. Select the applicable organization and verify that your user account is a member of the organization. -3. Sign in to [Docker Hub](https://hub.docker.com) using your original Docker ID, and pull your images: - - ```console - $ docker pull namespace1/docker101tutorial - ``` -4. Tag your images with your new organization namespace: - - ```console - $ docker tag namespace1/docker101tutorial /docker101tutorial - ``` -5. Push your newly tagged images to your new org namespace: - - ```console - $ docker push new_org/docker101tutorial - ``` - -The private images that existed in your user account are now available for your organization. - -## Delete a repository - -> [!WARNING] -> -> Deleting a repository deletes all the images it contains and its build settings. This action can't be undone. - -1. Navigate to your repository. -2. Select the **Settings** tab. -3. Select **Delete repository**. -4. Enter the name of your repository to confirm. +A Docker Hub repository is a collection of container images, enabling you to +store, manage, and share Docker images publicly or privately. Each repository +serves as a dedicated space where you can store images associated with a +particular application, microservice, or project. Content in repositories is +organized by tags, which represent different versions of the same application, +allowing users to pull the right version when needed. + +In this section, learn how to: + +- [Create](./create.md) a repository. +- Manage a repository, including how to manage: + + - [Repository information](./manage/information.md): Add descriptions, + overviews, and categories to help users understand the purpose and usage of + your repository. Clear repository information aids discoverability and + usability. + + - [Access](./manage/access.md): Control who can access your repositories with + flexible options. Make repositories public or private, add collaborators, + and, for organizations, manage roles and teams to maintain security and + control. + + - [Images](./manage/hub-images/_index.md): Repositories support diverse + content types, including OCI artifacts, and allow version control through + tagging. Push new images and manage existing content across repositories + for flexibility. + + - [Image security insights](./manage/vulnerability-scanning.md): Utilize + continuous Docker Scout analysis and static vulnerability scanning to + detect, understand, and address security issues within container images. + + - [Webhooks](./manage/webhooks.md): Automate responses to repository events + like image pushes or updates by setting up webhooks, which can trigger + notifications or actions in external systems, streamlining workflows. + + - [Automated builds](./manage/builds/_index.md): Integrate with GitHub or + Bitbucket for automated builds. Every code change triggers an image + rebuild, supporting continuous integration and delivery. + + - [Trusted content](./manage/trusted-content/_index.md): Contribute to Docker + Official Images or manage repositories in the Verified Publisher and + Sponsored Open Source programs, including tasks like setting logos, + accessing analytics, and enabling vulnerability scanning. + +- [Archive](./archive.md) an outdated or unsupported repository. +- [Delete](./delete.md) a repository. +- [Manage personal settings](./settings.md): For your account, you can set personal + settings for repositories, including default repository privacy and autobuild + notifications. diff --git a/content/manuals/docker-hub/repos/access.md b/content/manuals/docker-hub/repos/access.md deleted file mode 100644 index 3cf92798e75..00000000000 --- a/content/manuals/docker-hub/repos/access.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -description: Discover how to access repositories on Docker Hub -keywords: Docker, docker, trusted, registry, accounts, plans, Dockerfile, Docker Hub, - webhooks, docs, documentation, collaborators, viewing, searching, starring -title: Access repositories ---- - -Within your repository, you can give others access to push and pull to your repository, and you can assign permissions. You can also view your repository tags and the associated images. - -## Collaborators and their role - -A collaborator is someone you want to give access to a private repository. Once designated, they can `push` and `pull` to your repositories. They're not -allowed to perform any administrative tasks such as deleting the repository or changing its status from private to public. - -Only personal account repositories can use collaborators. You can add unlimited collaborators to public repositories, and [Docker Pro](../../subscription/core-subscription/details.md#docker-pro) accounts can add up to 1 collaborator on private repositories. Organization repositories can't use collaborators. Organization owners can control repository access with [member roles](../../security/for-admins/roles-and-permissions.md) and [teams](../../admin/organization/manage-a-team.md). - -You can choose collaborators and manage their access to a private -repository from that repository's **Settings** page. - -> [!NOTE] -> -> A collaborator can't add other collaborators. Only the owner of -> the repository has administrative access. - -You can also assign more granular collaborator rights ("Read", "Write", or -"Admin") on Docker Hub by using organizations and teams. For more information -see the [organizations documentation](../../admin/organization/orgs.md#create-an-organization). - -## View repository tags - -You can view the available tags and the size of the associated image. Go to the **Repositories** view and select a repository to see its tags. To view individual tags, select the **Tags** tab. - -To delete a tag, select the corresponding checkbox and select **Delete** from the **Action** drop-down list. - -> [!NOTE] -> -> Only a user with administrative access (owner or team member with Admin -> permission) over the repository can delete tags. - -You can select a tag's digest to access more details. - -Image sizes are the cumulative space taken up by the image and all its parent -images. This is also the disk space used by the contents of the `.tar` file -created when you `docker save` an image. - -An image is stale if there has been no push or pull activity for more than one month. A multi-architecture image is stale if all single-architecture images part of its manifest are stale. - -## Search for repositories - -You can search the [Docker Hub](https://hub.docker.com) registry through its -search interface or by using the command line interface. You can search by image name, username, or description: - -```console -$ docker search centos - -NAME DESCRIPTION STARS OFFICIAL AUTOMATED -centos The official build of CentOS. 1034 [OK] -ansible/centos7-ansible Ansible on Centos7 43 [OK] -tutum/centos Centos image with SSH access. For the root... 13 [OK] -... -``` - -In the previous example, you can see two example results, `centos` and `ansible/centos7-ansible`. - -The second result shows that it comes from the public repository of a user, -named `ansible/`, while the first result, `centos`, doesn't explicitly list a -repository which means that it comes from the top-level namespace for -[Docker Official Images](../../trusted-content/official-images/_index.md). -The `/` character separates a user's repository from the image name. - -Once you've found the image you want, you can download it with `docker pull `: - -```console -$ docker pull centos - -latest: Pulling from centos -6941bfcbbfca: Pull complete -41459f052977: Pull complete -fd44297e2ddb: Already exists -centos:latest: The image you are pulling has been verified. Important: image verification is a tech preview feature and should not be relied on to provide security. -Digest: sha256:d601d3b928eb2954653c59e65862aabb31edefa868bd5148a41fa45004c12288 -Status: Downloaded newer image for centos:latest -``` - -You now have an image from which you can run containers. - -## Star repositories - -Stars are a way to show that you like a repository. They're also an easy way of bookmarking your favorites. diff --git a/content/manuals/docker-hub/repos/archive.md b/content/manuals/docker-hub/repos/archive.md new file mode 100644 index 00000000000..18c89bfccc2 --- /dev/null +++ b/content/manuals/docker-hub/repos/archive.md @@ -0,0 +1,63 @@ +--- +description: Learn how to archive or unarchive a repository on Docker Hub +keywords: Docker Hub, Hub, repositories, archive, unarchive +title: Archive or unarchive a repository +linkTitle: Archive +toc_max: 3 +weight: 35 +--- + +You can archive a repository on Docker Hub to mark it as read-only and indicate +that it's no longer actively maintained. This helps prevent the use of outdated +or unsupported images in workflows. Archived repositories can also be unarchived +if needed. + +Docker Hub highlights repositories that haven't been updated in over a year by +displaying an icon ({{< inline-image src="./images/outdated-icon.webp" +alt="outdated icon" >}}) next to them on the [**Repositories** +page](https://hub.docker.com/repositories/). Consider reviewing these +highlighted repositories and archiving them if necessary. + +When a repository is archived, the following occurs: + +- The repository information can't be modified. +- New images can't be pushed to the repository. +- An **Archived** label is displayed on the public repository page. +- Users can still pull the images. + +You can unarchive an archived repository to remove the archived state. When +unarchived, the following occurs: + +- The repository information can be modified. +- New images can be pushed to the repository. +- The **Archived** label is removed on the public repository page. + +## Archive a repository + +1. Sign in to [Docker Hub](https://hub.docker.com). +2. Select **Repositories**. + + A list of your repositories appears. + +3. Select a repository. + + The **General** page for the repository appears. + +4. Select the **Settings** tab. +5. Select **Archive repository**. +6. Enter the name of your repository to confirm. +7. Select **Archive**. + +## Unarchive a repository + +1. Sign in to [Docker Hub](https://hub.docker.com). +2. Select **Repositories**. + + A list of your repositories appears. + +3. Select a repository. + + The **General** page for the repository appears. + +4. Select the **Settings** tab. +5. Select **Unarchive repository**. \ No newline at end of file diff --git a/content/manuals/docker-hub/repos/categories.md b/content/manuals/docker-hub/repos/categories.md deleted file mode 100644 index d72d7380975..00000000000 --- a/content/manuals/docker-hub/repos/categories.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: Categories in Docker Hub -description: | - Categorizing your Docker Hub repositories makes it easier for users to - find your images based on its use cases and content. -keywords: hub, images, content, categories, explore, search ---- - -You can tag Docker Hub repositories with categories, representing the primary -intended use cases for your images. This lets users more easily find and -explore content for the problem domain that they're interested in. - -## Available categories - -The Docker Hub content team maintains a curated list of categories. -The available categories are: - -- **API Management**: Tools for creating, publishing, analyzing, and securing APIs. -- **Content Management System:** Software applications to create and manage digital content through templates, procedures, and standard formats. -- **Data Science:** Tools and software to support analyzing data and generating actionable insights. -- **Databases & Storage:** Systems for storing, retrieving, and managing data. -- **Languages & Frameworks:** Programming language runtimes and frameworks. -- **Integrations & Delivery:** Tools for Continuous Integration (CI) and Continuous Delivery (CD). -- **Internet of Things:** Tools supporting Internet of Things (IoT) applications. -- **Machine Learning & AI:** Tools and frameworks optimized for artificial intelligence and machine learning projects, such as pre-installed libraries and frameworks for data analysis, model training, and deployment. -- **Message Queues:** Message queuing systems optimized for reliable, scalable, and efficient message handling. -- **Monitoring & Observability:** Tools to track software and system performance through metrics, logs, and traces, as well as observability to explore the system’s state and diagnose issues. -- **Networking:** Repositories that support data exchange and connecting computers and other devices to share resources. -- **Operating Systems:** Software that manages all other programs on a computer and serves as an intermediary between users and the computer hardware, while overseeing applications and system resources. -- **Security:** Tools to protect a computer system or network from theft, unauthorized access, or damage to their hardware, software, or electronic data, as well as from service disruption. -- **Web Servers:** Software to serve web pages, HTML files, and other assets to users or other systems. -- **Web Analytics:** Tools to collect, measure, analyze, and report on web data and website visitor engagement. - -## Auto-generated categories - -> [!NOTE] -> -> Auto-generated categories only apply to Docker Verified Publishers and -> Docker-Sponsored Open Source program participants. - -For repositories that pre-date the Categories feature in Docker Hub, -categories have been automatically generated and applied, using OpenAI, based -on the repository title and description. - -As an owner of a repository that has been auto-categorized, you can manually -edit the categories if you think they're inaccurate. See [Manage categories for -a repository](#manage-categories-for-a-repository). - -The auto-generated categorization was a one-time effort to help seed categories -onto repositories created before the feature existed. Categories are not -assigned to new repositories automatically. - -## Manage categories for a repository - -You can tag a repository with up to three categories. - -To edit the categories of a repository: - -1. Go to the repository page on Docker Hub. -2. Select the pencil icon under the description field. -3. Select the categories you want to apply. -4. Select **Update** to save the changes. - - - -If you're missing a category, use the -[Give feedback link](https://docker.qualtrics.com/jfe/form/SV_03CrMyAkCWVylKu) -to let us know what categories you'd like to see. diff --git a/content/manuals/docker-hub/repos/create.md b/content/manuals/docker-hub/repos/create.md index 37795c49351..3cc4d97c826 100644 --- a/content/manuals/docker-hub/repos/create.md +++ b/content/manuals/docker-hub/repos/create.md @@ -1,80 +1,58 @@ --- -description: Learn how to create repositories on Docker Hub -keywords: Docker, docker, trusted, registry, accounts, plans, Dockerfile, Docker Hub, - webhooks, docs, documentation, manage, repos -title: Create repositories +description: Learn how to create a repository on Docker Hub +keywords: Docker Hub, Hub, repositories, create +title: Create a repository +linkTitle: Create toc_max: 3 -aliases: -- /docker-hub/repos/configure/ +weight: 20 --- -Repositories let you share container images with your team, -customers, or the Docker community at large. - -A single Docker Hub repository can hold many Docker images which are stored as **tags**. You can push Docker images to Docker Hub with the [`docker push`](/reference/cli/docker/image/push/)command. - -## Create a repository - -1. Sign in to Docker Hub. +1. Sign in to [Docker Hub](https://hub.docker.com). 2. Select **Repositories**. -3. Near the top-right corner, select **Create Repository**. +3. Near the top-right corner, select **Create repository**. +4. Select a **Namespace**. -When creating a new repository: + You can choose to locate it under your own user account, or under any + organization where you are an owner or editor. -- You can choose to locate it under your own user account, or under any - [organization](../../admin/organization//orgs.md) where you are an [owner](../../admin/organization/manage-a-team.md#organization-owner) or [editor](../../security/for-admins/roles-and-permissions.md). -- The repository name needs to: +5. Specify the **Repository Name**. + + The repository name needs to: - Be unique - Have between 2 and 255 characters - - Only contain lowercase letters, numbers, hyphens (`-`), and underscores (`_`) - - > [!NOTE] - > - > You can't rename a Docker Hub repository once it's created. - -- The description can be up to 100 characters. It's used in the search results. -- If you're a Docker Verified Publisher (DVP) or Docker-Sponsored Open Source (DSOS) organization, you can also add a logo to a repository. The maximum size in pixels is 1000x1000. -- You can link a GitHub or Bitbucket account now, or choose to do it later in - the repository settings. -- You can set the repository's default visibility to public or private. - - > [!NOTE] - > - > For organizations creating a new repository, it's recommended you select **Private**. - -### Add a repository overview - -Once you have created a repository, add an overview to the **Repository overview** field. This describes what your image does and how to use it. - -Consider the following repository overview best practices. - -- Describe what the image is, the features it offers, and why it should be used. Can include examples of usage or the team behind the project. -- Explain how to get started with running a container using the image. You can include a minimal example of how to use the image in a Dockerfile. -- List the key image variants and tags to use them, as well as use cases for the variants. -- Link to documentation or support sites, communities, or mailing lists for additional resources. -- Provide contact information for the image maintainers. -- Include the license for the image and where to find more details if needed. + - Only contain lowercase letters, numbers, hyphens (`-`), and underscores + (`_`) -## Push a Docker container image to Docker Hub + > [!NOTE] + > + > You can't rename a Docker Hub repository once it's created. -Once you have created a repository, you can start using `docker push` to push -images. +6. Specify the **Short description**. -To push an image to Docker Hub, you must first name your local image using your -Docker ID and the repository name that you created. + The description can be up to 100 characters. It appears in search results. -If you want to add multiple images to a repository, add a specific `:` to them, for example `docs/base:testing`. If it's not specified, the tag defaults to `latest`. +7. Select the default visibility. -Name your local images using one of these methods: + - **Public**: The repository appears in Docker Hub search results and can be + pulled by everyone. + - **Private**: The repository doesn't appear in Docker Hub search results and + is only accessible to you and collaborators. In addition, if you selected + an organization's namespace, then the repository is accessible to those + with applicable roles or permissions. For more details, see [Roles and + permissions](../../security/for-admins/roles-and-permissions.md). -- When you build them, using `docker build -t /[:` -- By re-tagging the existing local image with `docker tag /[:]`. -- By using `docker commit /[:]` to commit changes. + > [!NOTE] + > + > For organizations creating a new repository, if you're unsure which + > visibility to choose, then Docker recommends that you select **Private**. -Then, you can push this image to the repository designated by its name or tag: +8. Select **Create**. -```console -$ docker push /: -``` +After the repository is created, the **General** page appears. You are now able to manage: -The image is then uploaded and available for use by your teammates and/or the community. +- [Repository information](./manage/information.md) +- [Access](./manage/access.md) +- [Images](./manage/hub-images/_index.md) +- [Automated builds](./manage/builds/_index.md) +- [Webhooks](./manage/webhooks.md) +- [Image security insights](./manage/vulnerability-scanning.md) diff --git a/content/manuals/docker-hub/repos/delete.md b/content/manuals/docker-hub/repos/delete.md new file mode 100644 index 00000000000..46e27c1ea2e --- /dev/null +++ b/content/manuals/docker-hub/repos/delete.md @@ -0,0 +1,27 @@ +--- +description: Learn how to delete a repository on Docker Hub +keywords: Docker Hub, Hub, repositories, delete +title: Delete a repository +linkTitle: Delete +toc_max: 3 +weight: 40 +--- + +> [!WARNING] +> +> Deleting a repository deletes all the images it contains and its build +> settings. This action can't be undone. + +1. Sign in to [Docker Hub](https://hub.docker.com). +2. Select **Repositories**. + + A list of your repositories appears. + +3. Select a repository. + + The **General** page for the repository appears. + +4. Select the **Settings** tab. +5. Select **Delete repository**. +6. Enter the name of your repository to confirm. +7. Select **Delete Repository Forever**. \ No newline at end of file diff --git a/content/manuals/docker-hub/repos/images/outdated-icon.webp b/content/manuals/docker-hub/repos/images/outdated-icon.webp new file mode 100644 index 00000000000..153d3dcea09 Binary files /dev/null and b/content/manuals/docker-hub/repos/images/outdated-icon.webp differ diff --git a/content/manuals/scout/concepts/_index.md b/content/manuals/docker-hub/repos/manage/_index.md similarity index 72% rename from content/manuals/scout/concepts/_index.md rename to content/manuals/docker-hub/repos/manage/_index.md index 60fd656fe66..4806e0afc2c 100644 --- a/content/manuals/scout/concepts/_index.md +++ b/content/manuals/docker-hub/repos/manage/_index.md @@ -1,6 +1,6 @@ --- build: render: never -title: Concepts +title: Manage weight: 30 --- diff --git a/content/manuals/docker-hub/repos/manage/access.md b/content/manuals/docker-hub/repos/manage/access.md new file mode 100644 index 00000000000..ed190257f32 --- /dev/null +++ b/content/manuals/docker-hub/repos/manage/access.md @@ -0,0 +1,134 @@ +--- +description: Discover how to manage access to repositories on Docker Hub. +keywords: Docker Hub, Hub, repository access, repository collaborators, repository privacy +title: Access management +LinkTItle: Access +weight: 50 +aliases: +- /docker-hub/repos/access/ +--- + +In this topic learn about the features available to manage access to your +repositories. This includes visibility, collaborators, roles, teams, and +organization access tokens. + +## Repository visibility + +The most basic repository access is controlled via the visibility. A +repository's visibility can be public or private. + +With public visibility, the repository appears in Docker Hub search results and +can be pulled by everyone. To manage push access to public personal +repositories, you can use collaborators. To manage push access to public +organization repositories, you can use roles, teams, or organization access +tokens. + +With private visibility, the repository doesn't appear in Docker Hub search +results and is only accessible to those with granted permission. To manage push +and pull access to private personal repositories, you can use collaborators. To +manage push and pull access to private organization repositories, you can use +roles, teams, or organization access tokens. + +### Change repository visibility + +When creating a repository in Docker Hub, you can set the repository visibility. +In addition, you can set the default repository visibility when a repository is +created in your personal repository settings. The following describes how to +change the visibility after the repository has been created. + +To change repository visibility: + +1. Sign in to [Docker Hub](https://hub.docker.com). +2. Select **Repositories**. +3. Select a repository. + + The **General** page for the repository appears. + +4. Select the **Settings** tab. +5. Under **Visibility settings**, select one of the following: + + - **Make public**: The repository appears in Docker Hub search results and can be + pulled by everyone. + - **Make private**: The repository doesn't appear in Docker Hub search results + and is only accessible to you and collaborators. In addition, if the + repository is in an organization's namespace, then the repository + is accessible to those with applicable roles or permissions. + +6. Type the repository's name to verify the change. +7. Select **Make public** or **Make private**. + +## Collaborators + +A collaborator is someone you want to give `push` and `pull` access to a +personal repository. Collaborators aren't able to perform any administrative +tasks such as deleting the repository or changing its visibility from private to +public. In addition, collaborators can't add other collaborators. + +Only personal repositories can use collaborators. You can add unlimited +collaborators to public repositories, and Docker Pro accounts can add up to 1 +collaborator on private repositories. + +Organization repositories can't use collaborators, but can use member roles, +teams, or organization access tokens to manage access. + +### Manage collaborators + +1. Sign in to [Docker Hub](https://hub.docker.com). + +2. Select **Repositories**. + + A list of your repositories appears. + +3. Select a repository. + + The **General** page for the repository appears. + +4. Select the **Collaborators** tab. + +5. Add or remove collaborators based on their Docker username. + +You can choose collaborators and manage their access to a private +repository from that repository's **Settings** page. + +## Organization roles + +Organizations can use roles for individuals, giving them different +permissions in the organization. For more details, see [Roles and +permissions](/manuals/security/for-admins/roles-and-permissions.md). + +## Organization teams + +Organizations can use teams. A team can be assigned fine-grained repository +access. + +### Configure team repository permissions + +You must create a team before you are able to configure repository permissions. +For more details, see [Create and manage a +team](/manuals/admin/organization/manage-a-team.md). + +To configure team repository permissions: + +1. Sign in to [Docker Hub](https://hub.docker.com). + +2. Select **Repositories**. + + A list of your repositories appears. + +3. Select a repository. + + The **General** page for the repository appears. + +4. Select the **Permissions** tab. + +5. Add, modify, or remove a team's repository permissions. + + - Add: Specify the **Team**, select the **Permission**, and then select **Add**. + - Modify: Specify the new permission next to the team. + - Remove: Select the **Remove permission** icon next to the team. + +## Organization access tokens (OATs) + +Organizations can use OATs. OATs let you assign fine-grained repository access +permissions to tokens. For more details, see [Organization access +tokens](/manuals/security/for-admins/access-tokens.md). diff --git a/content/manuals/docker-hub/builds/_index.md b/content/manuals/docker-hub/repos/manage/builds/_index.md similarity index 99% rename from content/manuals/docker-hub/builds/_index.md rename to content/manuals/docker-hub/repos/manage/builds/_index.md index 930e40c5435..d95313288cb 100644 --- a/content/manuals/docker-hub/builds/_index.md +++ b/content/manuals/docker-hub/repos/manage/builds/_index.md @@ -3,16 +3,17 @@ description: Set up Automated builds keywords: automated, build, images, Docker Hub title: Set up Automated Builds linkTitle: Automated builds -weight: 60 +weight: 90 aliases: - /docker-hub/builds/automated-build/ - /docker-hub/builds/classic/ +- /docker-hub/builds/ --- > [!NOTE] > > Automated builds require a -> [Docker Pro, Team, or Business subscription](../../subscription/_index.md). +> Docker Pro, Team, or Business subscription. This page contains information on: - [Configuring Automated builds](#configure-automated-builds) diff --git a/content/manuals/docker-hub/builds/advanced.md b/content/manuals/docker-hub/repos/manage/builds/advanced.md similarity index 98% rename from content/manuals/docker-hub/builds/advanced.md rename to content/manuals/docker-hub/repos/manage/builds/advanced.md index 111a065da33..1a4298ab0f0 100644 --- a/content/manuals/docker-hub/builds/advanced.md +++ b/content/manuals/docker-hub/repos/manage/builds/advanced.md @@ -2,12 +2,14 @@ description: Automated builds keywords: automated, build, images title: Advanced options for Autobuild and Autotest +aliases: +- /docker-hub/builds/advanced/ --- > [!NOTE] > > Automated builds require a -> [Docker Pro, Team, or Business subscription](../../subscription/_index.md). +> Docker Pro, Team, or Business subscription. The following options allow you to customize your automated build and automated test processes. diff --git a/content/manuals/docker-hub/builds/automated-testing.md b/content/manuals/docker-hub/repos/manage/builds/automated-testing.md similarity index 96% rename from content/manuals/docker-hub/builds/automated-testing.md rename to content/manuals/docker-hub/repos/manage/builds/automated-testing.md index c22293b0467..a2aed00f30b 100644 --- a/content/manuals/docker-hub/builds/automated-testing.md +++ b/content/manuals/docker-hub/repos/manage/builds/automated-testing.md @@ -2,15 +2,17 @@ description: Automated tests keywords: Automated, testing, repository title: Automated repository tests +aliases: +- /docker-hub/builds/automated-testing/ --- > [!NOTE] > > Automated builds require a -> [Docker Pro, Team, or Business subscription](../../subscription/_index.md). +> Docker Pro, Team, or Business subscription. Docker Hub can automatically test changes to your source code repositories -using containers. You can enable `Autotest` on [any Docker Hub repository](../repos/_index.md) +using containers. You can enable `Autotest` on any Docker Hub repository to run tests on each pull request to the source code repository to create a continuous integration testing service. diff --git a/content/manuals/docker-hub/builds/how-builds-work.md b/content/manuals/docker-hub/repos/manage/builds/how-builds-work.md similarity index 94% rename from content/manuals/docker-hub/builds/how-builds-work.md rename to content/manuals/docker-hub/repos/manage/builds/how-builds-work.md index 1ff6d690afd..fc67d3683dc 100644 --- a/content/manuals/docker-hub/builds/how-builds-work.md +++ b/content/manuals/docker-hub/repos/manage/builds/how-builds-work.md @@ -2,12 +2,14 @@ description: how automated builds work keywords: docker hub, automated builds title: How Automated builds work +aliases: +- /docker-hub/builds/how-builds-work/ --- > [!NOTE] > > Automated builds require a -> [Docker Pro, Team, or Business subscription](../../subscription/_index.md). +> Docker Pro, Team, or Business subscription. Docker Hub can automatically build images from source code in an external repository and automatically push the built image to your Docker repositories. diff --git a/content/manuals/docker-hub/builds/images/authorize-builder.png b/content/manuals/docker-hub/repos/manage/builds/images/authorize-builder.png similarity index 100% rename from content/manuals/docker-hub/builds/images/authorize-builder.png rename to content/manuals/docker-hub/repos/manage/builds/images/authorize-builder.png diff --git a/content/manuals/docker-hub/builds/images/bitbucket-revoke.png b/content/manuals/docker-hub/repos/manage/builds/images/bitbucket-revoke.png similarity index 100% rename from content/manuals/docker-hub/builds/images/bitbucket-revoke.png rename to content/manuals/docker-hub/repos/manage/builds/images/bitbucket-revoke.png diff --git a/content/manuals/docker-hub/builds/images/build-cancelicon.png b/content/manuals/docker-hub/repos/manage/builds/images/build-cancelicon.png similarity index 100% rename from content/manuals/docker-hub/builds/images/build-cancelicon.png rename to content/manuals/docker-hub/repos/manage/builds/images/build-cancelicon.png diff --git a/content/manuals/docker-hub/images/docker-hub-repo-settings-menu.png b/content/manuals/docker-hub/repos/manage/builds/images/docker-hub-repo-settings-menu.png similarity index 100% rename from content/manuals/docker-hub/images/docker-hub-repo-settings-menu.png rename to content/manuals/docker-hub/repos/manage/builds/images/docker-hub-repo-settings-menu.png diff --git a/content/manuals/docker-hub/builds/images/index-active.png b/content/manuals/docker-hub/repos/manage/builds/images/index-active.png similarity index 100% rename from content/manuals/docker-hub/builds/images/index-active.png rename to content/manuals/docker-hub/repos/manage/builds/images/index-active.png diff --git a/content/manuals/docker-hub/builds/images/index-dashboard.png b/content/manuals/docker-hub/repos/manage/builds/images/index-dashboard.png similarity index 100% rename from content/manuals/docker-hub/builds/images/index-dashboard.png rename to content/manuals/docker-hub/repos/manage/builds/images/index-dashboard.png diff --git a/content/manuals/docker-hub/images/index-report.png b/content/manuals/docker-hub/repos/manage/builds/images/index-report.png similarity index 100% rename from content/manuals/docker-hub/images/index-report.png rename to content/manuals/docker-hub/repos/manage/builds/images/index-report.png diff --git a/content/manuals/docker-hub/builds/images/retry-build.png b/content/manuals/docker-hub/repos/manage/builds/images/retry-build.png similarity index 100% rename from content/manuals/docker-hub/builds/images/retry-build.png rename to content/manuals/docker-hub/repos/manage/builds/images/retry-build.png diff --git a/content/manuals/docker-hub/builds/link-source.md b/content/manuals/docker-hub/repos/manage/builds/link-source.md similarity index 96% rename from content/manuals/docker-hub/builds/link-source.md rename to content/manuals/docker-hub/repos/manage/builds/link-source.md index b4a02b96aa1..3f8d48f3275 100644 --- a/content/manuals/docker-hub/builds/link-source.md +++ b/content/manuals/docker-hub/repos/manage/builds/link-source.md @@ -6,12 +6,13 @@ title: Configure automated builds from GitHub and BitBucket aliases: - /docker-hub/github/ - /docker-hub/bitbucket/ +- /docker-hub/builds/link-source/ --- > [!NOTE] > -> Automated builds require a -> [Docker Pro, Team, or Business subscription](../../subscription/_index.md). +> Automated builds require a Docker Pro, Team, or Business subscription. + To automate building and testing of your images, you link to your hosted source code service to Docker Hub so that it can access your source code @@ -26,7 +27,7 @@ If you are linking a source code provider to create autobuilds for a team, follo 2. Select the **Settings** icon in the top-right navigation, then select **Repository Settings**. - ![Repository settings menu](../images/docker-hub-repo-settings-menu.png) + ![Repository settings menu](./images/docker-hub-repo-settings-menu.png) 3. From the **Linked accounts** tab, select **Link provider** for the source provider you want to link. @@ -38,7 +39,7 @@ If you are linking a source code provider to create autobuilds for a team, follo ![Granting access to GitHub account](images/authorize-builder.png) - >**Note** + > [!NOTE] > > If you are the owner of any GitHub organizations, you might see options to grant Docker Hub access to them from this screen. You can also diff --git a/content/manuals/docker-hub/builds/manage-builds.md b/content/manuals/docker-hub/repos/manage/builds/manage-builds.md similarity index 87% rename from content/manuals/docker-hub/builds/manage-builds.md rename to content/manuals/docker-hub/repos/manage/builds/manage-builds.md index 3295ff541b2..c199e918a6f 100644 --- a/content/manuals/docker-hub/builds/manage-builds.md +++ b/content/manuals/docker-hub/repos/manage/builds/manage-builds.md @@ -2,12 +2,14 @@ title: Manage autobuilds description: How to manage autobuilds in Docker Hub keywords: autobuilds, automated, docker hub, registry +aliases: +- /docker-hub/builds/manage-builds/ --- > [!NOTE] > -> Automated builds require a -> [Docker Pro, Team, or Business subscription](../../subscription/_index.md). +> Automated builds require a Docker Pro, Team, or Business subscription. + ## Cancel or retry a build @@ -32,13 +34,11 @@ From either location, you can select a build job to view its build report. The build report shows information about the build job. This includes the source repository and branch, or tag, the build logs, the build duration, creation time and location, and the user account the build occurred in. ->**Note** +> [!NOTE] > -> You can now view the progress of your builds every 30 seconds when you -> refresh the **Builds** page. With the in-progress build logs, you can debug your -> builds before they're finished. +> You can now view the progress of your builds every 30 seconds when you refresh the **Builds** page. With the in-progress build logs, you can debug your builds before they're finished. -![Build report](/docker-hub/images/index-report.png) +![Build report](./images/index-report.png) ## Disable an automated build diff --git a/content/manuals/docker-hub/builds/troubleshoot.md b/content/manuals/docker-hub/repos/manage/builds/troubleshoot.md similarity index 97% rename from content/manuals/docker-hub/builds/troubleshoot.md rename to content/manuals/docker-hub/repos/manage/builds/troubleshoot.md index fc49a26fd1e..146e39e93c9 100644 --- a/content/manuals/docker-hub/builds/troubleshoot.md +++ b/content/manuals/docker-hub/repos/manage/builds/troubleshoot.md @@ -3,12 +3,14 @@ title: Troubleshoot your autobuilds description: How to troubleshoot Automated builds keywords: docker hub, troubleshoot, automated builds, autobuilds tags: [ Troubleshooting ] +aliases: +- /docker-hub/builds/troubleshoot/ --- > [!NOTE] > > Automated builds require a -> [Docker Pro, Team, or Business subscription](../../subscription/_index.md). +> Docker Pro, Team, or Business subscription. ## Failing builds diff --git a/content/manuals/docker-hub/repos/manage/hub-images/_index.md b/content/manuals/docker-hub/repos/manage/hub-images/_index.md new file mode 100644 index 00000000000..726eb788925 --- /dev/null +++ b/content/manuals/docker-hub/repos/manage/hub-images/_index.md @@ -0,0 +1,31 @@ +--- +description: Learn how to manage images in Docker Hub repositories +keywords: Docker Hub, Hub, images, content +title: Image management +linkTitle: Images +weight: 60 +--- + +Docker Hub provides powerful features for managing and organizing your +repository content, ensuring that your images and artifacts are accessible, +version-controlled, and easy to share. This section covers key image management +tasks, including tagging, pushing images, transferring images between +repositories, and supported software artifacts. + +- [Tags](./tags.md): Tags help you version and organize different iterations of + your images within a single repository. This topic explains tagging and + provides guidance on how to create, view, and delete tags in Docker Hub. +- [Software artifacts](./oci-artifacts.md): Docker Hub supports OCI (Open + Container Initiative) artifacts, allowing you to store, manage, and distribute + a range of content beyond standard Docker images, including Helm charts, + vulnerability reports, and more. This section provides an overview of OCI + artifacts as well as some examples of pushing them to Docker Hub. +- [Push images to Hub](./push.md): Docker Hub enables you to push local images + to it, making them available for your team or the Docker community. Learn how + to configure your images and use the `docker push` command to upload them to + Docker Hub. +- [Move images between repositories](./move.md): Organizing content across + different repositories can help streamline collaboration and resource + management. This topic details how to move images from one Docker Hub + repository to another, whether for personal consolidation or to share images + with an organization. \ No newline at end of file diff --git a/content/manuals/docker-hub/images/oci-artifact.png b/content/manuals/docker-hub/repos/manage/hub-images/images/oci-artifact.png similarity index 100% rename from content/manuals/docker-hub/images/oci-artifact.png rename to content/manuals/docker-hub/repos/manage/hub-images/images/oci-artifact.png diff --git a/content/manuals/docker-hub/images/oci-helm-tagview.png b/content/manuals/docker-hub/repos/manage/hub-images/images/oci-helm-tagview.png similarity index 100% rename from content/manuals/docker-hub/images/oci-helm-tagview.png rename to content/manuals/docker-hub/repos/manage/hub-images/images/oci-helm-tagview.png diff --git a/content/manuals/docker-hub/images/oci-helm.png b/content/manuals/docker-hub/repos/manage/hub-images/images/oci-helm.png similarity index 100% rename from content/manuals/docker-hub/images/oci-helm.png rename to content/manuals/docker-hub/repos/manage/hub-images/images/oci-helm.png diff --git a/content/manuals/docker-hub/images/oci-volume.png b/content/manuals/docker-hub/repos/manage/hub-images/images/oci-volume.png similarity index 100% rename from content/manuals/docker-hub/images/oci-volume.png rename to content/manuals/docker-hub/repos/manage/hub-images/images/oci-volume.png diff --git a/content/manuals/docker-hub/repos/manage/hub-images/move.md b/content/manuals/docker-hub/repos/manage/hub-images/move.md new file mode 100644 index 00000000000..fc267f3a8e6 --- /dev/null +++ b/content/manuals/docker-hub/repos/manage/hub-images/move.md @@ -0,0 +1,63 @@ +--- +description: Discover how to move images between repositories. +keywords: Docker Hub, Hub, repository content, move +title: Move images between repositories +linkTitle: Move images +weight: 40 +--- + +Consolidating and organizing your Docker images across repositories can +streamline your workflows, whether you're managing personal projects or +contributing to an organization. This topic explains how to move images between +Docker Hub repositories, ensuring that your content remains accessible and +organized under the correct accounts or namespaces. + +## Personal to personal + +When consolidating personal repositories, you can pull private images from the initial repository and push them into another repository owned by you. To avoid losing your private images, perform the following steps: + +1. [Sign up](https://app.docker.com/signup) for a new Docker account with a personal subscription. +2. Sign in to [Docker](https://app.docker.com/login) using your original Docker account +3. Pull your images: + + ```console + $ docker pull namespace1/docker101tutorial + ``` + +4. Tag your private images with your newly created Docker username, for example: + + ```console + $ docker tag namespace1/docker101tutorial new_namespace/docker101tutorial + ``` +5. Using `docker login` from the CLI, sign in with your newly created Docker account, and push your newly tagged private images to your new Docker account namespace: + + ```console + $ docker push new_namespace/docker101tutorial + ``` + +The private images that existed in your previous account are now available in your new account. + +## Personal to an organization + +To avoid losing your private images, you can pull your private images from your +personal account and push them to an organization that's owned by you. + +1. Navigate to [Docker Hub](https://hub.docker.com) and select **Organizations**. +2. Select the applicable organization and verify that your user account is a member of the organization. +3. Sign in to [Docker Hub](https://hub.docker.com) using your original Docker account, and pull your images: + + ```console + $ docker pull namespace1/docker101tutorial + ``` +4. Tag your images with your new organization namespace: + + ```console + $ docker tag namespace1/docker101tutorial /docker101tutorial + ``` +5. Push your newly tagged images to your new org namespace: + + ```console + $ docker push new_org/docker101tutorial + ``` + +The private images that existed in your user account are now available for your organization. \ No newline at end of file diff --git a/content/manuals/docker-hub/oci-artifacts.md b/content/manuals/docker-hub/repos/manage/hub-images/oci-artifacts.md similarity index 90% rename from content/manuals/docker-hub/oci-artifacts.md rename to content/manuals/docker-hub/repos/manage/hub-images/oci-artifacts.md index 8688ac16874..bb7b786cf20 100644 --- a/content/manuals/docker-hub/oci-artifacts.md +++ b/content/manuals/docker-hub/repos/manage/hub-images/oci-artifacts.md @@ -1,14 +1,18 @@ --- -title: OCI artifacts on Docker Hub -linkTitle: OCI artifacts -weight: 100 +title: Software artifacts on Docker Hub +linkTitle: Software artifacts +weight: 20 keywords: oci, artifacts, docker hub description: You can use Docker Hub to store software artifacts packaged as OCI artifacts. +aliases: +- /docker-hub/oci-artifacts/ --- You can use Docker Hub to store any kind of software artifact, not just -container images. Docker Hub supports OCI artifacts by leveraging the config -property on the image manifest. +container images. A software artifact is any item produced during the software +development process that contributes to the creation, maintenance, or +understanding of the software. Docker Hub supports OCI artifacts by leveraging +the config property on the image manifest. ## What are OCI artifacts? @@ -77,7 +81,7 @@ Steps: Successfully packaged chart and saved it to: /Users/hubuser/demo-0.1.0.tgz ``` -3. Sign in to Docker Hub with Helm, using your Docker ID credentials. +3. Sign in to Docker Hub with Helm, using your Docker credentials. ```console $ helm registry login registry-1.docker.io -u hubuser diff --git a/content/manuals/docker-hub/repos/manage/hub-images/push.md b/content/manuals/docker-hub/repos/manage/hub-images/push.md new file mode 100644 index 00000000000..a9a1f028452 --- /dev/null +++ b/content/manuals/docker-hub/repos/manage/hub-images/push.md @@ -0,0 +1,44 @@ +--- +description: Learn how to add content to a repository on Docker Hub. +keywords: Docker Hub, Hub, repository content, push +title: Push images to a repository +linkTitle: Push images +weight: 30 +--- + +To add content to a repository on Docker Hub, you need to tag your Docker image +and then push it to your repository. This process lets you share your +images with others or use them in different environments. + +1. Tag your Docker image. + + The `docker tag` command assigns a tag to your Docker image, which includes + your Docker Hub namespace and the repository name. The general syntax is: + + ```console + $ docker tag [SOURCE_IMAGE[:TAG]] [NAMESPACE/REPOSITORY[:TAG]] + ``` + + Example: + + If your local image is called `my-app` and you want to tag it for the + repository `my-namespace/my-repo` with the tag `v1.0`, run: + + ```console + $ docker tag my-app my-namespace/my-repo:v1.0 + ``` + +2. Push the image to Docker Hub. + + Use the `docker push` command to upload your tagged image to the specified + repository on Docker Hub. + + Example: + + ```console + $ docker push my-namespace/my-repo:v1.0 + ``` + + This command pushes the image tagged `v1.0` to the `my-namespace/my-repo` repository. + +3. Verify the image on Docker Hub. diff --git a/content/manuals/docker-hub/repos/manage/hub-images/tags.md b/content/manuals/docker-hub/repos/manage/hub-images/tags.md new file mode 100644 index 00000000000..35db6a1866a --- /dev/null +++ b/content/manuals/docker-hub/repos/manage/hub-images/tags.md @@ -0,0 +1,70 @@ +--- +description: Discover how to manage repository tags on Docker Hub. +keywords: Docker Hub, Hub, repository content, tags +title: Tags on Docker Hub +linkTitle: Tags +weight: 10 +--- + +Tags let you manage multiple versions of images within a single Docker Hub +repository. By adding a specific `:` to each image, such as +`docs/base:testing`, you can organize and differentiate image versions for +various use cases. If no tag is specified, the image defaults to the `latest` +tag. + +## Tag a local image + +To tag a local image, use one of the following methods: + +- When you build an image, use `docker build -t /[:`. +- Re-tag an existing local image with `docker tag /[:]`. +- When you commit changes, use `docker commit /[:]`. + +Then, you can push this image to the repository designated by its name or tag: + +```console +$ docker push /: +``` + +The image is then uploaded and available for use in Docker Hub. + +## View repository tags + +You can view the available tags and the size of the associated image. + +1. Sign in to [Docker Hub](https://hub.docker.com). +2. Select **Repositories**. + + A list of your repositories appears. + +3. Select a repository. + + The **General** page for the repository appears. + +4. Select the **Tags** tab. + +You can select a tag's digest to see more details. + +## Delete repository tags + +Only the repository owner or other team members with granted permissions can +delete tags. + +1. Sign in to [Docker Hub](https://hub.docker.com). +2. Select **Repositories**. + + A list of your repositories appears. + +3. Select a repository. + + The **General** page for the repository appears. + +4. Select the **Tags** tab. + +5. Select the corresponding checkbox next to the tags to delete. + +6. Select **Delete**. + + A confirmation dialog appears. + +7. Select **Delete**. diff --git a/content/manuals/docker-hub/images/vuln-scan-details.png b/content/manuals/docker-hub/repos/manage/images/vuln-scan-details.png similarity index 100% rename from content/manuals/docker-hub/images/vuln-scan-details.png rename to content/manuals/docker-hub/repos/manage/images/vuln-scan-details.png diff --git a/content/manuals/docker-hub/images/vuln-scan-report.png b/content/manuals/docker-hub/repos/manage/images/vuln-scan-report.png similarity index 100% rename from content/manuals/docker-hub/images/vuln-scan-report.png rename to content/manuals/docker-hub/repos/manage/images/vuln-scan-report.png diff --git a/content/manuals/docker-hub/repos/manage/information.md b/content/manuals/docker-hub/repos/manage/information.md new file mode 100644 index 00000000000..06f494da5a4 --- /dev/null +++ b/content/manuals/docker-hub/repos/manage/information.md @@ -0,0 +1,159 @@ +--- +description: Learn how to describe and optimize your Docker Hub repositories for better discoverability. +keywords: Docker Hub, Hub, repository information, repository discoverability, best practices +title: Repository information +toc_max: 3 +weight: 40 +aliases: +- /docker-hub/repos/categories/ +--- + +Each repository can include a description, an overview, and categories to help +users understand its purpose and usage. Adding clear repository information +ensures that others can find your images and use them effectively. + +You can only modify the repository information of repositories that aren't +archived. If a repository is archived, you must unarchive it to modify the +information. For more details, see [Unarchive a repository](../archive.md#unarchive-a-repository). + +## Repository description + +The description appears in search results when using the `docker search` command +and in the search results on Docker Hub. + +Consider the following repository description best practices. + +- Summarize the purpose. Clearly state what the image does in a concise and + specific manner. Make it clear if it's for a particular application, tool, or + platform, or has a distinct use case. +- Highlight key features or benefits. Briefly mention the primary benefits or + unique features that differentiate the image. Examples include high + performance, ease of use, lightweight build, or compatibility with specific + frameworks or operating systems. +- Include relevant keywords. Use keywords that users may search for to increase + visibility, such as technology stacks, use cases, or environments. +- Keep it concise. The description can be a maximum of 100 characters. Aim to + stay within one or two sentences for the description to ensure it's easy to + read in search results. Users should quickly understand the image's value. +- Focus on the audience. Consider your target audience (developers, system + administrators, etc.) and write the description to address their needs + directly. + +Following these practices can help make the description more engaging and +effective in search results, driving more relevant traffic to your repository. + +### Add or update a repository description + +1. Sign in to [Docker Hub](https://hub.docker.com). + +2. Select **Repositories**. + + A list of your repositories appears. + +3. Select a repository. + + The **General** page for the repository appears. + +4. Select the pencil icon under the description field. + +5. Specify a description. + + The description can be up to 100 characters long. + +6. Select **Update**. + +## Repository overview + +An overview describes what your image does and how to run it. It displays in the +public view of your repository when the repository has at least one image. If +automated builds are enabled, the overview will be synced from the source code +repository's `README.md` file on each successful build. + +Consider the following repository overview best practices. + +- Describe what the image is, the features it offers, and why it should be used. + Can include examples of usage or the team behind the project. +- Explain how to get started with running a container using the image. You can + include a minimal example of how to use the image in a Dockerfile. +- List the key image variants and tags to use them, as well as use cases for the + variants. +- Link to documentation or support sites, communities, or mailing lists for + additional resources. +- Provide contact information for the image maintainers. +- Include the license for the image and where to find more details if needed. + +### Add or update a repository overview + +1. Sign in to [Docker Hub](https://hub.docker.com). + +2. Select **Repositories**. + + A list of your repositories appears. + +3. Select a repository. + + The **General** page for the repository appears. + +4. Under **Repository overview**, select **Edit** or **Add overview**. + + The **Write** and **Preview** tabs appear. + +5. Under **Write**, specify your repository overview. + + You can use basic Markdown and use the **Preview** tab to preview the formatting. + +6. Select **Update**. + +## Repository categories + +You can tag Docker Hub repositories with categories, representing the primary +intended use cases for your images. This lets users more easily find and +explore content for the problem domain that they're interested in. + +### Available categories + +The Docker Hub content team maintains a curated list of categories. + +{{< include "hub-categories.md" >}} + +### Auto-generated categories + +> [!NOTE] +> +> Auto-generated categories only apply to Docker Verified Publishers and +> Docker-Sponsored Open Source program participants. + +For repositories that pre-date the Categories feature in Docker Hub, +categories have been automatically generated and applied, using OpenAI, based +on the repository title and description. + +As an owner of a repository that has been auto-categorized, you can manually +edit the categories if you think they're inaccurate. See [Manage categories for +a repository](#manage-categories-for-a-repository). + +The auto-generated categorization was a one-time effort to help seed categories +onto repositories created before the feature existed. Categories are not +assigned to new repositories automatically. + +### Manage categories for a repository + +You can tag a repository with up to three categories. + +To edit the categories of a repository: + +1. Sign in to [Docker Hub](https://hub.docker.com). +2. Select **Repositories**. + + A list of your repositories appears. + +3. Select a repository. + + The **General** page for the repository appears. + +4. Select the pencil icon under the description field. +5. Select the categories you want to apply. +6. Select **Update**. + +If you're missing a category, use the +[Give feedback link](https://docker.qualtrics.com/jfe/form/SV_03CrMyAkCWVylKu) +to let us know what categories you'd like to see. \ No newline at end of file diff --git a/content/manuals/docker-hub/repos/manage/trusted-content/_index.md b/content/manuals/docker-hub/repos/manage/trusted-content/_index.md new file mode 100644 index 00000000000..3b29c8873da --- /dev/null +++ b/content/manuals/docker-hub/repos/manage/trusted-content/_index.md @@ -0,0 +1,30 @@ +--- +description: Learn how to manage and contribute to trusted content. +keywords: Docker Hub, Hub, trusted content +title: Trusted content +weight: 100 +--- + +Docker's trusted content programs ensure that container images meet the highest +standards for security, quality, and reliability. These programs provide +opportunities for publishers and contributors to share their images with +millions of developers worldwide while gaining valuable insights into their +content's usage. By participating, you can enhance your content's visibility, +build credibility, and access tools to optimize its impact within the container +ecosystem. + +In this section, learn about: + +- [Docker Official Images](./official-images.md): Learn how to contribute, + propose, and maintain Docker Official Images to serve as reliable foundations + for containerized applications. +- [Docker-Sponsored Open Source (DSOS) Program](dsos-program.md): Discover how + open source projects can gain perks like verified badges, insights, and access + to Docker Scout, enhancing visibility and trust on Docker Hub. +- [Docker Verified Publisher (DVP) Program](./dvp-program.md): Explore how to + join the DVP program to showcase trusted, high-quality images with a verified + badge, gain priority in search results, access insights, and enhance security + through vulnerability analysis. +- [Insights and analytics](./insights-analytics.md): Access detailed metrics on + image and extension usage, including pull counts, geolocation, and client + data, to understand user behavior and optimize your content. \ No newline at end of file diff --git a/content/manuals/trusted-content/dsos-program.md b/content/manuals/docker-hub/repos/manage/trusted-content/dsos-program.md similarity index 87% rename from content/manuals/trusted-content/dsos-program.md rename to content/manuals/docker-hub/repos/manage/trusted-content/dsos-program.md index 8b686508a41..ee404d7db33 100644 --- a/content/manuals/trusted-content/dsos-program.md +++ b/content/manuals/docker-hub/repos/manage/trusted-content/dsos-program.md @@ -4,15 +4,14 @@ title: Docker-Sponsored Open Source Program keywords: docker hub, hub, insights, analytics, open source, Docker sponsored, program aliases: - /docker-hub/dsos-program/ + - /trusted-content/dsos-program/ --- -[Docker Sponsored Open Source images](https://hub.docker.com/search?q=&image_filter=open_source) are published and maintained by open-source projects sponsored by Docker through the program. +[Docker-Sponsored Open Source images](https://hub.docker.com/search?q=&image_filter=open_source) are published and maintained by open-source projects sponsored by Docker through the program. Images that are part of this program have a special badge on Docker Hub making it easier for users to identify projects that Docker has verified as trusted, secure, and active open-source projects. -![Docker-Sponsored Open Source badge](images/sponsored-badge-iso.png) - -## For content publishers +![Docker-Sponsored Open Source badge](../../../images/sponsored-badge-iso.png) The Docker-Sponsored Open Source (DSOS) Program provides several features and benefits to non-commercial open source developers. @@ -47,25 +46,25 @@ over the repository can change the repository logo. 1. Sign in to [Docker Hub](https://hub.docker.com). 2. Go to the page of the repository that you want to change the logo for. 3. Select the upload logo button, represented by a camera icon - ({{< inline-image src="images/upload_logo_sm.png" alt="camera icon" >}}) + ({{< inline-image src="../../../images/upload_logo_sm.png" alt="camera icon" >}}) overlaying the current repository logo. 4. In the dialog that opens, select the PNG image that you want to upload to set it as the logo for the repository. #### Remove the logo -Select the **Clear** button ({{< inline-image src="images/clear_logo_sm.png" +Select the **Clear** button ({{< inline-image src="../../../images/clear_logo_sm.png" alt="clear button" >}}) to remove a logo. Removing the logo makes the repository default to using the organization logo, if set, or the following default logo if not. -![Default logo which is a 3D grey cube](images/default_logo_sm.png) +![Default logo which is a 3D grey cube](../../../images/default_logo_sm.png) ### Verified Docker-Sponsored Open Source badge Docker verifies that developers can trust images with this badge on Docker Hub as an active open source project. -![Fluent org with a Docker-Sponsored Open Source badge](images/sponsored-badge.png) +![Fluent org with a Docker-Sponsored Open Source badge](../../../images/sponsored-badge.png) ### Insights and analytics @@ -75,8 +74,6 @@ the community uses Docker images, granting insight into user behavior. The usage metrics show the number of image pulls by tag or by digest, and breakdowns by geolocation, cloud provider, client, and more. -![The insights and analytics tab on the Docker Hub website](images/insights-and-analytics-tab.png) - You can select the time span for which you want to view analytics data. You can also export the data in either a summary or raw format. ### Docker Scout diff --git a/content/manuals/trusted-content/dvp-program.md b/content/manuals/docker-hub/repos/manage/trusted-content/dvp-program.md similarity index 85% rename from content/manuals/trusted-content/dvp-program.md rename to content/manuals/docker-hub/repos/manage/trusted-content/dvp-program.md index e9dc38a5096..39f75d10d30 100644 --- a/content/manuals/trusted-content/dvp-program.md +++ b/content/manuals/docker-hub/repos/manage/trusted-content/dvp-program.md @@ -13,6 +13,7 @@ aliases: - /docker-hub/publish/ - /docker-hub/publish/repository-logos/ - /docker-hub/dvp-program/ +- /trusted-content/dvp-program/ --- [The Docker Verified Publisher Program](https://hub.docker.com/search?q=&image_filter=store) provides high-quality images from commercial publishers verified by Docker. @@ -21,9 +22,7 @@ These images help development teams build secure software supply chains, minimiz Images that are part of this program have a special badge on Docker Hub making it easier for users to identify projects that Docker has verified as high-quality commercial publishers. -![Docker-Sponsored Open Source badge](./images/verified-publisher-badge-iso.png) - -## For content publishers +![Docker-Sponsored Open Source badge](../../../images/verified-publisher-badge-iso.png) The Docker Verified Publisher Program (DVP) provides several features and benefits to Docker Hub publishers. The program grants the following perks based on participation tier: @@ -57,37 +56,35 @@ over the repository can change the repository logo. 1. Sign in to [Docker Hub](https://hub.docker.com). 2. Go to the page of the repository that you want to change the logo for. 3. Select the upload logo button, represented by a camera icon ({{< inline-image - src="./images/upload_logo_sm.png" alt="camera icon" >}}) overlaying the + src="../../../images/upload_logo_sm.png" alt="camera icon" >}}) overlaying the current repository logo. 4. In the dialog that opens, select the PNG image that you want to upload to set it as the logo for the repository. #### Remove the logo -Select the **Clear** button ({{< inline-image src="images/clear_logo_sm.png" +Select the **Clear** button ({{< inline-image src="../../../images/clear_logo_sm.png" alt="clear button" >}}) to remove a logo. Removing the logo makes the repository default to using the organization logo, if set, or the following default logo if not. -![Default logo which is a 3D grey cube](images/default_logo_sm.png) +![Default logo which is a 3D grey cube](../../../images/default_logo_sm.png) ### Verified publisher badge Images that are part of this program have a badge on Docker Hub making it easier for developers to identify projects that Docker has verified as high quality publishers and with content they can trust. -![Docker, Inc. org with a verified publisher badge](./images/verified-publisher-badge.png) +![Docker, Inc. org with a verified publisher badge](../../../images/verified-publisher-badge.png) ### Insights and analytics -The [insights and analytics](/docker-hub/publish/insights-analytics) service provides usage metrics for how +The [insights and analytics](./insights-analytics.md) service provides usage metrics for how the community uses Docker images, granting insight into user behavior. The usage metrics show the number of image pulls by tag or by digest, and breakdowns by geolocation, cloud provider, client, and more. -![The insights and analytics tab on the Docker Hub website](./images/insights-and-analytics-tab.png) - You can select the time span for which you want to view analytics data. You can also export the data in either a summary or raw format. ### Vulnerability analysis @@ -98,7 +95,7 @@ Scanning images ensures that the published content is secure, and proves to developers that they can trust the image. You can enable analysis on a per-repository -basis. For more about using this feature, see [Basic vulnerability scanning](/docker-hub/vulnerability-scanning/). +basis. For more about using this feature, see [Basic vulnerability scanning](/docker-hub/repos/manage/vulnerability-scanning/). ### Who's eligible to become a verified publisher? diff --git a/content/manuals/trusted-content/insights-analytics.md b/content/manuals/docker-hub/repos/manage/trusted-content/insights-analytics.md similarity index 98% rename from content/manuals/trusted-content/insights-analytics.md rename to content/manuals/docker-hub/repos/manage/trusted-content/insights-analytics.md index c2dead2bbdc..0ffd17abcb5 100644 --- a/content/manuals/trusted-content/insights-analytics.md +++ b/content/manuals/docker-hub/repos/manage/trusted-content/insights-analytics.md @@ -5,6 +5,7 @@ keywords: docker hub, hub, insights, analytics, api, verified publisher aliases: - /docker-hub/publish/insights-analytics/ - /docker-hub/insights-analytics/ +- /trusted-content/insights-analytics/ --- Insights and analytics provides usage analytics for Docker Verified @@ -31,7 +32,7 @@ To view data in the chart: - Select the time interval: 3, 6, or 12 months - Select one or more repositories in the list -![Insights and analytics chart visualization](./images/chart.png) +![Insights and analytics chart visualization](../../../images/chart.png) > [!TIP] @@ -44,7 +45,7 @@ To view data in the chart: You can share the visualization with others using the **Share** icon above the chart. This is a convenient way to share statistics with others in your organization. -![Chart share icon](./images/chart-share-icon.png) +![Chart share icon](../../../images/chart-share-icon.png) Selecting the icon generates a link that's copied to your clipboard. The link preserves the display selections you made. When someone follows the link, the @@ -75,14 +76,14 @@ Export usage data for your organization's images using the Docker Hub website by 2. Choose your organization and select **Insights and analytics**. - ![Organization overview page, with the Insights and Analytics tab](./images/organization-tabs.png) + ![Organization overview page, with the Insights and Analytics tab](../../../images/organization-tabs.png) 3. Set the time span for which you want to export analytics data. The downloadable CSV files for summary and raw data appear on the right-hand side. - ![Filtering options and download links for analytics data](./images/download-analytics-data.png) + ![Filtering options and download links for analytics data](../../../images/download-analytics-data.png) ### Export data using the API diff --git a/content/manuals/trusted-content/official-images/contributing.md b/content/manuals/docker-hub/repos/manage/trusted-content/official-images.md similarity index 95% rename from content/manuals/trusted-content/official-images/contributing.md rename to content/manuals/docker-hub/repos/manage/trusted-content/official-images.md index 48189a44218..206ee0eaa55 100644 --- a/content/manuals/trusted-content/official-images/contributing.md +++ b/content/manuals/docker-hub/repos/manage/trusted-content/official-images.md @@ -1,9 +1,13 @@ --- -title: Contributing to Docker Official Images +title: Docker Official Images description: | This article describes how Docker Official Images are created, and how you can contribute or leave feedback. keywords: docker official images, doi, contributing, upstream, open source +aliases: +- /trusted-content/official-images/contributing/ +- /docker-hub/official_repos/ +- /docker-hub/official_images/ --- Docker, Inc. sponsors a dedicated team that's responsible for reviewing and diff --git a/content/manuals/docker-hub/vulnerability-scanning.md b/content/manuals/docker-hub/repos/manage/vulnerability-scanning.md similarity index 57% rename from content/manuals/docker-hub/vulnerability-scanning.md rename to content/manuals/docker-hub/repos/manage/vulnerability-scanning.md index 13faf26d0da..e9d14d3c892 100644 --- a/content/manuals/docker-hub/vulnerability-scanning.md +++ b/content/manuals/docker-hub/repos/manage/vulnerability-scanning.md @@ -1,22 +1,65 @@ --- -description: Static vulnerability scanning in Docker Hub +description: Learn about vulnerability scanning and Docker Scout image analysis in Docker Hub. keywords: scanning, vulnerabilities, Hub, static -title: Static vulnerability scanning +title: Image security insights weight: 70 +aliases: +- /docker-hub/vulnerability-scanning/ --- +Strengthen the security of your Docker images with Docker Hub's image security +insights. Docker Hub lets you perform either point-in-time static vulnerability +scanning or always up-to-date image analysis using Docker Scout. + +## Docker Scout image analysis + +After turning on Docker Scout image analysis, Docker Scout automatically +analyzes images in your Docker Hub repository. + +Image analysis extracts the Software Bill of Material (SBOM) and other image +metadata, and evaluates it against vulnerability data from security advisories. + +The following sections describe how to turn on or off Docker Scout image +analysis for a Docker Hub repository. For more details about the image analysis, +see [Docker Scout](/manuals/scout/_index.md). + +### Turn on Docker Scout image analysis + +1. Sign in to [Docker Hub](https://hub.docker.com). +2. Select **Repositories**. + + A list of your repositories appears. + +3. Select a repository. + + The **General** page for the repository appears. + +4. Select the **Settings** tab. +5. Under **Image security insight settings**, select **Docker Scout image analysis**. +6. Select **Save**. + +### Turn off Docker Scout image analysis + +1. Sign in to [Docker Hub](https://hub.docker.com). +2. Select **Repositories**. + + A list of your repositories appears. + +3. Select a repository. + + The **General** page for the repository appears. + +4. Select the **Settings** tab. +5. Under **Image security insight settings**, select **None**. +6. Select **Save**. + + +## Static vulnerability scanning + > [!NOTE] > -> This page describes the legacy static vulnerability scanning feature of -> Docker Hub. There's also [Docker Scout](../scout/_index.md), which provides -> more detailed and always up-to-date results, guided remediation steps for -> improving your security posture, and more. -> -> Docker Hub static scanning requires a [Docker Pro, Team, or Business -> subscription](../subscription/_index.md). - -Docker Hub static vulnerability scanning lets you automatically run a -point-in-time scan on your Docker images for vulnerabilities. +> Docker Hub static vulnerability scanning requires a Docker Pro, Team, or +> Business subscription. When you push an image to a Docker Hub repository after turning on static scanning, Docker Hub automatically scans the image to identify vulnerabilities. @@ -31,7 +74,7 @@ Scan results include: - A recommended fixed version, if available, to remediate the vulnerabilities discovered. -## Changes to static scanning in Docker Hub +### Changes to static scanning in Docker Hub From February 27th, 2023, Docker changed the technology that supports the Docker Hub static scanning feature. The static scanning is now powered natively @@ -47,72 +90,59 @@ There is no action required on your part. Scans continue to run as usual with no interruption or changes to pricing. Historical data continues to be available. -## Scan images with static vulnerability scanning +### Turn on static vulnerability scanning -Repository owners and administrators of a Docker Pro, Team, or a Business tier -enable and disable static vulnerability scanning. When scanning is active on a -repository, anyone with push access can trigger a scan by pushing an image to -Docker Hub. +Repository owners and administrators can enable static vulnerability scanning +on a repository. If you are a member of a Team or a Business subscription, +ensure the repository you would like to enable scanning on is part of the Team +or a Business tier. + +When scanning is active on a repository, anyone with push access can trigger a +scan by pushing an image to Docker Hub. -Additionally, repository owners in a Docker Pro subscription and team members in -a Team, or a Business subscription can view the detailed scan reports. +To enable static vulnerability scanning: > [!NOTE] > > Static vulnerability scanning supports scanning images which are of AMD64 > architecture, Linux OS, and are less than 10 GB in size. -### Turn on static vulnerability scanning +1. Sign in to [Docker Hub](https://hub.docker.com). +2. Select **Repositories**. -Repository owners and administrators can enable static vulnerability scanning -on a repository. If you are a member of a Team or a Business subscription, -ensure the repository you would like to enable scanning on is part of the Team -or a Business tier. + A list of your repositories appears. -To enable static vulnerability scanning: +3. Select a repository. + + The **General** page for the repository appears. -1. Sign in to your [Docker Hub](https://hub.docker.com) account. -2. Select **Repositories** and then choose a repository. -3. Go to the **Settings** tab. -4. Under **Image security insight settings**, select **Static scanning**. -5. Select **Save**. +4. Select the **Settings** tab. +5. Under **Image security insight settings**, select **Static scanning**. +6. Select **Save**. ### Scan an image To scan an image for vulnerabilities, push the image to Docker Hub, to the -repository for which you have turned on scanning: - -1. Ensure you have installed Docker locally. See [Get Docker](/get-started/get-docker.md) - to download and install Docker on your local machine. -2. Use the command line to log into your Docker account. See - [`docker login`](/reference/cli/docker/login.md) for more - information. -3. Tag the image to scan. For example, to tag a Redis image, run: +repository for which you have turned on scanning. - ```console - $ docker tag redis /:latest - ``` +### View the vulnerability report -4. Push the image to Docker Hub to trigger a static vulnerability scan for the - image: - - ```console - $ docker push /:latest - ``` +To view the vulnerability report: -## View the vulnerability report +1. Sign in to [Docker Hub](https://hub.docker.com). +2. Select **Repositories**. -To view the vulnerability report: + A list of your repositories appears. -1. Go to [Docker Hub](https://hub.docker.com) and open the repository page to - view a summary of the static vulnerability scanning report. +3. Select a repository. + The **General** page for the repository appears. It may take a couple of minutes for the vulnerability report to appear in your repository. ![Vulnerability scan report](images/vuln-scan-report.png) -2. Select the **Tags** tab, then **Digest**, then **Vulnerabilities** to view the +4. Select the **Tags** tab, then **Digest**, then **Vulnerabilities** to view the detailed scan report. The scan report displays vulnerabilities identified by the scan, sorting them @@ -153,15 +183,22 @@ actions you can take to remediate the vulnerabilities. For example, you can: Docker Scout can provide you with concrete and contextual remediation steps for improving image security. For more information, see -[Docker Scout](../scout/_index.md). +[Docker Scout](/manuals/scout/_index.md). ### Turn off static vulnerability scanning Repository owners and administrators can disable static vulnerability scanning on a repository. To disable scanning: -1. Sign in to your [Docker Hub](https://hub.docker.com) account. -2. Go to **Repositories** and then select a repository from the list. -3. Go to the **Settings** tab. -4. Under **Image security insight settings**, select **None**. -5. Select **Save**. +1. Sign in to [Docker Hub](https://hub.docker.com). +2. Select **Repositories**. + + A list of your repositories appears. + +3. Select a repository. + + The **General** page for the repository appears. + +4. Select the **Settings** tab. +5. Under **Image security insight settings**, select **None**. +6. Select **Save**. diff --git a/content/manuals/docker-hub/webhooks.md b/content/manuals/docker-hub/repos/manage/webhooks.md similarity index 98% rename from content/manuals/docker-hub/webhooks.md rename to content/manuals/docker-hub/repos/manage/webhooks.md index 7eed021aee9..67928127f7d 100644 --- a/content/manuals/docker-hub/webhooks.md +++ b/content/manuals/docker-hub/repos/manage/webhooks.md @@ -2,7 +2,9 @@ description: Docker Hub Webhooks keywords: Docker, webhooks, hub, builds title: Webhooks -weight: 40 +weight: 80 +aliases: +- /docker-hub/webhooks/ --- You can use webhooks to cause an action in another service in response to a push event in the repository. Webhooks are POST requests sent to a URL you define in Docker Hub. diff --git a/content/manuals/docker-hub/repos/settings.md b/content/manuals/docker-hub/repos/settings.md new file mode 100644 index 00000000000..279295d458f --- /dev/null +++ b/content/manuals/docker-hub/repos/settings.md @@ -0,0 +1,55 @@ +--- +description: Learn about personal repository settings in Docker Hub +keywords: Docker Hub, Hub, repositories, settings +title: Personal settings for repositories +linkTitle: Personal settings +toc_max: 3 +weight: 50 +--- + +For your account, you can set personal settings for repositories, including +default repository privacy and autobuild notifications. + +## Default repository privacy + +When creating a new repository in Docker Hub, you are able to specify the +repository visibility. You can also change the visibility at any time in Docker Hub. + +The default setting is useful if you use the `docker push` command to push to a +repository that doesn't exist yet. In this case, Docker Hub automatically +creates the repository with your default repository privacy. + +### Configure default repository privacy + +1. Sign in to [Docker Hub](https://hub.docker.com). +2. Select **Repositories**. +3. Near the top-right corner, select the settings icon and then **Repository Settings**. +4. Select the **Default privacy** for any new repository created. + + - **Public**: All new repositories appear in Docker Hub search results and can be + pulled by everyone. + - **Private**: All new repositories don't appear in Docker Hub search results + and are only accessible to you and collaborators. In addition, if the + repository is created in an organization's namespace, then the repository + is accessible to those with applicable roles or permissions. + +5. Select **Save**. + +## Autobuild notifications + +You can send notifications to your email for all your repositories using +autobuilds. + +### Configure autobuild notifications + +1. Sign in to [Docker Hub](https://hub.docker.com). +2. Select **Repositories**. +3. Near the top-right corner, select the settings icon and then **Repository Settings**. +4. Select the **Notifications** +5. Select the notifications to receive by email. + + - **Off**: No notifications. + - **Only failures**: Only notifications about failed builds. + - **Everything**: Notifications for successful and failed builds. + +6. Select **Save**. diff --git a/content/manuals/docker-hub/service-accounts.md b/content/manuals/docker-hub/service-accounts.md index 9237220d091..845ebd96670 100644 --- a/content/manuals/docker-hub/service-accounts.md +++ b/content/manuals/docker-hub/service-accounts.md @@ -7,62 +7,29 @@ weight: 50 {{< include "new-plans.md" >}} -> [!NOTE] +> [!IMPORTANT] > -> Service accounts require a -> [Docker Team, or Business subscription](../subscription/_index.md). +> As of December 10, 2024, service accounts are no longer available. Existing +> Service Account agreements will be honored until their current term expires, +> but new purchases or renewals of service accounts no longer available and +> customers must renew under a new subscription plan. > -> Docker recommends that you use organization access tokens instead of service -> accounts. For more details, see [Organization access -> tokens](/security/for-admins/access-tokens/). +> Docker recommends transitioning to [Organization Access Tokens +> (OATs)](../security/for-admins/access-tokens.md), which can provide similar +> functionality. A service account is a Docker ID used for automated management of container images or containerized applications. Service accounts are typically used in automated workflows, and don't share Docker IDs with the members in the organization. Common use cases for service accounts include mirroring content on Docker Hub, or tying in image pulls from your CI/CD process. -> [!NOTE] -> -> All paid Docker subscriptions include up to 5000 pulls per day per authenticated user. If you require a higher number of pulls, you can purchase an Enhanced Service Account add-on. - -## Enhanced Service Account add-on pricing - -Refer to the following table for details on the Enhanced Service Account add-on pricing: - -| Tier | Pull Rates Per Day* | Annual Fee | -| ------ | ------ | ------ | -| 1 | 5,000-10,000 | $9,950/yr | -| 2 | 10,000-25,000 | $17,950/yr | -| 3 | 25,000-50,000 | $32,950/yr | -| 4 | 50,000-100,000 | $58,950/yr | -| 5 | 100,000+ | [Contact Sales](https://www.docker.com/pricing/contact-sales/) | - -*Once you establish the initial Tier, that's the minimum fee for the year. Annual commitment required. The service account may exceed Pulls by up to 25% for up to 20 days during the year without incurring additional fees. Reports on consumption are available upon request. At the end of the initial 1-year term, the appropriate Tier will be established for the following year. - -## How a pull is defined - -- Pulls are accounted to the user doing the pull, not to the owner of the image. -- A pull request is defined as up to two `GET` requests on registry manifest URLs (`/v2/*/manifests/*`). -- A normal image pull makes a single manifest request. -- A pull request for a multi-arch image makes two manifest requests. -- `HEAD` requests aren't counted. -- Some images are unlimited through our [Docker Sponsored Open Source](https://www.docker.com/blog/expanded-support-for-open-source-software-projects/) and [Docker Verified Publisher](https://www.docker.com/partners/programs) programs. - -## Creating a new service account - -To create a new service account for your Team account: - -1. Create a new Docker ID. -2. Create a [team](manage-a-team.md) in your organization and grant it read-only access to your private repositories. -3. Add the new Docker ID to your [organization](orgs.md). -4. Add the new Docker ID to the [team](manage-a-team.md) you created earlier. -5. Create a new [personal access token (PAT)](/security/for-developers/access-tokens/) from the user account and use it for CI. - -> [!NOTE] -> -> If you want a read-only PAT just for your open-source repositories, or to access -official images and other public images, you don't have to grant any access permissions to the new Docker ID. +## Enhanced Service Account add-on tiers -## Additional information +Refer to the following table for details on the Enhanced Service Account add-ons: -Refer to the following topics for additional information: +| Tier | Pull Rates Per Day\* | +| ------ | ------ | +| 1 | 5,000-10,000 | +| 2 | 10,000-25,000 | +| 3 | 25,000-50,000 | +| 4 | 50,000-100,000 | +| 5 | 100,000+ | -- [Mirroring Docker Hub](./mirror.md) -- [Docker pricing FAQs](https://www.docker.com/pricing/faq/) +*The service account may exceed Pulls by up to 25% for up to 20 days during the year without incurring additional fees. Reports on consumption are available upon request. \ No newline at end of file diff --git a/content/manuals/engine/_index.md b/content/manuals/engine/_index.md index 6a2e265d7f9..febf3717d81 100644 --- a/content/manuals/engine/_index.md +++ b/content/manuals/engine/_index.md @@ -1,9 +1,11 @@ --- -title: Docker Engine overview -linkTitle: Docker Engine -weight: 100 +title: Docker Engine +weight: 10 description: Find a comprehensive overview of Docker Engine, including how to install, storage details, networking, and more keywords: Engine +params: + sidebar: + group: Open source grid: - title: Install Docker Engine description: Learn how to install the open source Docker Engine for your distribution. diff --git a/content/manuals/engine/cli/proxy.md b/content/manuals/engine/cli/proxy.md index bcda40f3d7a..050c4160ec0 100644 --- a/content/manuals/engine/cli/proxy.md +++ b/content/manuals/engine/cli/proxy.md @@ -12,7 +12,7 @@ This page describes how to configure the Docker CLI to use proxies via environment variables in containers. This page doesn't describe how to configure proxies for Docker Desktop. -For instructions, see [configuring Docker Desktop to use HTTP/HTTPS proxies](/manuals/desktop/settings.md#proxies). +For instructions, see [configuring Docker Desktop to use HTTP/HTTPS proxies](/manuals/desktop/settings-and-maintenance/settings.md#proxies). If you're running Docker Engine without Docker Desktop, refer to [Configure the Docker daemon to use a proxy](/manuals/engine/daemon/proxy.md) diff --git a/content/manuals/engine/containers/runmetrics.md b/content/manuals/engine/containers/runmetrics.md index d16b06be934..2f95b808ea0 100644 --- a/content/manuals/engine/containers/runmetrics.md +++ b/content/manuals/engine/containers/runmetrics.md @@ -38,7 +38,7 @@ CPU, memory, and block I/O usage. You can access those metrics and obtain network usage metrics as well. This is relevant for "pure" LXC containers, as well as for Docker containers. -Control groups are exposed through a pseudo-filesystem. In modern distros, you +Control groups are exposed through a pseudo-filesystem. In modern distributions, you should find this filesystem under `/sys/fs/cgroup`. Under that directory, you see multiple sub-directories, called `devices`, `freezer`, `blkio`, and so on. Each sub-directory actually corresponds to a different cgroup hierarchy. @@ -151,7 +151,7 @@ more pseudo-files exist and contain statistics. Memory metrics are found in the `memory` cgroup. The memory control group adds a little overhead, because it does very fine-grained -accounting of the memory usage on your host. Therefore, many distros +accounting of the memory usage on your host. Therefore, many distributions chose to not enable it by default. Generally, to enable it, all you have to do is to add some kernel command-line parameters: `cgroup_enable=memory swapaccount=1`. diff --git a/content/manuals/engine/daemon/_index.md b/content/manuals/engine/daemon/_index.md index fd93053b0fd..3b1ee08307a 100644 --- a/content/manuals/engine/daemon/_index.md +++ b/content/manuals/engine/daemon/_index.md @@ -33,7 +33,7 @@ This page shows you how to customize the Docker daemon, `dockerd`. > [!NOTE] > > This page is for users who've installed Docker Engine manually. If you're -> using Docker Desktop, refer to the [settings page](/manuals/desktop/settings.md#docker-engine). +> using Docker Desktop, refer to the [settings page](/manuals/desktop/settings-and-maintenance/settings.md#docker-engine). ## Configure the Docker daemon diff --git a/content/manuals/engine/daemon/alternative-runtimes.md b/content/manuals/engine/daemon/alternative-runtimes.md index 0cde0c7cfb3..95bb542642d 100644 --- a/content/manuals/engine/daemon/alternative-runtimes.md +++ b/content/manuals/engine/daemon/alternative-runtimes.md @@ -30,7 +30,7 @@ You can also use runtimes designed as drop-in replacements for runc. Such runtimes depend on the runc containerd shim for invoking the runtime binary. You must manually register such runtimes in the daemon configuration. -[youki](https://github.com/containers/youki) +[youki](https://github.com/youki-dev/youki) is one example of a runtime that can function as a runc drop-in replacement. Refer to the [youki example](#youki) explaining the setup. @@ -133,7 +133,7 @@ To add youki as a container runtime: 1. Install youki and its dependencies. For instructions, refer to the - [official setup guide](https://containers.github.io/youki/user/basic_setup.html). + [official setup guide](https://youki-dev.github.io/youki/user/basic_setup.html). 2. Register youki as a runtime for Docker by editing the Docker daemon configuration file, located at `/etc/docker/daemon.json` by default. diff --git a/content/manuals/engine/daemon/prometheus.md b/content/manuals/engine/daemon/prometheus.md index a4dbdeb6210..5e194d627da 100644 --- a/content/manuals/engine/daemon/prometheus.md +++ b/content/manuals/engine/daemon/prometheus.md @@ -48,8 +48,10 @@ Add the following configuration: Save the file, or in the case of Docker Desktop for Mac or Docker Desktop for Windows, save the configuration. Restart Docker. -Docker now exposes Prometheus-compatible metrics on port 9323 on the loopback -interface. +Docker now exposes Prometheus-compatible metrics on port 9323 via the loopback +interface. You can configure it to use the wildcard address `0.0.0.0` instead, +but this will expose the Prometheus port to the wider network. Consider your +threat model carefully when deciding which option best suits your environment. ### Create a Prometheus configuration diff --git a/content/manuals/engine/daemon/proxy.md b/content/manuals/engine/daemon/proxy.md index 158feecf85a..d2a4a7ebfe2 100644 --- a/content/manuals/engine/daemon/proxy.md +++ b/content/manuals/engine/daemon/proxy.md @@ -26,7 +26,7 @@ Docker CLI to use a proxy server](/manuals/engine/cli/proxy.md). > [!IMPORTANT] > Proxy configurations specified in the `daemon.json` are ignored by Docker > Desktop. If you use Docker Desktop, you can configure proxies using the -> [Docker Desktop settings](/manuals/desktop/settings.md#proxies). +> [Docker Desktop settings](/manuals/desktop/settings-and-maintenance/settings.md#proxies). There are two ways you can configure these settings: diff --git a/content/manuals/engine/install/_index.md b/content/manuals/engine/install/_index.md index b67dbdef795..cf03b08c40a 100644 --- a/content/manuals/engine/install/_index.md +++ b/content/manuals/engine/install/_index.md @@ -35,11 +35,8 @@ aliases: This section describes how to install Docker Engine on Linux, also known as Docker CE. Docker Engine is also available for Windows, macOS, and Linux, -through Docker Desktop. For instructions on how to install Docker Desktop, see: - -- [Docker Desktop for Linux](/manuals/desktop/install/linux/_index.md) -- [Docker Desktop for Mac (macOS)](/manuals/desktop/install/mac-install.md) -- [Docker Desktop for Windows](/manuals/desktop/install/windows-install.md) +through Docker Desktop. For instructions on how to install Docker Desktop, +see: [Overview of Docker Desktop](/manuals/desktop/_index.md). ## Supported platforms @@ -54,32 +51,32 @@ through Docker Desktop. For instructions on how to install Docker Desktop, see: | [Ubuntu](ubuntu.md) | ✅ | ✅ | ✅ | ✅ | ✅ | | [Binaries](binaries.md) | ✅ | ✅ | ✅ | | | -### Other Linux distros +### Other Linux distributions > [!NOTE] > > While the following instructions may work, Docker doesn't test or verify -> installation on distro derivatives. +> installation on distribution derivatives. - If you use Debian derivatives such as "BunsenLabs Linux", "Kali Linux" or "LMDE" (Debian-based Mint) should follow the installation instructions for - [Debian](debian.md), substitute the version of your distro for the - corresponding Debian release. Refer to the documentation of your distro to find + [Debian](debian.md), substitute the version of your distribution for the + corresponding Debian release. Refer to the documentation of your distribution to find which Debian release corresponds with your derivative version. - Likewise, if you use Ubuntu derivatives such as "Kubuntu", "Lubuntu" or "Xubuntu" you should follow the installation instructions for [Ubuntu](ubuntu.md), - substituting the version of your distro for the corresponding Ubuntu release. - Refer to the documentation of your distro to find which Ubuntu release + substituting the version of your distribution for the corresponding Ubuntu release. + Refer to the documentation of your distribution to find which Ubuntu release corresponds with your derivative version. -- Some Linux distros provide a package of Docker Engine through their +- Some Linux distributions provide a package of Docker Engine through their package repositories. These packages are built and maintained by the Linux - distro's package maintainers and may have differences in configuration + distribution's package maintainers and may have differences in configuration or are built from modified source code. Docker isn't involved in releasing these packages and you should report any bugs or issues involving these packages to - your Linux distro's issue tracker. + your Linux distribution's issue tracker. Docker provides [binaries](binaries.md) for manual installation of Docker Engine. -These binaries are statically linked and you can use them on any Linux distro. +These binaries are statically linked and you can use them on any Linux distribution. ## Release channels diff --git a/content/manuals/engine/install/centos.md b/content/manuals/engine/install/centos.md index 61ecd8296ba..a79b2cd0535 100644 --- a/content/manuals/engine/install/centos.md +++ b/content/manuals/engine/install/centos.md @@ -1,7 +1,7 @@ --- description: Learn how to install Docker Engine on CentOS. These instructions cover the different installation methods, how to uninstall, and next steps. -keywords: requirements, yum, installation, centos, install, uninstall, docker engine, upgrade, update +keywords: requirements, dnf, yum, installation, centos, install, uninstall, docker engine, upgrade, update title: Install Docker Engine on CentOS linkTitle: CentOS weight: 60 @@ -36,12 +36,14 @@ default. If you have disabled it, you need to re-enable it. ### Uninstall old versions -Older versions of Docker went by `docker` or `docker-engine`. -Uninstall any such older versions before attempting to install a new version, -along with associated dependencies. +Before you can install Docker Engine, you need to uninstall any conflicting packages. + +Your Linux distribution may provide unofficial Docker packages, which may conflict +with the official packages provided by Docker. You must uninstall these packages +before you install the official version of Docker Engine. ```console -$ sudo yum remove docker \ +$ sudo dnf remove docker \ docker-client \ docker-client-latest \ docker-common \ @@ -51,7 +53,7 @@ $ sudo yum remove docker \ docker-engine ``` -`yum` might report that you have none of these packages installed. +`dnf` might report that you have none of these packages installed. Images, containers, volumes, and networks stored in `/var/lib/docker/` aren't automatically removed when you uninstall Docker. @@ -81,17 +83,17 @@ Docker from the repository. #### Set up the repository -Install the `yum-utils` package (which provides the `yum-config-manager` -utility) and set up the repository. +Install the `dnf-plugins-core` package (which provides the commands to manage +your DNF repositories) and set up the repository. ```console -$ sudo yum install -y yum-utils -$ sudo yum-config-manager --add-repo {{% param "download-url-base" %}}/docker-ce.repo +$ sudo dnf -y install dnf-plugins-core +$ sudo dnf config-manager --add-repo {{% param "download-url-base" %}}/docker-ce.repo ``` #### Install Docker Engine -1. Install Docker Engine, containerd, and Docker Compose: +1. Install the Docker packages. {{< tabs >}} {{< tab name="Latest" >}} @@ -99,7 +101,7 @@ $ sudo yum-config-manager --add-repo {{% param "download-url-base" %}}/docker-ce To install the latest version, run: ```console - $ sudo yum install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin + $ sudo dnf install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin ``` If prompted to accept the GPG key, verify that the fingerprint matches @@ -115,10 +117,10 @@ $ sudo yum-config-manager --add-repo {{% param "download-url-base" %}}/docker-ce the repository: ```console - $ yum list docker-ce --showduplicates | sort -r + $ dnf list docker-ce --showduplicates | sort -r - docker-ce.x86_64 3:27.1.1-1.el9 docker-ce-stable - docker-ce.x86_64 3:27.1.0-1.el9 docker-ce-stable + docker-ce.x86_64 3:{{% param "docker_ce_version" %}}-1.el9 docker-ce-stable + docker-ce.x86_64 3:{{% param "docker_ce_version_prev" %}}-1.el9 docker-ce-stable <...> ``` @@ -127,13 +129,13 @@ $ sudo yum-config-manager --add-repo {{% param "download-url-base" %}}/docker-ce Install a specific version by its fully qualified package name, which is the package name (`docker-ce`) plus the version string (2nd column), - separated by a hyphen (`-`). For example, `docker-ce-3:27.1.1-1.el9`. + separated by a hyphen (`-`). For example, `docker-ce-3:{{% param "docker_ce_version" %}}-1.el9`. Replace `` with the desired version and then run the following command to install: ```console - $ sudo yum install docker-ce- docker-ce-cli- containerd.io docker-buildx-plugin docker-compose-plugin + $ sudo dnf install docker-ce- docker-ce-cli- containerd.io docker-buildx-plugin docker-compose-plugin ``` This command installs Docker, but it doesn't start Docker. It also creates a @@ -142,14 +144,17 @@ $ sudo yum-config-manager --add-repo {{% param "download-url-base" %}}/docker-ce {{< /tab >}} {{< /tabs >}} -2. Start Docker. +2. Start Docker Engine. ```console - $ sudo systemctl start docker + $ sudo systemctl enable --now docker ``` -3. Verify that the Docker Engine installation is successful by running the - `hello-world` image. + This configures the Docker systemd service to start automatically when you + boot your system. If you don't want Docker to start automatically, use `sudo + systemctl start docker` instead. + +3. Verify that the installation is successful by running the `hello-world` image: ```console $ sudo docker run hello-world @@ -182,20 +187,23 @@ download a new file each time you want to upgrade Docker Engine. the Docker package. ```console - $ sudo yum install /path/to/package.rpm + $ sudo dnf install /path/to/package.rpm ``` Docker is installed but not started. The `docker` group is created, but no users are added to the group. -3. Start Docker. +3. Start Docker Engine. ```console - $ sudo systemctl start docker + $ sudo systemctl enable --now docker ``` -4. Verify that the Docker Engine installation is successful by running the - `hello-world` image. + This configures the Docker systemd service to start automatically when you + boot your system. If you don't want Docker to start automatically, use `sudo + systemctl start docker` instead. + +4. Verify that the installation is successful by running the `hello-world` image: ```console $ sudo docker run hello-world @@ -211,8 +219,8 @@ You have now successfully installed and started Docker Engine. #### Upgrade Docker Engine To upgrade Docker Engine, download the newer package files and repeat the -[installation procedure](#install-from-a-package), using `yum -y upgrade` -instead of `yum -y install`, and point to the new files. +[installation procedure](#install-from-a-package), using `dnf upgrade` +instead of `dnf install`, and point to the new files. {{< include "install-script.md" >}} @@ -221,7 +229,7 @@ instead of `yum -y install`, and point to the new files. 1. Uninstall the Docker Engine, CLI, containerd, and Docker Compose packages: ```console - $ sudo yum remove docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin docker-ce-rootless-extras + $ sudo dnf remove docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin docker-ce-rootless-extras ``` 2. Images, containers, volumes, or custom configuration files on your host diff --git a/content/manuals/engine/install/debian.md b/content/manuals/engine/install/debian.md index 47f635399a9..1a0e17c9f10 100644 --- a/content/manuals/engine/install/debian.md +++ b/content/manuals/engine/install/debian.md @@ -52,9 +52,9 @@ and ppc64le (ppc64el) architectures. Before you can install Docker Engine, you need to uninstall any conflicting packages. -Distro maintainers provide unofficial distributions of Docker packages in -their repositories. You must uninstall these packages before you can install the -official version of Docker Engine. +Your Linux distribution may provide unofficial Docker packages, which may conflict +with the official packages provided by Docker. You must uninstall these packages +before you install the official version of Docker Engine. The unofficial packages to uninstall are: @@ -86,7 +86,7 @@ clean installation, and prefer to clean up any existing data, read the You can install Docker Engine in different ways, depending on your needs: - Docker Engine comes bundled with - [Docker Desktop for Linux](/manuals/desktop/install/linux/_index.md). This is + [Docker Desktop for Linux](/manuals/desktop/setup/install/linux/_index.md). This is the easiest and quickest way to get started. - Set up and install Docker Engine from @@ -123,7 +123,7 @@ Docker from the repository. > [!NOTE] > - > If you use a derivative distro, such as Kali Linux, + > If you use a derivative distribution, such as Kali Linux, > you may need to substitute the part of this command that's expected to > print the version codename: > @@ -155,23 +155,22 @@ Docker from the repository. # List the available versions: $ apt-cache madison docker-ce | awk '{ print $3 }' - 5:27.1.1-1~debian.12~bookworm - 5:27.1.0-1~debian.12~bookworm + 5:{{% param "docker_ce_version" %}}-1~debian.12~bookworm + 5:{{% param "docker_ce_version_prev" %}}-1~debian.12~bookworm ... ``` Select the desired version and install: ```console - $ VERSION_STRING=5:27.1.1-1~debian.12~bookworm + $ VERSION_STRING=5:{{% param "docker_ce_version" %}}-1~debian.12~bookworm $ sudo apt-get install docker-ce=$VERSION_STRING docker-ce-cli=$VERSION_STRING containerd.io docker-buildx-plugin docker-compose-plugin ``` {{< /tab >}} {{< /tabs >}} -3. Verify that the installation is successful by running the `hello-world` - image: +3. Verify that the installation is successful by running the `hello-world` image: ```console $ sudo docker run hello-world @@ -226,8 +225,7 @@ download a new file each time you want to upgrade Docker Engine. The Docker daemon starts automatically. -6. Verify that the Docker Engine installation is successful by running the - `hello-world` image: +6. Verify that the installation is successful by running the `hello-world` image: ```console $ sudo service docker start @@ -250,26 +248,26 @@ To upgrade Docker Engine, download the newer package files and repeat the ## Uninstall Docker Engine -1. Uninstall the Docker Engine, CLI, containerd, and Docker Compose packages: +1. Uninstall the Docker Engine, CLI, containerd, and Docker Compose packages: - ```console - $ sudo apt-get purge docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin docker-ce-rootless-extras - ``` + ```console + $ sudo apt-get purge docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin docker-ce-rootless-extras + ``` -2. Images, containers, volumes, or custom configuration files on your host - aren't automatically removed. To delete all images, containers, and volumes: +2. Images, containers, volumes, or custom configuration files on your host + aren't automatically removed. To delete all images, containers, and volumes: - ```console - $ sudo rm -rf /var/lib/docker - $ sudo rm -rf /var/lib/containerd - ``` + ```console + $ sudo rm -rf /var/lib/docker + $ sudo rm -rf /var/lib/containerd + ``` -3. Remove source list and keyrings +3. Remove source list and keyrings - ```console - $ sudo rm /etc/apt/sources.list.d/docker.list - $ sudo rm /etc/apt/keyrings/docker.asc - ``` + ```console + $ sudo rm /etc/apt/sources.list.d/docker.list + $ sudo rm /etc/apt/keyrings/docker.asc + ``` You have to delete any edited configuration files manually. diff --git a/content/manuals/engine/install/fedora.md b/content/manuals/engine/install/fedora.md index 4c2f4c5f45f..9ee612c60cf 100644 --- a/content/manuals/engine/install/fedora.md +++ b/content/manuals/engine/install/fedora.md @@ -1,7 +1,7 @@ --- description: Learn how to install Docker Engine on Fedora. These instructions cover the different installation methods, how to uninstall, and next steps. -keywords: requirements, apt, installation, fedora, install fedora, install docker engine, rpm, install, uninstall, upgrade, +keywords: requirements, dnf, installation, fedora, install fedora, install docker engine, rpm, install, uninstall, upgrade, update title: Install Docker Engine on Fedora linkTitle: Fedora @@ -26,14 +26,16 @@ To get started with Docker Engine on Fedora, make sure you To install Docker Engine, you need a maintained version of one of the following Fedora versions: -- Fedora 39 - Fedora 40 +- Fedora 41 ### Uninstall old versions -Older versions of Docker went by `docker` or `docker-engine`. -Uninstall any such older versions before attempting to install a new version, -along with associated dependencies. +Before you can install Docker Engine, you need to uninstall any conflicting packages. + +Your Linux distribution may provide unofficial Docker packages, which may conflict +with the official packages provided by Docker. You must uninstall these packages +before you install the official version of Docker Engine. ```console $ sudo dnf remove docker \ @@ -88,11 +90,11 @@ $ sudo dnf-3 config-manager --add-repo {{% param "download-url-base" %}}/docker- #### Install Docker Engine -1. Install Docker Engine, containerd, and Docker Compose: +1. Install the Docker packages. {{< tabs >}} {{< tab name="Latest" >}} - + To install the latest version, run: ```console @@ -114,8 +116,8 @@ $ sudo dnf-3 config-manager --add-repo {{% param "download-url-base" %}}/docker- ```console $ dnf list docker-ce --showduplicates | sort -r - docker-ce.x86_64 3:27.1.1-1.fc40 docker-ce-stable - docker-ce.x86_64 3:27.1.0-1.fc40 docker-ce-stable + docker-ce.x86_64 3:{{% param "docker_ce_version" %}}-1.fc41 docker-ce-stable + docker-ce.x86_64 3:{{% param "docker_ce_version_prev" %}}-1.fc41 docker-ce-stable <...> ``` @@ -124,29 +126,32 @@ $ sudo dnf-3 config-manager --add-repo {{% param "download-url-base" %}}/docker- Install a specific version by its fully qualified package name, which is the package name (`docker-ce`) plus the version string (2nd column), - separated by a hyphen (`-`). For example, `docker-ce-3:27.1.1-1.fc40`. + separated by a hyphen (`-`). For example, `docker-ce-3:{{% param "docker_ce_version" %}}-1.fc41`. Replace `` with the desired version and then run the following command to install: ```console - $ sudo dnf -y install docker-ce- docker-ce-cli- containerd.io docker-buildx-plugin docker-compose-plugin + $ sudo dnf install docker-ce- docker-ce-cli- containerd.io docker-buildx-plugin docker-compose-plugin ``` This command installs Docker, but it doesn't start Docker. It also creates a `docker` group, however, it doesn't add any users to the group by default. - + {{< /tab >}} {{< /tabs >}} -2. Start Docker. +2. Start Docker Engine. ```console - $ sudo systemctl start docker + $ sudo systemctl enable --now docker ``` -3. Verify that the Docker Engine installation is successful by running the - `hello-world` image. + This configures the Docker systemd service to start automatically when you + boot your system. If you don't want Docker to start automatically, use `sudo + systemctl start docker` instead. + +3. Verify that the installation is successful by running the `hello-world` image: ```console $ sudo docker run hello-world @@ -179,20 +184,23 @@ download a new file each time you want to upgrade Docker Engine. the Docker package. ```console - $ sudo dnf -y install /path/to/package.rpm + $ sudo dnf install /path/to/package.rpm ``` Docker is installed but not started. The `docker` group is created, but no users are added to the group. -3. Start Docker. +3. Start Docker Engine. ```console - $ sudo systemctl start docker + $ sudo systemctl enable --now docker ``` -4. Verify that the Docker Engine installation is successful by running the - `hello-world` image. + This configures the Docker systemd service to start automatically when you + boot your system. If you don't want Docker to start automatically, use `sudo + systemctl start docker` instead. + +4. Verify that the installation is successful by running the `hello-world` image: ```console $ sudo docker run hello-world @@ -208,8 +216,8 @@ You have now successfully installed and started Docker Engine. #### Upgrade Docker Engine To upgrade Docker Engine, download the newer package files and repeat the -[installation procedure](#install-from-a-package), using `dnf -y upgrade` -instead of `dnf -y install`, and point to the new files. +[installation procedure](#install-from-a-package), using `dnf upgrade` +instead of `dnf install`, and point to the new files. {{< include "install-script.md" >}} diff --git a/content/manuals/engine/install/raspberry-pi-os.md b/content/manuals/engine/install/raspberry-pi-os.md index f9e5b2d7d01..ca4d69caedd 100644 --- a/content/manuals/engine/install/raspberry-pi-os.md +++ b/content/manuals/engine/install/raspberry-pi-os.md @@ -53,9 +53,9 @@ To install Docker Engine, you need one of the following OS versions: Before you can install Docker Engine, you need to uninstall any conflicting packages. -Distro maintainers provide an unofficial distributions of Docker packages in -APT. You must uninstall these packages before you can install the official -version of Docker Engine. +Your Linux distribution may provide unofficial Docker packages, which may conflict +with the official packages provided by Docker. You must uninstall these packages +before you install the official version of Docker Engine. The unofficial packages to uninstall are: @@ -87,7 +87,7 @@ clean installation, and prefer to clean up any existing data, read the You can install Docker Engine in different ways, depending on your needs: - Docker Engine comes bundled with - [Docker Desktop for Linux](/manuals/desktop/install/linux/_index.md). This is + [Docker Desktop for Linux](/manuals/desktop/setup/install/linux/_index.md). This is the easiest and quickest way to get started. - Set up and install Docker Engine from @@ -143,23 +143,22 @@ Docker from the repository. # List the available versions: $ apt-cache madison docker-ce | awk '{ print $3 }' - 5:27.1.1-1~raspbian.12~bookworm - 5:27.1.0-1~raspbian.12~bookworm + 5:{{% param "docker_ce_version" %}}-1~raspbian.12~bookworm + 5:{{% param "docker_ce_version_prev" %}}-1~raspbian.12~bookworm ... ``` Select the desired version and install: ```console - $ VERSION_STRING=5:27.1.1-1~raspbian.12~bookworm + $ VERSION_STRING=5:{{% param "docker_ce_version" %}}-1~raspbian.12~bookworm $ sudo apt-get install docker-ce=$VERSION_STRING docker-ce-cli=$VERSION_STRING containerd.io docker-buildx-plugin docker-compose-plugin ``` {{< /tab >}} {{< /tabs >}} -3. Verify that the installation is successful by running the `hello-world` - image: +3. Verify that the installation is successful by running the `hello-world` image: ```console $ sudo docker run hello-world @@ -214,8 +213,7 @@ download a new file each time you want to upgrade Docker Engine. The Docker daemon starts automatically. -6. Verify that the Docker Engine installation is successful by running the - `hello-world` image: +6. Verify that the installation is successful by running the `hello-world` image: ```console $ sudo service docker start @@ -238,19 +236,26 @@ To upgrade Docker Engine, download the newer package files and repeat the ## Uninstall Docker Engine -1. Uninstall the Docker Engine, CLI, containerd, and Docker Compose packages: +1. Uninstall the Docker Engine, CLI, containerd, and Docker Compose packages: - ```console - $ sudo apt-get purge docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin docker-ce-rootless-extras - ``` + ```console + $ sudo apt-get purge docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin docker-ce-rootless-extras + ``` + +2. Images, containers, volumes, or custom configuration files on your host + aren't automatically removed. To delete all images, containers, and volumes: + + ```console + $ sudo rm -rf /var/lib/docker + $ sudo rm -rf /var/lib/containerd + ``` -2. Images, containers, volumes, or custom configuration files on your host - aren't automatically removed. To delete all images, containers, and volumes: +3. Remove source list and keyrings - ```console - $ sudo rm -rf /var/lib/docker - $ sudo rm -rf /var/lib/containerd - ``` + ```console + $ sudo rm /etc/apt/sources.list.d/docker.list + $ sudo rm /etc/apt/keyrings/docker.asc + ``` You have to delete any edited configuration files manually. diff --git a/content/manuals/engine/install/rhel.md b/content/manuals/engine/install/rhel.md index 07a8fae2308..e0678357fc2 100644 --- a/content/manuals/engine/install/rhel.md +++ b/content/manuals/engine/install/rhel.md @@ -1,7 +1,7 @@ --- description: Learn how to install Docker Engine on RHEL. These instructions cover the different installation methods, how to uninstall, and next steps. -keywords: requirements, apt, installation, rhel, rpm, install, install docker engine, uninstall, upgrade, +keywords: requirements, dnf, installation, rhel, rpm, install, install docker engine, uninstall, upgrade, update title: Install Docker Engine on RHEL linkTitle: RHEL @@ -34,13 +34,14 @@ RHEL versions: ### Uninstall old versions -Older versions of Docker went by `docker` or `docker-engine`. -Uninstall any such older versions before attempting to install a new version, -along with associated dependencies. Also uninstall `Podman` and the associated -dependencies if installed already: +Before you can install Docker Engine, you need to uninstall any conflicting packages. + +Your Linux distribution may provide unofficial Docker packages, which may conflict +with the official packages provided by Docker. You must uninstall these packages +before you install the official version of Docker Engine. ```console -$ sudo yum remove docker \ +$ sudo dnf remove docker \ docker-client \ docker-client-latest \ docker-common \ @@ -52,7 +53,7 @@ $ sudo yum remove docker \ runc ``` -`yum` might report that you have none of these packages installed. +`dnf` might report that you have none of these packages installed. Images, containers, volumes, and networks stored in `/var/lib/docker/` aren't automatically removed when you uninstall Docker. @@ -82,17 +83,17 @@ Docker from the repository. #### Set up the repository -Install the `yum-utils` package (which provides the `yum-config-manager` -utility) and set up the repository. +Install the `dnf-plugins-core` package (which provides the commands to manage +your DNF repositories) and set up the repository. ```console -$ sudo yum install -y yum-utils -$ sudo yum-config-manager --add-repo {{% param "download-url-base" %}}/docker-ce.repo +$ sudo dnf -y install dnf-plugins-core +$ sudo dnf config-manager --add-repo {{% param "download-url-base" %}}/docker-ce.repo ``` #### Install Docker Engine -1. Install Docker Engine, containerd, and Docker Compose: +1. Install the Docker packages. {{< tabs >}} {{< tab name="Latest" >}} @@ -100,7 +101,7 @@ $ sudo yum-config-manager --add-repo {{% param "download-url-base" %}}/docker-ce To install the latest version, run: ```console - $ sudo yum install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin + $ sudo dnf install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin ``` If prompted to accept the GPG key, verify that the fingerprint matches @@ -116,10 +117,10 @@ $ sudo yum-config-manager --add-repo {{% param "download-url-base" %}}/docker-ce the repository: ```console - $ yum list docker-ce --showduplicates | sort -r + $ dnf list docker-ce --showduplicates | sort -r - docker-ce.x86_64 3:27.1.1-1.el9 docker-ce-stable - docker-ce.x86_64 3:27.1.0-1.el9 docker-ce-stable + docker-ce.x86_64 3:{{% param "docker_ce_version" %}}-1.el9 docker-ce-stable + docker-ce.x86_64 3:{{% param "docker_ce_version_prev" %}}-1.el9 docker-ce-stable <...> ``` @@ -128,13 +129,13 @@ $ sudo yum-config-manager --add-repo {{% param "download-url-base" %}}/docker-ce Install a specific version by its fully qualified package name, which is the package name (`docker-ce`) plus the version string (2nd column), - separated by a hyphen (`-`). For example, `docker-ce-3:27.1.1-1.el9`. + separated by a hyphen (`-`). For example, `docker-ce-3:{{% param "docker_ce_version" %}}-1.el9`. Replace `` with the desired version and then run the following command to install: ```console - $ sudo yum install docker-ce- docker-ce-cli- containerd.io docker-buildx-plugin docker-compose-plugin + $ sudo dnf install docker-ce- docker-ce-cli- containerd.io docker-buildx-plugin docker-compose-plugin ``` This command installs Docker, but it doesn't start Docker. It also creates a @@ -143,14 +144,17 @@ $ sudo yum-config-manager --add-repo {{% param "download-url-base" %}}/docker-ce {{< /tab >}} {{< /tabs >}} -2. Start Docker. +2. Start Docker Engine. ```console - $ sudo systemctl start docker + $ sudo systemctl enable --now docker ``` -3. Verify that the Docker Engine installation is successful by running the - `hello-world` image. + This configures the Docker systemd service to start automatically when you + boot your system. If you don't want Docker to start automatically, use `sudo + systemctl start docker` instead. + +3. Verify that the installation is successful by running the `hello-world` image: ```console $ sudo docker run hello-world @@ -195,7 +199,7 @@ download a new file each time you want to upgrade Docker Engine. the packages. ```console - $ sudo yum install ./containerd.io-..rpm \ + $ sudo dnf install ./containerd.io-..rpm \ ./docker-ce-..rpm \ ./docker-ce-cli-..rpm \ ./docker-buildx-plugin-..rpm \ @@ -205,14 +209,17 @@ download a new file each time you want to upgrade Docker Engine. Docker is installed but not started. The `docker` group is created, but no users are added to the group. -6. Start Docker. +6. Start Docker Engine. ```console - $ sudo systemctl start docker + $ sudo systemctl enable --now docker ``` -7. Verify that the Docker Engine installation is successful by running the - `hello-world` image. + This configures the Docker systemd service to start automatically when you + boot your system. If you don't want Docker to start automatically, use `sudo + systemctl start docker` instead. + +7. Verify that the installation is successful by running the `hello-world` image: ```console $ sudo docker run hello-world @@ -228,8 +235,8 @@ You have now successfully installed and started Docker Engine. #### Upgrade Docker Engine To upgrade Docker Engine, download the newer package files and repeat the -[installation procedure](#install-from-a-package), using `yum -y upgrade` -instead of `yum -y install`, and point to the new files. +[installation procedure](#install-from-a-package), using `dnf upgrade` +instead of `dnf install`, and point to the new files. {{< include "install-script.md" >}} @@ -238,7 +245,7 @@ instead of `yum -y install`, and point to the new files. 1. Uninstall the Docker Engine, CLI, containerd, and Docker Compose packages: ```console - $ sudo yum remove docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin docker-ce-rootless-extras + $ sudo dnf remove docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin docker-ce-rootless-extras ``` 2. Images, containers, volumes, or custom configuration files on your host diff --git a/content/manuals/engine/install/sles.md b/content/manuals/engine/install/sles.md index b0735454a2c..b148e60a1b1 100644 --- a/content/manuals/engine/install/sles.md +++ b/content/manuals/engine/install/sles.md @@ -58,9 +58,11 @@ $ sudo zypper addrepo $opensuse_repo ### Uninstall old versions -Older versions of Docker went by `docker` or `docker-engine`. -Uninstall any such older versions before attempting to install a new version, -along with associated dependencies. +Before you can install Docker Engine, you need to uninstall any conflicting packages. + +Your Linux distribution may provide unofficial Docker packages, which may conflict +with the official packages provided by Docker. You must uninstall these packages +before you install the official version of Docker Engine. ```console $ sudo zypper remove docker \ @@ -112,7 +114,7 @@ $ sudo zypper addrepo {{% param "download-url-base" %}}/docker-ce.repo #### Install Docker Engine -1. Install Docker Engine, containerd, and Docker Compose: +1. Install the Docker packages. {{< tabs >}} {{< tab name="Latest" >}} @@ -128,7 +130,7 @@ $ sudo zypper addrepo {{% param "download-url-base" %}}/docker-ce.repo This command installs Docker, but it doesn't start Docker. It also creates a `docker` group, however, it doesn't add any users to the group by default. - + {{< /tab >}} {{< tab name="Specific version" >}} @@ -138,8 +140,8 @@ $ sudo zypper addrepo {{% param "download-url-base" %}}/docker-ce.repo ```console $ sudo zypper search -s --match-exact docker-ce | sort -r - v | docker-ce | package | 3:27.0.3-1 | s390x | Docker CE Stable - s390x - v | docker-ce | package | 3:27.0.2-1 | s390x | Docker CE Stable - s390x + v | docker-ce | package | 3:{{% param "docker_ce_version" %}}-1 | s390x | Docker CE Stable - s390x + v | docker-ce | package | 3:{{% param "docker_ce_version_prev" %}}-1 | s390x | Docker CE Stable - s390x ``` The list returned depends on which repositories are enabled, and is specific @@ -147,7 +149,7 @@ $ sudo zypper addrepo {{% param "download-url-base" %}}/docker-ce.repo Install a specific version by its fully qualified package name, which is the package name (`docker-ce`) plus the version string (2nd column), - separated by a hyphen (`-`). For example, `docker-ce-3:27.0.3`. + separated by a hyphen (`-`). For example, `docker-ce-3:{{% param "docker_ce_version" %}}`. Replace `` with the desired version and then run the following command to install: @@ -162,14 +164,17 @@ $ sudo zypper addrepo {{% param "download-url-base" %}}/docker-ce.repo {{< /tab >}} {{< /tabs >}} -2. Start Docker. +2. Start Docker Engine. ```console - $ sudo systemctl start docker + $ sudo systemctl enable --now docker ``` -3. Verify that the Docker Engine installation is successful by running the - `hello-world` image. + This configures the Docker systemd service to start automatically when you + boot your system. If you don't want Docker to start automatically, use `sudo + systemctl start docker` instead. + +3. Verify that the installation is successful by running the `hello-world` image: ```console $ sudo docker run hello-world @@ -208,14 +213,17 @@ download a new file each time you want to upgrade Docker Engine. Docker is installed but not started. The `docker` group is created, but no users are added to the group. -3. Start Docker. +3. Start Docker Engine. ```console - $ sudo systemctl start docker + $ sudo systemctl enable --now docker ``` -4. Verify that the Docker Engine installation is successful by running the - `hello-world` image. + This configures the Docker systemd service to start automatically when you + boot your system. If you don't want Docker to start automatically, use `sudo + systemctl start docker` instead. + +4. Verify that the installation is successful by running the `hello-world` image: ```console $ sudo docker run hello-world diff --git a/content/manuals/engine/install/ubuntu.md b/content/manuals/engine/install/ubuntu.md index 295bc5c1f7c..ae89082b26d 100644 --- a/content/manuals/engine/install/ubuntu.md +++ b/content/manuals/engine/install/ubuntu.md @@ -50,6 +50,7 @@ To get started with Docker Engine on Ubuntu, make sure you To install Docker Engine, you need the 64-bit version of one of these Ubuntu versions: +- Ubuntu Oracular 24.10 - Ubuntu Noble 24.04 (LTS) - Ubuntu Jammy 22.04 (LTS) - Ubuntu Focal 20.04 (LTS) @@ -61,9 +62,9 @@ s390x, and ppc64le (ppc64el) architectures. Before you can install Docker Engine, you need to uninstall any conflicting packages. -Distro maintainers provide unofficial distributions of Docker packages in -APT. You must uninstall these packages before you can install the official -version of Docker Engine. +Your Linux distribution may provide unofficial Docker packages, which may conflict +with the official packages provided by Docker. You must uninstall these packages +before you install the official version of Docker Engine. The unofficial packages to uninstall are: @@ -96,7 +97,7 @@ clean installation, and prefer to clean up any existing data, read the You can install Docker Engine in different ways, depending on your needs: - Docker Engine comes bundled with - [Docker Desktop for Linux](/manuals/desktop/install/linux/_index.md). This is + [Docker Desktop for Linux](/manuals/desktop/setup/install/linux/_index.md). This is the easiest and quickest way to get started. - Set up and install Docker Engine from @@ -110,7 +111,7 @@ You can install Docker Engine in different ways, depending on your needs: ### Install using the `apt` repository {#install-using-the-repository} Before you install Docker Engine for the first time on a new host machine, you -need to set up the Docker repository. Afterward, you can install and update +need to set up the Docker `apt` repository. Afterward, you can install and update Docker from the repository. 1. Set up Docker's `apt` repository. @@ -122,7 +123,7 @@ Docker from the repository. sudo install -m 0755 -d /etc/apt/keyrings sudo curl -fsSL {{% param "download-url-base" %}}/gpg -o /etc/apt/keyrings/docker.asc sudo chmod a+r /etc/apt/keyrings/docker.asc - + # Add the repository to Apt sources: echo \ "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] {{% param "download-url-base" %}} \ @@ -133,7 +134,7 @@ Docker from the repository. > [!NOTE] > - > If you use an Ubuntu derivative distro, such as Linux Mint, + > If you use an Ubuntu derivative distribution, such as Linux Mint, > you may need to use `UBUNTU_CODENAME` instead of `VERSION_CODENAME`. 2. Install the Docker packages. @@ -157,23 +158,22 @@ Docker from the repository. # List the available versions: $ apt-cache madison docker-ce | awk '{ print $3 }' - 5:27.1.1-1~ubuntu.24.04~noble - 5:27.1.0-1~ubuntu.24.04~noble + 5:{{% param "docker_ce_version" %}}-1~ubuntu.24.04~noble + 5:{{% param "docker_ce_version_prev" %}}-1~ubuntu.24.04~noble ... ``` Select the desired version and install: ```console - $ VERSION_STRING=5:27.1.1-1~ubuntu.24.04~noble + $ VERSION_STRING=5:{{% param "docker_ce_version" %}}-1~ubuntu.24.04~noble $ sudo apt-get install docker-ce=$VERSION_STRING docker-ce-cli=$VERSION_STRING containerd.io docker-buildx-plugin docker-compose-plugin ``` - + {{< /tab >}} {{< /tabs >}} -3. Verify that the Docker Engine installation is successful by running the - `hello-world` image. +3. Verify that the installation is successful by running the `hello-world` image: ```console $ sudo docker run hello-world @@ -228,8 +228,7 @@ download a new file each time you want to upgrade Docker Engine. The Docker daemon starts automatically. -6. Verify that the Docker Engine installation is successful by running the - `hello-world` image. +6. Verify that the installation is successful by running the `hello-world` image: ```console $ sudo service docker start @@ -266,6 +265,13 @@ To upgrade Docker Engine, download the newer package files and repeat the $ sudo rm -rf /var/lib/containerd ``` +3. Remove source list and keyrings + + ```console + $ sudo rm /etc/apt/sources.list.d/docker.list + $ sudo rm /etc/apt/keyrings/docker.asc + ``` + You have to delete any edited configuration files manually. ## Next steps diff --git a/content/manuals/engine/logging/configure.md b/content/manuals/engine/logging/configure.md index 0febf718be8..fa7801fb794 100644 --- a/content/manuals/engine/logging/configure.md +++ b/content/manuals/engine/logging/configure.md @@ -22,9 +22,9 @@ As a default, Docker uses the [`json-file` logging driver](drivers/json-file.md) caches container logs as JSON internally. In addition to using the logging drivers included with Docker, you can also implement and use [logging driver plugins](plugins.md). -> **Tip: use the `local` logging driver to prevent disk-exhaustion** +> [!TIP] > -> By default, no log-rotation is performed. As a result, log-files stored by the +> Use the `local` logging driver to prevent disk-exhaustion. By default, no log-rotation is performed. As a result, log-files stored by the > default [`json-file` logging driver](drivers/json-file.md) logging driver can cause > a significant amount of disk space to be used for containers that generate much > output, which can lead to disk space exhaustion. diff --git a/content/manuals/engine/network/links.md b/content/manuals/engine/network/links.md index 99eb5a87ab8..0f97ccd40ab 100644 --- a/content/manuals/engine/network/links.md +++ b/content/manuals/engine/network/links.md @@ -9,9 +9,9 @@ aliases: - /network/links/ --- ->**Warning** -> ->The `--link` flag is a legacy feature of Docker. It may eventually +> [!WARNING] +> +> The `--link` flag is a legacy feature of Docker. It may eventually be removed. Unless you absolutely need to continue using it, we recommend that you use user-defined networks to facilitate communication between two containers instead of using `--link`. One feature that user-defined networks do not support that you can do diff --git a/content/manuals/engine/release-notes/17.03.md b/content/manuals/engine/release-notes/17.03.md index cd536ee0c55..9c59a30ba57 100644 --- a/content/manuals/engine/release-notes/17.03.md +++ b/content/manuals/engine/release-notes/17.03.md @@ -71,13 +71,9 @@ toc_max: 2 ## 17.03.0-ce 2017-03-01 -**IMPORTANT**: Starting with this release, Docker is on a monthly release cycle and uses a -new YY.MM versioning scheme to reflect this. Two channels are available: monthly and quarterly. -Any given monthly release will only receive security and bugfixes until the next monthly -release is available. Quarterly releases receive security and bugfixes for 4 months after -initial release. This release includes bugfixes for 1.13.1 but -there are no major feature additions and the API version stays the same. -Upgrading from Docker 1.13.1 to 17.03.0 is expected to be simple and low-risk. +> [!IMPORTANT] +> +> Starting with this release, Docker is on a monthly release cycle and uses a new YY.MM versioning scheme to reflect this. Two channels are available: monthly and quarterly. Any given monthly release will only receive security and bugfixes until the next monthly release is available. Quarterly releases receive security and bugfixes for 4 months after initial release. This release includes bugfixes for 1.13.1 but there are no major feature additions and the API version stays the same. Upgrading from Docker 1.13.1 to 17.03.0 is expected to be simple and low-risk. ### Client diff --git a/content/manuals/engine/release-notes/18.09.md b/content/manuals/engine/release-notes/18.09.md index 535bcc3ad62..b01c055012d 100644 --- a/content/manuals/engine/release-notes/18.09.md +++ b/content/manuals/engine/release-notes/18.09.md @@ -16,7 +16,7 @@ toc_max: 2 > ``` > > See the [installation instructions](../install/_index.md) for the corresponding -> Linux distro for details. +> Linux distribution for details. ## 18.09.9 2019-09-03 diff --git a/content/manuals/engine/release-notes/20.10.md b/content/manuals/engine/release-notes/20.10.md index 2e93cc8e772..15453343fd8 100644 --- a/content/manuals/engine/release-notes/20.10.md +++ b/content/manuals/engine/release-notes/20.10.md @@ -50,7 +50,7 @@ Docker Buildx, containerd, and some minor bug fixes and enhancements. - Update Docker Compose to [v2.15.1](https://github.com/docker/compose/releases/tag/v2.15.1). - Update Docker Buildx to [v0.10.0](https://github.com/docker/buildx/releases/tag/v0.10.0). - Update containerd (`containerd.io` package) to [v1.6.15](https://github.com/containerd/containerd/releases/tag/v1.6.15). -- Update the package versioning format for `docker-compose-cli` to allow distro version updates [docker/docker-ce-packaging#822](https://github.com/docker/docker-ce-packaging/pull/822). +- Update the package versioning format for `docker-compose-cli` to allow distribution version updates [docker/docker-ce-packaging#822](https://github.com/docker/docker-ce-packaging/pull/822). - Update Go runtime to [1.18.10](https://go.dev/doc/devel/release#go1.18.minor), ### Bug fixes and enhancements @@ -365,13 +365,13 @@ the latest version. Use the instructions below to update `docker scan` to the la version. You can also use these instructions to install, or upgrade the `docker scan` package without upgrading the Docker Engine: -On `.deb` based distros, such as Ubuntu and Debian: +On `.deb` based distributions, such as Ubuntu and Debian: ```console $ apt-get update && apt-get install docker-scan-plugin ``` -On rpm-based distros, such as CentOS or Fedora: +On rpm-based distributions, such as CentOS or Fedora: ```console $ yum install docker-scan-plugin @@ -399,15 +399,9 @@ to learn how to use the `docker scan` command to check if images are vulnerable. ## 20.10.11 2021-11-17 -> **IMPORTANT** +> [!IMPORTANT] > -> Due to [net/http changes](https://github.com/golang/go/issues/40909) in [Go 1.16](https://golang.org/doc/go1.16#net/http), -> HTTP proxies configured through the `$HTTP_PROXY` environment variable are no -> longer used for TLS (`https://`) connections. Make sure you also set an `$HTTPS_PROXY` -> environment variable for handling requests to `https://` URLs. -> -> Refer to [Configure the daemon to use a proxy](/manuals/engine/daemon/proxy.md) -> to learn how to configure the Docker Daemon to use a proxy server. +> Due to [net/http changes](https://github.com/golang/go/issues/40909) in [Go 1.16](https://golang.org/doc/go1.16#net/http), HTTP proxies configured through the `$HTTP_PROXY` environment variable are no longer used for TLS (`https://`) connections. Make sure you also set an `$HTTPS_PROXY` environment variable for handling requests to `https://` URLs. Refer to [Configure the daemon to use a proxy](/manuals/engine/daemon/proxy.md) to learn how to configure the Docker Daemon to use a proxy server. ### Distribution @@ -428,15 +422,9 @@ to learn how to use the `docker scan` command to check if images are vulnerable. ## 20.10.10 2021-10-25 -> **IMPORTANT** -> -> Due to [net/http changes](https://github.com/golang/go/issues/40909) in [Go 1.16](https://golang.org/doc/go1.16#net/http), -> HTTP proxies configured through the `$HTTP_PROXY` environment variable are no -> longer used for TLS (`https://`) connections. Make sure you also set an `$HTTPS_PROXY` -> environment variable for handling requests to `https://` URLs. +> [!IMPORTANT] > -> Refer to the [HTTP/HTTPS proxy section](/manuals/engine/daemon/proxy.md) -> to learn how to configure the Docker Daemon to use a proxy server. +> Due to [net/http changes](https://github.com/golang/go/issues/40909) in [Go 1.16](https://golang.org/doc/go1.16#net/http), HTTP proxies configured through the `$HTTP_PROXY` environment variable are no longer used for TLS (`https://`) connections. Make sure you also set an `$HTTPS_PROXY` environment variable for handling requests to `https://` URLs. Refer to the [HTTP/HTTPS proxy section](/manuals/engine/daemon/proxy.md) to learn how to configure the Docker Daemon to use a proxy server. ### Builder @@ -468,15 +456,9 @@ to learn how to use the `docker scan` command to check if images are vulnerable. This release is a security release with security fixes in the CLI, runtime, as well as updated versions of the containerd.io package. -> **IMPORTANT** +> [!IMPORTANT] > -> Due to [net/http changes](https://github.com/golang/go/issues/40909) in [Go 1.16](https://golang.org/doc/go1.16#net/http), -> HTTP proxies configured through the `$HTTP_PROXY` environment variable are no -> longer used for TLS (`https://`) connections. Make sure you also set an `$HTTPS_PROXY` -> environment variable for handling requests to `https://` URLs. -> -> Refer to the [HTTP/HTTPS proxy section](/manuals/engine/daemon/proxy.md) -> to learn how to configure the Docker Daemon to use a proxy server. +> Due to [net/http changes](https://github.com/golang/go/issues/40909) in [Go 1.16](https://golang.org/doc/go1.16#net/http), HTTP proxies configured through the `$HTTP_PROXY` environment variable are no longer used for TLS (`https://`) connections. Make sure you also set an `$HTTPS_PROXY` environment variable for handling requests to `https://` URLs. Refer to the [HTTP/HTTPS proxy section](/manuals/engine/daemon/proxy.md) to learn how to configure the Docker Daemon to use a proxy server. ### Client @@ -512,15 +494,9 @@ well as updated versions of the containerd.io package. ## 20.10.8 2021-08-03 -> **IMPORTANT** -> -> Due to [net/http changes](https://github.com/golang/go/issues/40909) in [Go 1.16](https://golang.org/doc/go1.16#net/http), -> HTTP proxies configured through the `$HTTP_PROXY` environment variable are no -> longer used for TLS (`https://`) connections. Make sure you also set an `$HTTPS_PROXY` -> environment variable for handling requests to `https://` URLs. +> [!IMPORTANT] > -> Refer to the [HTTP/HTTPS proxy section](/manuals/engine/daemon/proxy.md) -> to learn how to configure the Docker Daemon to use a proxy server. +> Due to [net/http changes](https://github.com/golang/go/issues/40909) in [Go 1.16](https://golang.org/doc/go1.16#net/http), HTTP proxies configured through the `$HTTP_PROXY` environment variable are no longer used for TLS (`https://`) connections. Make sure you also set an `$HTTPS_PROXY` environment variable for handling requests to `https://` URLs. Refer to the [HTTP/HTTPS proxy section](/manuals/engine/daemon/proxy.md) to learn how to configure the Docker Daemon to use a proxy server. ### Deprecation diff --git a/content/manuals/engine/release-notes/24.0.md b/content/manuals/engine/release-notes/24.0.md index 4b578ce473f..afd7c4ba4cf 100644 --- a/content/manuals/engine/release-notes/24.0.md +++ b/content/manuals/engine/release-notes/24.0.md @@ -312,7 +312,7 @@ For a full list of pull requests and changes in this release, refer to the relev * The `docker info` CLI command now reports a version and platform field. [docker/cli#4180](https://github.com/docker/cli/pull/4180) * Introduce the daemon flag `--default-network-opt` to configure options for newly created networks. [moby/moby#43197](https://github.com/moby/moby/pull/43197) * Restrict access to `AF_VSOCK` in the `socket(2)` family of syscalls in the default seccomp profile. [moby/moby#44562](https://github.com/moby/moby/pull/44562) -* Introduce support for setting OCI runtime annotations on containers. [docker/cli#45025](https://github.com/docker/cli/pull/4156), [moby/moby#45025](https://github.com/moby/moby/pull/45025) +* Introduce support for setting OCI runtime annotations on containers. [docker/cli#4156](https://github.com/docker/cli/pull/4156), [moby/moby#45025](https://github.com/moby/moby/pull/45025) * Alternative runtimes can now be configured in `daemon.json`, enabling runtime names to be aliased and options to be passed. [moby/moby#45032](https://github.com/moby/moby/pull/45032) * The `docker-init` binary will now be discovered in FHS-compliant libexec directories, in addition to the `PATH`. [moby/moby#45198](https://github.com/moby/moby/pull/45198) * API: Surface the daemon-level `--no-new-privileges` in `GET /info`. [moby/moby#45320](https://github.com/moby/moby/pull/45320) diff --git a/content/manuals/engine/release-notes/25.0.md b/content/manuals/engine/release-notes/25.0.md index c3d28ae5d05..d000b7ab9c7 100644 --- a/content/manuals/engine/release-notes/25.0.md +++ b/content/manuals/engine/release-notes/25.0.md @@ -94,7 +94,7 @@ For a full list of pull requests and changes in this release, refer to the relev - Fix a bug where the value of the `ipv6` daemon option was ignored. [moby/moby#47310](https://github.com/moby/moby/pull/47310) - Fix a bug where trying to install a pulling using a digest revision would cause a panic. [moby/moby#47323](https://github.com/moby/moby/pull/47323) - Fix a potential race condition in the managed containerd supervisor. [moby/moby#47313](https://github.com/moby/moby/pull/47313) -- Fix an issue with the `journald` log driver preventing container logs from being followed correctly with systemd version 255. [moby/moby47243](https://github.com/moby/moby/pull/47243) +- Fix an issue with the `journald` log driver preventing container logs from being followed correctly with systemd version 255. [moby/moby#47243](https://github.com/moby/moby/pull/47243) - seccomp: Update the builtin seccomp profile to include syscalls added in kernel v5.17 - v6.7 to align the profile with the profile used by containerd. [moby/moby#47341](https://github.com/moby/moby/pull/47341) - Windows: Fix cache not being used when building images based on Windows versions older than the host's version. [moby/moby#47307](https://github.com/moby/moby/pull/47307), [moby/moby#47337](https://github.com/moby/moby/pull/47337) diff --git a/content/manuals/engine/release-notes/27.md b/content/manuals/engine/release-notes/27.md index 3143c0d2aea..7e2fe362696 100644 --- a/content/manuals/engine/release-notes/27.md +++ b/content/manuals/engine/release-notes/27.md @@ -23,6 +23,99 @@ For more information about: - Deprecated and removed features, see [Deprecated Engine Features](../deprecated.md). - Changes to the Engine API, see [Engine API version history](/reference/api/engine/version-history.md). +## 27.4 + +Release notes for Docker Engine version 27.4 releases. + +### 27.4.1 + +{{< release-date date="2024-12-18" >}} + +For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones: + +- [docker/cli, 27.4.1 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A27.4.1) +- [moby/moby, 27.4.1 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A27.4.1) + +#### Bug fixes and enhancements + +- Fix excessive memory allocations when OTel is not configured. [moby/moby#49079](https://github.com/moby/moby/pull/49079) +- The `docker info` command and the corresponding `GET /info` API endpoint no longer include warnings when `bridge-nf-call-iptables` or `bridge-nf-call-ip6tables` are disabled at the daemon is started. The `br_netfilter` kernel module is now attempted to be loaded when needed, which made those warnings inaccurate. [moby/moby#49090](https://github.com/moby/moby/pull/49090) +- Attempt to load kernel modules, including `ip6_tables` and `br_netfilter` when required, using a method that is likely to succeed inside a Docker-in-Docker container. [moby/moby#49043](https://github.com/moby/moby/pull/49043) +- Fix a bug that could result in an iptables `DOCKER FILTER` chain not being cleaned up on failure. [moby/moby#49110](https://github.com/moby/moby/pull/49110) + +#### Packaging updates + +- Update Compose to [v2.32.1](https://github.com/docker/compose/releases/tag/v2.32.1). [docker/docker-ce-packaging#1130](https://github.com/docker/docker-ce-packaging/pull/1130) +- Update Buildx to [v0.19.3](https://github.com/docker/buildx/releases/tag/v0.19.3). [docker/docker-ce-packaging#1132](https://github.com/docker/docker-ce-packaging/pull/1132) +- Update runc (static binaries only) to [v1.2.3](https://github.com/opencontainers/runc/releases/tag/v1.2.3) [moby/moby#49085](https://github.com/moby/moby/pull/49085) + +### 27.4.0 + +{{< release-date date="2024-12-09" >}} + + +For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones: + +- [docker/cli, 27.4.0 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A27.4.0) +- [moby/moby, 27.4.0 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A27.4.0) + +#### API + +- `GET /images/json` with the `manifests` option enabled now preserves the original order in which manifests appeared in the manifest-index. [moby/moby#48712](https://github.com/moby/moby/pull/48712) + +#### Bug fixes and enhancements + +- When reading logs with the `jsonfile` or `local` log drivers, any errors while trying to read or parse underlying log files will cause the rest of the file to be skipped and move to the next log file (if one exists) rather than returning an error to the client and closing the stream. The errors are viewable in the Docker Daemon logs and exported to traces when tracing is configured. [moby/moby#48842](https://github.com/moby/moby/pull/48842) +- When reading log files, compressed log files are now only decompressed when needed rather than decompressing all files before starting the log stream. [moby/moby#48842](https://github.com/moby/moby/pull/48842) +- Fix an issue that meant published ports from one container on a bridge network were not accessible from another container on the same network with `userland-proxy` disabled, if the kernel's `br_netfilter` module was not loaded and enabled. The daemon will now attempt to load the module and enable `bridge-nf-call-iptables` or `bridge-nf-call-ip6tables` when creating a network with the userland proxy disabled. [moby/moby#48685](https://github.com/moby/moby/pull/48685) +- Fix loading of `bridge` and `br_netfilter` kernel modules. [moby/moby#48966](https://github.com/moby/moby/pull/48966) +- containerd image store: Fix Docker daemon failing to fully start with a "context deadline exceeded error" with containerd snapshotter and many builds/images. [moby/moby#48954](https://github.com/moby/moby/pull/48954) +- containerd image store: Fix partially pulled images not being garbage-collected. [moby#48910](https://github.com/moby/moby/pull/48910), [moby/moby#48957](https://github.com/moby/moby/pull/48957) +- containerd image store: Fix `docker image inspect` outputting duplicate references in `RepoDigests`. [moby/moby#48785](https://github.com/moby/moby/pull/48785) +- containerd image store: Fix not being able to connect to some insecure registries in cases where the HTTPS request failed due to a non-TLS related error. [moby/moby#48758](https://github.com/moby/moby/pull/48758) +- containerd image store: Remove a confusing warning log when tagging a non-dangling image. [moby/moby#49010](https://github.com/moby/moby/pull/49010) +- containerd image store: Do not underline names in `docker image ls --tree`. [docker/cli#5519](https://github.com/docker/cli/pull/5519) +- containerd image store: Change name of `USED` column in `docker image ls --tree` to `IN USE`. [docker/cli#5518](https://github.com/docker/cli/pull/5518) +- `dockerd-rootless-setuptool.sh install --force` now ignores RootlessKit errors [moby/moby#48695](https://github.com/moby/moby/pull/48695) +- Disable IPv6 Duplicate Address Detection (DAD) for addresses assigned to the bridges belonging to bridge networks. [moby/moby#48684](https://github.com/moby/moby/pull/48684) +- Remove BuildKit init timeout. [moby/moby#48963](https://github.com/moby/moby/pull/48963) +- Ignore "dataset does not exist" error when removing dataset on ZFS. [moby/moby#48968](https://github.com/moby/moby/pull/48968) +- Client: Prevent idle connections leaking FDs. [moby/moby#48764](https://github.com/moby/moby/pull/48764) +- Fix anonymous volumes being created through the `--mount` option not being marked as anonymous. [moby/moby#48755](https://github.com/moby/moby/pull/48755) +- After a daemon restart with live-restore, ensure an iptables jump to the `DOCKER-USER` chain is placed before other rules. [moby/moby#48714](https://github.com/moby/moby/pull/48714) +- Fix a possible memory leak caused by OTel meters. [moby/moby#48693](https://github.com/moby/moby/pull/48693) +- Create distinct build history db for each image store. [moby/moby#48688](https://github.com/moby/moby/pull/48688) +- Fix an issue that caused excessive memory usage when DNS resolution was made in a tight loop. [moby/moby#48840](https://github.com/moby/moby/pull/48840) +- Fix a bug preventing image pulls from being cancelled during `docker run`. [docker/cli#5654](https://github.com/docker/cli/pull/5654) +- The `docker login` and `docker logout` command no longer update the configuration file if the credentials didn't change. [docker/cli#5569](https://github.com/docker/cli/pull/5569) +- Optimize `docker stats` to reduce flickering issues. [docker/cli#5588](https://github.com/docker/cli/pull/5588), [docker/cli#5635](https://github.com/docker/cli/pull/5635) +- Fix inaccessible plugins paths preventing plugins from being detected. [docker/cli#5652](https://github.com/docker/cli/pull/5652) +- Add support for `events --filter` in cobra generated shell completions. [docker/cli#5614](https://github.com/docker/cli/pull/5614) +- Fix bash completion for `events --filter daemon=`. [docker/cli#5563](https://github.com/docker/cli/pull/5563) +- Improve shell completion of containers for `docker rm`. [docker/cli#5540](https://github.com/docker/cli/pull/5540) +- Add shell completion for `--platform` flags. [docker/cli#5540](https://github.com/docker/cli/pull/5540) +- rootless: Make `/etc/cdi` and `/var/run/cdi` accessible by the Container Device Interface (CDI) integration. [moby/moby#49027](https://github.com/moby/moby/pull/49027) + +#### Removed + +- Deprecate `Daemon.Exists()` and `Daemon.IsPaused()`. These functions are no longer used and will be removed in the next release. [moby/moby#48719](https://github.com/moby/moby/pull/48719) +- Deprecate `container.ErrNameReserved` and `container.ErrNameNotReserved`. [moby/moby#48697](https://github.com/moby/moby/pull/48697) +- Deprecate `pkg/platform` - this package is only used internally, and will be removed in the next release. [moby/moby#48863](https://github.com/moby/moby/pull/48863) +- Deprecate `RepositoryInfo.Class`. This field is no longer used, and will be removed in the next release. [moby/moby#49013](https://github.com/moby/moby/pull/49013) +- Go SDK: Fix deprecation of `cli/command.ConfigureAuth()`, which was deprecated since v27.2.1. [docker/cli#5552](https://github.com/docker/cli/pull/5552) +- Go SDK: Deprecate `cli.Errors` type in favour of Go's `errors.Join` [docker/cli#5548](https://github.com/docker/cli/pull/5548) + +#### Packaging updates + +- Update Go runtime to 1.22.10. [moby/moby#49026](https://github.com/moby/moby/pull/49026), [docker/cli#5669](https://github.com/docker/cli/pull/5669), [docker/docker-ce-packaging#1120](https://github.com/docker/docker-ce-packaging/pull/1120). +- Update Compose to [v2.31.0](https://github.com/docker/compose/releases/tag/v2.31.0). [docker/docker-ce-packaging#1100](https://github.com/docker/docker-ce-packaging/pull/1117) +- Update BuildKit to [v0.17.3](https://github.com/moby/buildkit/releases/tag/v0.17.3). [moby/moby#49024](https://github.com/moby/moby/pull/49024) +- Update Buildx to [v0.19.1](https://github.com/docker/buildx/releases/tag/v0.19.1). [docker/docker-ce-packaging#1115](https://github.com/docker/docker-ce-packaging/pull/1115) +- Update containerd to [v1.7.24](https://github.com/containerd/containerd/releases/tag/v1.7.24). [moby/moby#48934](https://github.com/moby/moby/pull/48934) +- Update containerd (static binaries only) to [v1.7.24](https://github.com/containerd/containerd/releases/tag/v1.7.24). [moby/moby#48919](https://github.com/moby/moby/pull/48919) +- Update runc to [v1.2.2](https://github.com/opencontainers/runc/releases/tag/v1.2.2). [moby/moby#48919](https://github.com/moby/moby/pull/48919) + + ## 27.3 Release notes for Docker Engine version 27.3 releases. diff --git a/content/manuals/engine/release-notes/prior-releases.md b/content/manuals/engine/release-notes/prior-releases.md index 5ed930e7f62..ffe5dac7966 100644 --- a/content/manuals/engine/release-notes/prior-releases.md +++ b/content/manuals/engine/release-notes/prior-releases.md @@ -16,15 +16,13 @@ aliases: ## 1.13.1 (2017-02-08) -**Important**: On Linux distributions where `devicemapper` was the default storage driver, -the `overlay2`, or `overlay` is now used by default (if the kernel supports it). -To use devicemapper, you can manually configure the storage driver to use through -the `--storage-driver` daemon option, or by setting "storage-driver" in the `daemon.json` -configuration file. +> [!IMPORTANT] +> +> On Linux distributions where `devicemapper` was the default storage driver, the `overlay2`, or `overlay` is now used by default (if the kernel supports it). To use devicemapper, you can manually configure the storage driver to use through the `--storage-driver` daemon option, or by setting "storage-driver" in the `daemon.json` configuration file. -**Important**: In Docker 1.13, the managed plugin api changed, as compared to the experimental -version introduced in Docker 1.12. You must **uninstall** plugins which you installed with Docker 1.12 -_before_ upgrading to Docker 1.13. You can uninstall plugins using the `docker plugin rm` command. +> [!IMPORTANT] +> +> In Docker 1.13, the managed plugin api changed, as compared to the experimental version introduced in Docker 1.12. You must **uninstall** plugins which you installed with Docker 1.12 _before_ upgrading to Docker 1.13. You can uninstall plugins using the `docker plugin rm` command. If you have already upgraded to Docker 1.13 without uninstalling previously-installed plugins, you may see this message when the Docker daemon @@ -66,15 +64,13 @@ To manually remove all plugins and resolve this problem, take the following step ## 1.13.0 (2017-01-18) -**Important**: On Linux distributions where `devicemapper` was the default storage driver, -the `overlay2`, or `overlay` is now used by default (if the kernel supports it). -To use devicemapper, you can manually configure the storage driver to use through -the `--storage-driver` daemon option, or by setting "storage-driver" in the `daemon.json` -configuration file. +> [!IMPORTANT] +> +> On Linux distributions where `devicemapper` was the default storage driver, the `overlay2`, or `overlay` is now used by default (if the kernel supports it). To use devicemapper, you can manually configure the storage driver to use through the `--storage-driver` daemon option, or by setting "storage-driver" in the `daemon.json` configuration file. -**Important**: In Docker 1.13, the managed plugin api changed, as compared to the experimental -version introduced in Docker 1.12. You must **uninstall** plugins which you installed with Docker 1.12 -_before_ upgrading to Docker 1.13. You can uninstall plugins using the `docker plugin rm` command. +> [!IMPORTANT] +> +> In Docker 1.13, the managed plugin api changed, as compared to the experimental version introduced in Docker 1.12. You must **uninstall** plugins which you installed with Docker 1.12 _before_ upgrading to Docker 1.13. You can uninstall plugins using the `docker plugin rm` command. If you have already upgraded to Docker 1.13 without uninstalling previously-installed plugins, you may see this message when the Docker daemon @@ -299,16 +295,14 @@ To manually remove all plugins and resolve this problem, take the following step ## 1.12.6 (2017-01-10) -**IMPORTANT**: Docker 1.12 ships with an updated systemd unit file for rpm -based installs (which includes RHEL, Fedora, CentOS, and Oracle Linux 7). When -upgrading from an older version of docker, the upgrade process may not -automatically install the updated version of the unit file, or fail to start -the docker service if; +> [!IMPORTANT] +> +> Docker 1.12 ships with an updated systemd unit file for rpm +based installs (which includes RHEL, Fedora, CentOS, and Oracle Linux 7). When upgrading from an older version of Docker, the upgrade process may not automatically install the updated version of the unit file, or fail to start the `docker service` if; +> - the systemd unit file (`/usr/lib/systemd/system/docker.service`) contains local changes, or +> - a systemd drop-in file is present, and contains `-H fd://` in the `ExecStart` directive -- the systemd unit file (`/usr/lib/systemd/system/docker.service`) contains local changes, or -- a systemd drop-in file is present, and contains `-H fd://` in the `ExecStart` directive - -Starting the docker service will produce an error: +Starting the `docker service` will produce an error: Failed to start docker.service: Unit docker.socket failed to load: No such file or directory. @@ -326,8 +320,9 @@ To resolve this: After making those changes, run `sudo systemctl daemon-reload`, and `sudo systemctl restart docker` to reload changes and (re)start the docker daemon. -**NOTE**: Docker 1.12.5 will correctly validate that either an IPv6 subnet is provided or -that the IPAM driver can provide one when you specify the `--ipv6` option. +> [!NOTE] +> +> Docker 1.12.5 will correctly validate that either an IPv6 subnet is provided or that the IPAM driver can provide one when you specify the `--ipv6` option. If you are currently using the `--ipv6` option _without_ specifying the `--fixed-cidr-v6` option, the Docker daemon will refuse to start with the @@ -369,16 +364,14 @@ which supports automatic allocation of IPv6 subnets. ## 1.12.5 (2016-12-15) -**IMPORTANT**: Docker 1.12 ships with an updated systemd unit file for rpm -based installs (which includes RHEL, Fedora, CentOS, and Oracle Linux 7). When -upgrading from an older version of docker, the upgrade process may not -automatically install the updated version of the unit file, or fail to start -the docker service if; - -- the systemd unit file (`/usr/lib/systemd/system/docker.service`) contains local changes, or -- a systemd drop-in file is present, and contains `-H fd://` in the `ExecStart` directive +> [!IMPORTANT] +> +> Docker 1.12 ships with an updated systemd unit file for rpm +based installs (which includes RHEL, Fedora, CentOS, and Oracle Linux 7). When upgrading from an older version of Docker, the upgrade process may not automatically install the updated version of the unit file, or fail to start the `docker service` if; +> - the systemd unit file (`/usr/lib/systemd/system/docker.service`) contains local changes, or +> - a systemd drop-in file is present, and contains `-H fd://` in the `ExecStart` directive -Starting the docker service will produce an error: +Starting the `docker service` will produce an error: Failed to start docker.service: Unit docker.socket failed to load: No such file or directory. @@ -396,8 +389,9 @@ To resolve this: After making those changes, run `sudo systemctl daemon-reload`, and `sudo systemctl restart docker` to reload changes and (re)start the docker daemon. -**NOTE**: Docker 1.12.5 will correctly validate that either an IPv6 subnet is provided or -that the IPAM driver can provide one when you specify the `--ipv6` option. +> [!NOTE] +> +> Docker 1.12.5 will correctly validate that either an IPv6 subnet is provided or that the IPAM driver can provide one when you specify the `--ipv6` option. If you are currently using the `--ipv6` option _without_ specifying the `--fixed-cidr-v6` option, the Docker daemon will refuse to start with the @@ -447,16 +441,14 @@ which supports automatic allocation of IPv6 subnets. ## 1.12.4 (2016-12-12) -**IMPORTANT**: Docker 1.12 ships with an updated systemd unit file for rpm -based installs (which includes RHEL, Fedora, CentOS, and Oracle Linux 7). When -upgrading from an older version of docker, the upgrade process may not -automatically install the updated version of the unit file, or fail to start -the docker service if; +> [!IMPORTANT] +> +> Docker 1.12 ships with an updated systemd unit file for rpm +based installs (which includes RHEL, Fedora, CentOS, and Oracle Linux 7). When upgrading from an older version of Docker, the upgrade process may not automatically install the updated version of the unit file, or fail to start the `docker service` if; +> - the systemd unit file (`/usr/lib/systemd/system/docker.service`) contains local changes, or +> - a systemd drop-in file is present, and contains `-H fd://` in the `ExecStart` directive -- the systemd unit file (`/usr/lib/systemd/system/docker.service`) contains local changes, or -- a systemd drop-in file is present, and contains `-H fd://` in the `ExecStart` directive - -Starting the docker service will produce an error: +Starting the `docker service` will produce an error: Failed to start docker.service: Unit docker.socket failed to load: No such file or directory. @@ -518,20 +510,18 @@ systemctl restart docker` to reload changes and (re)start the docker daemon. - Run "dnf upgrade" before installing in fedora [#29150](https://github.com/docker/docker/pull/29150) - Add build-date back to RPM packages [#29150](https://github.com/docker/docker/pull/29150) -- deb package filename changed to include distro to distinguish between distro code names [#27829](https://github.com/docker/docker/pull/27829) +- deb package filename changed to include distribution to distinguish between distribution code names [#27829](https://github.com/docker/docker/pull/27829) ## 1.12.3 (2016-10-26) -**IMPORTANT**: Docker 1.12 ships with an updated systemd unit file for rpm -based installs (which includes RHEL, Fedora, CentOS, and Oracle Linux 7). When -upgrading from an older version of docker, the upgrade process may not -automatically install the updated version of the unit file, or fail to start -the docker service if; - -- the systemd unit file (`/usr/lib/systemd/system/docker.service`) contains local changes, or -- a systemd drop-in file is present, and contains `-H fd://` in the `ExecStart` directive +> [!IMPORTANT] +> +> Docker 1.12 ships with an updated systemd unit file for rpm +based installs (which includes RHEL, Fedora, CentOS, and Oracle Linux 7). When upgrading from an older version of Docker, the upgrade process may not automatically install the updated version of the unit file, or fail to start the Docker service if; +> - the systemd unit file (`/usr/lib/systemd/system/docker.service`) contains local changes, or +> - a systemd drop-in file is present, and contains `-H fd://` in the `ExecStart` directive -Starting the docker service will produce an error: +Starting the `docker service` will produce an error: Failed to start docker.service: Unit docker.socket failed to load: No such file or directory. @@ -589,16 +579,14 @@ systemctl restart docker` to reload changes and (re)start the docker daemon. ## 1.12.2 (2016-10-11) -**IMPORTANT**: Docker 1.12 ships with an updated systemd unit file for rpm -based installs (which includes RHEL, Fedora, CentOS, and Oracle Linux 7). When -upgrading from an older version of docker, the upgrade process may not -automatically install the updated version of the unit file, or fail to start -the docker service if; +> [!IMPORTANT] +> +> Docker 1.12 ships with an updated systemd unit file for rpm +based installs (which includes RHEL, Fedora, CentOS, and Oracle Linux 7). When upgrading from an older version of Docker, the upgrade process may not automatically install the updated version of the unit file, or fail to start the `docker service` if; +> - the systemd unit file (`/usr/lib/systemd/system/docker.service`) contains local changes, or +> - a systemd drop-in file is present, and contains `-H fd://` in the `ExecStart` directive -- the systemd unit file (`/usr/lib/systemd/system/docker.service`) contains local changes, or -- a systemd drop-in file is present, and contains `-H fd://` in the `ExecStart` directive - -Starting the docker service will produce an error: +Starting the `docker service` will produce an error: Failed to start docker.service: Unit docker.socket failed to load: No such file or directory. @@ -663,16 +651,14 @@ systemctl restart docker` to reload changes and (re)start the docker daemon. ## 1.12.1 (2016-08-18) -**IMPORTANT**: Docker 1.12 ships with an updated systemd unit file for rpm -based installs (which includes RHEL, Fedora, CentOS, and Oracle Linux 7). When -upgrading from an older version of docker, the upgrade process may not -automatically install the updated version of the unit file, or fail to start -the docker service if; - -- the systemd unit file (`/usr/lib/systemd/system/docker.service`) contains local changes, or -- a systemd drop-in file is present, and contains `-H fd://` in the `ExecStart` directive +> [!IMPORTANT] +> +> Docker 1.12 ships with an updated systemd unit file for rpm +based installs (which includes RHEL, Fedora, CentOS, and Oracle Linux 7). When upgrading from an older version of Docker, the upgrade process may not automatically install the updated version of the unit file, or fail to start the `docker service` if; +> - the systemd unit file (`/usr/lib/systemd/system/docker.service`) contains local changes, or +> - a systemd drop-in file is present, and contains `-H fd://` in the `ExecStart` directive -Starting the docker service will produce an error: +Starting the `docker service` will produce an error: Failed to start docker.service: Unit docker.socket failed to load: No such file or directory. @@ -704,7 +690,7 @@ systemctl restart docker` to reload changes and (re)start the docker daemon. ### Contrib + Official ARM installation for Debian Jessie, Ubuntu Trusty, and Raspbian Jessie [#24815](https://github.com/docker/docker/pull/24815) [#25591](https://github.com/docker/docker/pull/25637) -- Add selinux policy per distro/version, fixing issue preventing successful installation on Fedora 24, and Oracle Linux [#25334](https://github.com/docker/docker/pull/25334) [#25593](https://github.com/docker/docker/pull/25593) +- Add selinux policy per distribution/version, fixing issue preventing successful installation on Fedora 24, and Oracle Linux [#25334](https://github.com/docker/docker/pull/25334) [#25593](https://github.com/docker/docker/pull/25593) ### Networking @@ -755,16 +741,14 @@ systemctl restart docker` to reload changes and (re)start the docker daemon. ## 1.12.0 (2016-07-28) -**IMPORTANT**: Docker 1.12.0 ships with an updated systemd unit file for rpm -based installs (which includes RHEL, Fedora, CentOS, and Oracle Linux 7). When -upgrading from an older version of docker, the upgrade process may not -automatically install the updated version of the unit file, or fail to start -the docker service if; +> [!IMPORTANT] +> +> Docker 1.12.0 ships with an updated systemd unit file for rpm +based installs (which includes RHEL, Fedora, CentOS, and Oracle Linux 7). When upgrading from an older version of Docker, the upgrade process may not automatically install the updated version of the unit file, or fail to start the `docker service` if; +> - the systemd unit file (`/usr/lib/systemd/system/docker.service`) contains local changes, or +> - a systemd drop-in file is present, and contains `-H fd://` in the `ExecStart` directive -- the systemd unit file (`/usr/lib/systemd/system/docker.service`) contains local changes, or -- a systemd drop-in file is present, and contains `-H fd://` in the `ExecStart` directive - -Starting the docker service will produce an error: +Starting the `docker service` will produce an error: Failed to start docker.service: Unit docker.socket failed to load: No such file or directory. @@ -782,9 +766,10 @@ To resolve this: After making those changes, run `sudo systemctl daemon-reload`, and `sudo systemctl restart docker` to reload changes and (re)start the docker daemon. -**IMPORTANT**: With Docker 1.12, a Linux docker installation now has two -additional binaries; `dockerd`, and `docker-proxy`. If you have scripts for -installing docker, make sure to update them accordingly. +> [!IMPORTANT] +> +> With Docker 1.12, a Linux `docker` installation now has two +additional binaries; `dockerd`, and `docker-proxy`. If you have scripts for installing `docker`, make sure to update them accordingly. ### Builder @@ -974,7 +959,9 @@ installing docker, make sure to update them accordingly. ## 1.11.0 (2016-04-13) -**IMPORTANT**: With Docker 1.11, a Linux docker installation is now made of 4 binaries (`docker`, [`docker-containerd`](https://github.com/docker/containerd), [`docker-containerd-shim`](https://github.com/docker/containerd) and [`docker-runc`](https://github.com/opencontainers/runc)). If you have scripts relying on docker being a single static binaries, make sure to update them. Interaction with the daemon stay the same otherwise, the usage of the other binaries should be transparent. A Windows docker installation remains a single binary, `docker.exe`. +> [!IMPORTANT] +> +> With Docker 1.11, a Linux Docker installation is now made of 4 binaries (`docker`, [`docker-containerd`](https://github.com/docker/containerd), [`docker-containerd-shim`](https://github.com/docker/containerd) and [`docker-runc`](https://github.com/opencontainers/runc)). If you have scripts relying on `docker` being a single static binaries, make sure to update them. Interaction with the daemon stay the same otherwise, the usage of the other binaries should be transparent. A Windows Docker installation remains a single binary, `docker.exe`. ### Builder @@ -1223,9 +1210,11 @@ installing docker, make sure to update them accordingly. ## 1.10.0 (2016-02-04) -**IMPORTANT**: Docker 1.10 uses a new content-addressable storage for images and layers. -A migration is performed the first time docker is run, and can take a significant amount of time depending on the number of images present. -Refer to this page on the wiki for more information: https://github.com/docker/docker/wiki/Engine-v1.10.0-content-addressability-migration +> [!IMPORTANT] +> +> Docker 1.10 uses a new content-addressable storage for images and layers. + +A migration is performed the first time `docker` is run, and can take a significant amount of time depending on the number of images present. Refer to this page on the wiki for more information: https://github.com/docker/docker/wiki/Engine-v1.10.0-content-addressability-migration We also released a cool migration utility that enables you to perform the migration before updating to reduce downtime. Engine 1.10 migrator can be found on Docker Hub: https://hub.docker.com/r/docker/v1.10-migrator/ diff --git a/content/manuals/engine/security/rootless.md b/content/manuals/engine/security/rootless.md index c22f878d263..4b78bdf34e6 100644 --- a/content/manuals/engine/security/rootless.md +++ b/content/manuals/engine/security/rootless.md @@ -27,7 +27,7 @@ UIDs/GIDs to be used in the user namespace. ## Prerequisites - You must install `newuidmap` and `newgidmap` on the host. These commands - are provided by the `uidmap` package on most distros. + are provided by the `uidmap` package on most distributions. - `/etc/subuid` and `/etc/subgid` should contain at least 65,536 subordinate UIDs/GIDs for the user. In the following example, the user `testuser` has @@ -123,7 +123,7 @@ testuser:231072:65536 This step is not required on openSUSE Tumbleweed. - `sudo modprobe ip_tables iptable_mangle iptable_nat iptable_filter` is required. - This might be required on other distros as well depending on the configuration. + This might be required on other distributions as well depending on the configuration. - Known to work on openSUSE 15 and SLES 15. {{< /tab >}} diff --git a/content/manuals/engine/security/seccomp.md b/content/manuals/engine/security/seccomp.md index 1ea65a0b9d0..094bdbffe0a 100644 --- a/content/manuals/engine/security/seccomp.md +++ b/content/manuals/engine/security/seccomp.md @@ -26,13 +26,13 @@ protective while providing wide application compatibility. The default Docker profile can be found [here](https://github.com/moby/moby/blob/master/profiles/seccomp/default.json). -In effect, the profile is an allowlist which denies access to system calls by -default, then allowlists specific system calls. The profile works by defining a +In effect, the profile is an allowlist that denies access to system calls by +default and then allows specific system calls. The profile works by defining a `defaultAction` of `SCMP_ACT_ERRNO` and overriding that action only for specific system calls. The effect of `SCMP_ACT_ERRNO` is to cause a `Permission Denied` error. Next, the profile defines a specific list of system calls which are fully allowed, because their `action` is overridden to be `SCMP_ACT_ALLOW`. Finally, -some specific rules are for individual system calls such as `personality`, and others, +some specific rules are for individual system calls such as `personality`, and others, to allow variants of those system calls with specific arguments. `seccomp` is instrumental for running Docker containers with least privilege. It @@ -53,61 +53,61 @@ $ docker run --rm \ Docker's default seccomp profile is an allowlist which specifies the calls that are allowed. The table below lists the significant (but not all) syscalls that -are effectively blocked because they are not on the Allowlist. The table includes +are effectively blocked because they are not on the allowlist. The table includes the reason each syscall is blocked rather than white-listed. -| Syscall | Description | -|---------------------|---------------------------------------------------------------------------------------------------------------------------------------| -| `acct` | Accounting syscall which could let containers disable their own resource limits or process accounting. Also gated by `CAP_SYS_PACCT`. | -| `add_key` | Prevent containers from using the kernel keyring, which is not namespaced. | -| `bpf` | Deny loading potentially persistent bpf programs into kernel, already gated by `CAP_SYS_ADMIN`. | -| `clock_adjtime` | Time/date is not namespaced. Also gated by `CAP_SYS_TIME`. | -| `clock_settime` | Time/date is not namespaced. Also gated by `CAP_SYS_TIME`. | -| `clone` | Deny cloning new namespaces. Also gated by `CAP_SYS_ADMIN` for CLONE_* flags, except `CLONE_NEWUSER`. | -| `create_module` | Deny manipulation and functions on kernel modules. Obsolete. Also gated by `CAP_SYS_MODULE`. | -| `delete_module` | Deny manipulation and functions on kernel modules. Also gated by `CAP_SYS_MODULE`. | -| `finit_module` | Deny manipulation and functions on kernel modules. Also gated by `CAP_SYS_MODULE`. | -| `get_kernel_syms` | Deny retrieval of exported kernel and module symbols. Obsolete. | -| `get_mempolicy` | Syscall that modifies kernel memory and NUMA settings. Already gated by `CAP_SYS_NICE`. | -| `init_module` | Deny manipulation and functions on kernel modules. Also gated by `CAP_SYS_MODULE`. | -| `ioperm` | Prevent containers from modifying kernel I/O privilege levels. Already gated by `CAP_SYS_RAWIO`. | -| `iopl` | Prevent containers from modifying kernel I/O privilege levels. Already gated by `CAP_SYS_RAWIO`. | -| `kcmp` | Restrict process inspection capabilities, already blocked by dropping `CAP_SYS_PTRACE`. | -| `kexec_file_load` | Sister syscall of `kexec_load` that does the same thing, slightly different arguments. Also gated by `CAP_SYS_BOOT`. | -| `kexec_load` | Deny loading a new kernel for later execution. Also gated by `CAP_SYS_BOOT`. | -| `keyctl` | Prevent containers from using the kernel keyring, which is not namespaced. | -| `lookup_dcookie` | Tracing/profiling syscall, which could leak a lot of information on the host. Also gated by `CAP_SYS_ADMIN`. | -| `mbind` | Syscall that modifies kernel memory and NUMA settings. Already gated by `CAP_SYS_NICE`. | -| `mount` | Deny mounting, already gated by `CAP_SYS_ADMIN`. | -| `move_pages` | Syscall that modifies kernel memory and NUMA settings. | -| `nfsservctl` | Deny interaction with the kernel nfs daemon. Obsolete since Linux 3.1. | -| `open_by_handle_at` | Cause of an old container breakout. Also gated by `CAP_DAC_READ_SEARCH`. | -| `perf_event_open` | Tracing/profiling syscall, which could leak a lot of information on the host. | -| `personality` | Prevent container from enabling BSD emulation. Not inherently dangerous, but poorly tested, potential for a lot of kernel vulns. | -| `pivot_root` | Deny `pivot_root`, should be privileged operation. | -| `process_vm_readv` | Restrict process inspection capabilities, already blocked by dropping `CAP_SYS_PTRACE`. | -| `process_vm_writev` | Restrict process inspection capabilities, already blocked by dropping `CAP_SYS_PTRACE`. | +| Syscall | Description | +| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `acct` | Accounting syscall which could let containers disable their own resource limits or process accounting. Also gated by `CAP_SYS_PACCT`. | +| `add_key` | Prevent containers from using the kernel keyring, which is not namespaced. | +| `bpf` | Deny loading potentially persistent BPF programs into kernel, already gated by `CAP_SYS_ADMIN`. | +| `clock_adjtime` | Time/date is not namespaced. Also gated by `CAP_SYS_TIME`. | +| `clock_settime` | Time/date is not namespaced. Also gated by `CAP_SYS_TIME`. | +| `clone` | Deny cloning new namespaces. Also gated by `CAP_SYS_ADMIN` for CLONE\_\* flags, except `CLONE_NEWUSER`. | +| `create_module` | Deny manipulation and functions on kernel modules. Obsolete. Also gated by `CAP_SYS_MODULE`. | +| `delete_module` | Deny manipulation and functions on kernel modules. Also gated by `CAP_SYS_MODULE`. | +| `finit_module` | Deny manipulation and functions on kernel modules. Also gated by `CAP_SYS_MODULE`. | +| `get_kernel_syms` | Deny retrieval of exported kernel and module symbols. Obsolete. | +| `get_mempolicy` | Syscall that modifies kernel memory and NUMA settings. Already gated by `CAP_SYS_NICE`. | +| `init_module` | Deny manipulation and functions on kernel modules. Also gated by `CAP_SYS_MODULE`. | +| `ioperm` | Prevent containers from modifying kernel I/O privilege levels. Already gated by `CAP_SYS_RAWIO`. | +| `iopl` | Prevent containers from modifying kernel I/O privilege levels. Already gated by `CAP_SYS_RAWIO`. | +| `kcmp` | Restrict process inspection capabilities, already blocked by dropping `CAP_SYS_PTRACE`. | +| `kexec_file_load` | Sister syscall of `kexec_load` that does the same thing, slightly different arguments. Also gated by `CAP_SYS_BOOT`. | +| `kexec_load` | Deny loading a new kernel for later execution. Also gated by `CAP_SYS_BOOT`. | +| `keyctl` | Prevent containers from using the kernel keyring, which is not namespaced. | +| `lookup_dcookie` | Tracing/profiling syscall, which could leak a lot of information on the host. Also gated by `CAP_SYS_ADMIN`. | +| `mbind` | Syscall that modifies kernel memory and NUMA settings. Already gated by `CAP_SYS_NICE`. | +| `mount` | Deny mounting, already gated by `CAP_SYS_ADMIN`. | +| `move_pages` | Syscall that modifies kernel memory and NUMA settings. | +| `nfsservctl` | Deny interaction with the kernel NFS daemon. Obsolete since Linux 3.1. | +| `open_by_handle_at` | Cause of an old container breakout. Also gated by `CAP_DAC_READ_SEARCH`. | +| `perf_event_open` | Tracing/profiling syscall, which could leak a lot of information on the host. | +| `personality` | Prevent container from enabling BSD emulation. Not inherently dangerous, but poorly tested, potential for a lot of kernel vulnerabilities. | +| `pivot_root` | Deny `pivot_root`, should be privileged operation. | +| `process_vm_readv` | Restrict process inspection capabilities, already blocked by dropping `CAP_SYS_PTRACE`. | +| `process_vm_writev` | Restrict process inspection capabilities, already blocked by dropping `CAP_SYS_PTRACE`. | | `ptrace` | Tracing/profiling syscall. Blocked in Linux kernel versions before 4.8 to avoid seccomp bypass. Tracing/profiling arbitrary processes is already blocked by dropping `CAP_SYS_PTRACE`, because it could leak a lot of information on the host. | -| `query_module` | Deny manipulation and functions on kernel modules. Obsolete. | -| `quotactl` | Quota syscall which could let containers disable their own resource limits or process accounting. Also gated by `CAP_SYS_ADMIN`. | -| `reboot` | Don't let containers reboot the host. Also gated by `CAP_SYS_BOOT`. | -| `request_key` | Prevent containers from using the kernel keyring, which is not namespaced. | -| `set_mempolicy` | Syscall that modifies kernel memory and NUMA settings. Already gated by `CAP_SYS_NICE`. | -| `setns` | Deny associating a thread with a namespace. Also gated by `CAP_SYS_ADMIN`. | -| `settimeofday` | Time/date is not namespaced. Also gated by `CAP_SYS_TIME`. | -| `stime` | Time/date is not namespaced. Also gated by `CAP_SYS_TIME`. | -| `swapon` | Deny start/stop swapping to file/device. Also gated by `CAP_SYS_ADMIN`. | -| `swapoff` | Deny start/stop swapping to file/device. Also gated by `CAP_SYS_ADMIN`. | -| `sysfs` | Obsolete syscall. | -| `_sysctl` | Obsolete, replaced by /proc/sys. | -| `umount` | Should be a privileged operation. Also gated by `CAP_SYS_ADMIN`. | -| `umount2` | Should be a privileged operation. Also gated by `CAP_SYS_ADMIN`. | -| `unshare` | Deny cloning new namespaces for processes. Also gated by `CAP_SYS_ADMIN`, with the exception of `unshare --user`. | -| `uselib` | Older syscall related to shared libraries, unused for a long time. | -| `userfaultfd` | Userspace page fault handling, largely needed for process migration. | -| `ustat` | Obsolete syscall. | -| `vm86` | In kernel x86 real mode virtual machine. Also gated by `CAP_SYS_ADMIN`. | -| `vm86old` | In kernel x86 real mode virtual machine. Also gated by `CAP_SYS_ADMIN`. | +| `query_module` | Deny manipulation and functions on kernel modules. Obsolete. | +| `quotactl` | Quota syscall which could let containers disable their own resource limits or process accounting. Also gated by `CAP_SYS_ADMIN`. | +| `reboot` | Don't let containers reboot the host. Also gated by `CAP_SYS_BOOT`. | +| `request_key` | Prevent containers from using the kernel keyring, which is not namespaced. | +| `set_mempolicy` | Syscall that modifies kernel memory and NUMA settings. Already gated by `CAP_SYS_NICE`. | +| `setns` | Deny associating a thread with a namespace. Also gated by `CAP_SYS_ADMIN`. | +| `settimeofday` | Time/date is not namespaced. Also gated by `CAP_SYS_TIME`. | +| `stime` | Time/date is not namespaced. Also gated by `CAP_SYS_TIME`. | +| `swapon` | Deny start/stop swapping to file/device. Also gated by `CAP_SYS_ADMIN`. | +| `swapoff` | Deny start/stop swapping to file/device. Also gated by `CAP_SYS_ADMIN`. | +| `sysfs` | Obsolete syscall. | +| `_sysctl` | Obsolete, replaced by /proc/sys. | +| `umount` | Should be a privileged operation. Also gated by `CAP_SYS_ADMIN`. | +| `umount2` | Should be a privileged operation. Also gated by `CAP_SYS_ADMIN`. | +| `unshare` | Deny cloning new namespaces for processes. Also gated by `CAP_SYS_ADMIN`, with the exception of `unshare --user`. | +| `uselib` | Older syscall related to shared libraries, unused for a long time. | +| `userfaultfd` | Userspace page fault handling, largely needed for process migration. | +| `ustat` | Obsolete syscall. | +| `vm86` | In kernel x86 real mode virtual machine. Also gated by `CAP_SYS_ADMIN`. | +| `vm86old` | In kernel x86 real mode virtual machine. Also gated by `CAP_SYS_ADMIN`. | ## Run without the default seccomp profile @@ -115,6 +115,6 @@ You can pass `unconfined` to run a container without the default seccomp profile. ```console -$ docker run --rm -it --security-opt seccomp=unconfined debian:jessie \ +$ docker run --rm -it --security-opt seccomp=unconfined debian:latest \ unshare --map-root-user --user sh -c whoami ``` diff --git a/content/manuals/engine/security/userns-remap.md b/content/manuals/engine/security/userns-remap.md index bc58ded55ad..57dfe29986b 100644 --- a/content/manuals/engine/security/userns-remap.md +++ b/content/manuals/engine/security/userns-remap.md @@ -264,7 +264,7 @@ daemon with user namespaces enabled: User namespaces are an advanced feature and require coordination with other capabilities. For example, if volumes are mounted from the host, file ownership -must be pre-arranged need read or write access to the volume contents. +must be pre-arranged if you need read or write access to the volume contents. While the root user inside a user-namespaced container process has many of the expected privileges of the superuser within the container, the Linux kernel diff --git a/content/manuals/engine/storage/_index.md b/content/manuals/engine/storage/_index.md index 255d796dbfd..d616e302867 100644 --- a/content/manuals/engine/storage/_index.md +++ b/content/manuals/engine/storage/_index.md @@ -9,206 +9,72 @@ aliases: --- By default all files created inside a container are stored on a writable -container layer. This means that: +container layer that sits on top of the read-only, immutable image layers. -- The data doesn't persist when that container no longer exists, and it can be - difficult to get the data out of the container if another process needs it. -- A container's writable layer is tightly coupled to the host machine - where the container is running. You can't easily move the data somewhere else. -- Writing into a container's writable layer requires a - [storage driver](/engine/storage/drivers/) to manage the - filesystem. The storage driver provides a union filesystem, using the Linux - kernel. This extra abstraction reduces performance as compared to using - _data volumes_, which write directly to the host filesystem. +Data written to the container layer doesn't persist when the container is +destroyed. This means that it can be difficult to get the data out of the +container if another process needs it. -Docker has two options for containers to store files on the host machine, so -that the files are persisted even after the container stops: volumes, and -bind mounts. +The writable layer is unique per container. You can't easily extract the data +from the writeable layer to the host, or to another container. -Docker also supports containers storing files in-memory on the host machine. Such files are not persisted. -If you're running Docker on Linux, `tmpfs` mount is used to store files in the host's system memory. -If you're running Docker on Windows, named pipe is used to store files in the host's system memory. +## Storage mount options -## Choose the right type of mount +Docker supports the following types of storage mounts for storing data outside +of the writable layer of the container: + +- [Volume mounts](#volume-mounts) +- [Bind mounts](#bind-mounts) +- [tmpfs mounts](#tmpfs-mounts) +- [Named pipes](#named-pipes) No matter which type of mount you choose to use, the data looks the same from within the container. It is exposed as either a directory or an individual file in the container's filesystem. -An easy way to visualize the difference among volumes, bind mounts, and `tmpfs` -mounts is to think about where the data lives on the Docker host. - -![Types of mounts and where they live on the Docker host](images/types-of-mounts.webp?w=450&h=300) - -- Volumes are stored in a part of the host filesystem which is _managed by - Docker_ (`/var/lib/docker/volumes/` on Linux). Non-Docker processes should not - modify this part of the filesystem. Volumes are the best way to persist data - in Docker. - -- Bind mounts may be stored anywhere on the host system. They may even be - important system files or directories. Non-Docker processes on the Docker host - or a Docker container can modify them at any time. - -- `tmpfs` mounts are stored in the host system's memory only, and are never - written to the host system's filesystem. - -Bind mounts and volumes can both be mounted into containers using the `-v` or -`--volume` flag, but the syntax for each is slightly different. For `tmpfs` -mounts, you can use the `--tmpfs` flag. We recommend using the `--mount` flag -for both containers and services, for bind mounts, volumes, or `tmpfs` mounts, -as the syntax is more clear. - -### Volumes - -Volumes are created and managed by Docker. You can create a volume explicitly -using the `docker volume create` command, or Docker can create a volume during -container or service creation. - -When you create a volume, it's stored within a directory on the Docker -host. When you mount the volume into a container, this directory is what's -mounted into the container. This is similar to the way that bind mounts work, -except that volumes are managed by Docker and are isolated from the core -functionality of the host machine. - -A given volume can be mounted into multiple containers simultaneously. When no -running container is using a volume, the volume is still available to Docker -and isn't removed automatically. You can remove unused volumes using `docker -volume prune`. - -When you mount a volume, it may be named or anonymous. Anonymous volumes are -given a random name that's guaranteed to be unique within a given Docker host. -Just like named volumes, anonymous volumes persist even if you remove the -container that uses them, except if you use the `--rm` flag when creating the -container, in which case the anonymous volume is destroyed. -See [Remove anonymous volumes](volumes.md#remove-anonymous-volumes). -If you create multiple containers after each other that use anonymous volumes, -each container creates its own volume. -Anonymous volumes aren't reused or shared between containers automatically. -To share an anonymous volume between two or more containers, -you must mount the anonymous volume using the random volume ID. - -Volumes also support the use of volume drivers, which allow you to store -your data on remote hosts or cloud providers, among other possibilities. - -### Bind mounts - -Bind mounts have limited functionality compared to volumes. When you use a bind -mount, a file or directory on the host machine is mounted into a container. The -file or directory is referenced by its full path on the host machine. The file -or directory doesn't need to exist on the Docker host already. It is created on -demand if it doesn't yet exist. Bind mounts are fast, but they rely on the host -machine's filesystem having a specific directory structure available. If you -are developing new Docker applications, consider using named volumes instead. -You can't use Docker CLI commands to directly manage bind mounts. - -> [!IMPORTANT] -> -> Bind mounts allow write access to files on the host by default. -> -> One side effect of using bind mounts is that you can change the host -> filesystem via processes running in a container, including creating, -> modifying, or deleting important system files or directories. This is a -> powerful ability which can have security implications, including impacting -> non-Docker processes on the host system. - -> [!TIP] -> -> Working with large repositories or monorepos, or with virtual file systems that are no longer scaling with your codebase? -> Check out [Synchronized file shares](/manuals/desktop/synchronized-file-sharing.md). It provides fast and flexible host-to-VM file sharing by enhancing bind mount performance through the use of synchronized filesystem caches. - -### tmpfs - -A `tmpfs` mount isn't persisted on disk, either on the Docker host or within a -container. It can be used by a container during the lifetime of the container, -to store non-persistent state or sensitive information. For instance, -internally, Swarm services use `tmpfs` mounts to mount -[secrets](/manuals/engine/swarm/secrets.md) into a service's containers. - -### Named pipes - -[Named pipes](https://docs.microsoft.com/en-us/windows/desktop/ipc/named-pipes) -can be used for communication between the Docker host and a container. Common -use case is to run a third-party tool inside of a container and connect to the -Docker Engine API using a named pipe. - -## Good use cases for volumes - -Volumes are the preferred way to persist data in Docker containers and services. -Some use cases for volumes include: - -- Sharing data among multiple running containers. If you don't explicitly create - it, a volume is created the first time it is mounted into a container. When - that container stops or is removed, the volume still exists. Multiple - containers can mount the same volume simultaneously, either read-write or - read-only. Volumes are only removed when you explicitly remove them. +### Volume mounts -- When the Docker host is not guaranteed to have a given directory or file - structure. Volumes help you decouple the configuration of the Docker host - from the container runtime. +Volumes are persistent storage mechanisms managed by the Docker daemon. They +retain data even after the containers using them are removed. Volume data is +stored on the filesystem on the host, but in order to interact with the data in +the volume, you must mount the volume to a container. Directly accessing or +interacting with the volume data is unsupported, undefined behavior, and may +result in the volume or its data breaking in unexpected ways. -- When you want to store your container's data on a remote host or a cloud - provider, rather than locally. +Volumes are ideal for performance-critical data processing and long-term +storage needs. Since the storage location is managed on the daemon host, +volumes provide the same raw file performance as accessing the host filesystem +directly. -- When you need to back up, restore, or migrate data from one Docker - host to another, volumes are a better choice. You can stop containers using - the volume, then back up the volume's directory - (such as `/var/lib/docker/volumes/`). - -- When your application requires high-performance I/O on Docker Desktop. Volumes - are stored in the Linux VM rather than the host, which means that the reads and writes - have much lower latency and higher throughput. - -- When your application requires fully native file system behavior on Docker - Desktop. For example, a database engine requires precise control over disk - flushing to guarantee transaction durability. Volumes are stored in the Linux - VM and can make these guarantees, whereas bind mounts are remoted to macOS or - Windows, where the file systems behave slightly differently. - -## Good use cases for bind mounts - -In general, you should use volumes where possible. Bind mounts are appropriate -for the following types of use case: - -- Sharing configuration files from the host machine to containers. This is how - Docker provides DNS resolution to containers by default, by mounting - `/etc/resolv.conf` from the host machine into each container. - -- Sharing source code or build artifacts between a development environment on - the Docker host and a container. For instance, you may mount a Maven `target/` - directory into a container, and each time you build the Maven project on the - Docker host, the container gets access to the rebuilt artifacts. - - If you use Docker for development this way, your production Dockerfile would - copy the production-ready artifacts directly into the image, rather than - relying on a bind mount. +### Bind mounts -- When the file or directory structure of the Docker host is guaranteed to be - consistent with the bind mounts the containers require. +Bind mounts create a direct link between a host system path and a container, +allowing access to files or directories stored anywhere on the host. Since they +aren't isolated by Docker, both non-Docker processes on the host and container +processes can modify the mounted files simultaneously. -## Good use cases for tmpfs mounts +Use bind mounts when you need to be able to access files from both the +container and the host. -`tmpfs` mounts are best used for cases when you do not want the data to persist -either on the host machine or within the container. This may be for security -reasons or to protect the performance of the container when your application -needs to write a large volume of non-persistent state data. +### tmpfs mounts -## Tips for using bind mounts or volumes +A tmpfs mount stores files directly in the host machine's memory, ensuring the +data is not written to disk. This storage is ephemeral: the data is lost when +the container is stopped or restarted, or when the host is rebooted. tmpfs +mounts do not persist data either on the Docker host or within the container's +filesystem. -If you use either bind mounts or volumes, keep the following in mind: +These mounts are suitable for scenarios requiring temporary, in-memory storage, +such as caching intermediate data, handling sensitive information like +credentials, or reducing disk I/O. Use tmpfs mounts only when the data does not +need to persist beyond the current container session. -- If you mount an **empty volume** into a directory in the container in which files - or directories exist, these files or directories are propagated (copied) - into the volume. Similarly, if you start a container and specify a volume which - does not already exist, an empty volume is created for you. - This is a good way to pre-populate data that another container needs. +### Named pipes -- If you mount a **bind mount or non-empty volume** into a directory in the container - in which some files or directories exist, these files or directories are - obscured by the mount, just as if you saved files into `/mnt` on a Linux host - and then mounted a USB drive into `/mnt`. The contents of `/mnt` would be - obscured by the contents of the USB drive until the USB drive was unmounted. - The obscured files are not removed or altered, but are not accessible while the - bind mount or volume is mounted. +[Named pipes](https://docs.microsoft.com/en-us/windows/desktop/ipc/named-pipes) +can be used for communication between the Docker host and a container. Common +use case is to run a third-party tool inside of a container and connect to the +Docker Engine API using a named pipe. ## Next steps diff --git a/content/manuals/engine/storage/bind-mounts.md b/content/manuals/engine/storage/bind-mounts.md index 8681bada27c..4b5d07c09d9 100644 --- a/content/manuals/engine/storage/bind-mounts.md +++ b/content/manuals/engine/storage/bind-mounts.md @@ -4,91 +4,150 @@ title: Bind mounts weight: 20 keywords: storage, persistence, data persistence, mounts, bind mounts aliases: -- /engine/admin/volumes/bind-mounts/ -- /storage/bind-mounts/ + - /engine/admin/volumes/bind-mounts/ + - /storage/bind-mounts/ --- -Bind mounts have been around since the early days of Docker. Bind mounts have -limited functionality compared to [volumes](volumes.md). When you use a bind -mount, a file or directory on the host machine is mounted into a container. -The file or directory is referenced by its absolute path on the host -machine. By contrast, when you use a volume, a new directory is created within -Docker's storage directory on the host machine, and Docker manages that -directory's contents. +When you use a bind mount, a file or directory on the host machine is mounted +from the host into a container. By contrast, when you use a volume, a new +directory is created within Docker's storage directory on the host machine, and +Docker manages that directory's contents. -The file or directory does not need to exist on the Docker host already. It is -created on demand if it does not yet exist. Bind mounts are very performant, but -they rely on the host machine's filesystem having a specific directory structure -available. If you are developing new Docker applications, consider using -[named volumes](volumes.md) instead. You can't use Docker CLI commands to directly -manage bind mounts. +## When to use bind mounts -![Bind mounts on the Docker host](images/types-of-mounts-bind.webp?w=450&h=300) +Bind mounts are appropriate for the following types of use case: -> [!TIP] -> -> Working with large repositories or monorepos, or with virtual file systems that are no longer scaling with your codebase? -> Check out [Synchronized file shares](/manuals/desktop/synchronized-file-sharing.md). It provides fast and flexible host-to-VM file sharing by enhancing bind mount performance through the use of synchronized filesystem caches. +- Sharing source code or build artifacts between a development environment on + the Docker host and a container. -## Choose the -v or --mount flag +- When you want to create or generate files in a container and persist the + files onto the host's filesystem. -In general, `--mount` is more explicit and verbose. The biggest difference is that -the `-v` syntax combines all the options together in one field, while the `--mount` -syntax separates them. Here is a comparison of the syntax for each flag. +- Sharing configuration files from the host machine to containers. This is how + Docker provides DNS resolution to containers by default, by mounting + `/etc/resolv.conf` from the host machine into each container. -> Tip -> -> New users should use the `--mount` syntax. Experienced users may -> be more familiar with the `-v` or `--volume` syntax, but are encouraged to -> use `--mount`, because research has shown it to be easier to use. - -- `-v` or `--volume`: Consists of three fields, separated by colon characters - (`:`). The fields must be in the correct order, and the meaning of each field - is not immediately obvious. - - In the case of bind mounts, the first field is the path to the file or - directory on the **host machine**. - - The second field is the path where the file or directory is mounted in - the container. - - The third field is optional, and is a comma-separated list of options, such - as `ro`, `z`, and `Z`. These options - are discussed below. - -- `--mount`: Consists of multiple key-value pairs, separated by commas and each - consisting of a `=` tuple. The `--mount` syntax is more verbose - than `-v` or `--volume`, but the order of the keys is not significant, and - the value of the flag is easier to understand. - - The `type` of the mount, which can be `bind`, `volume`, or `tmpfs`. This - topic discusses bind mounts, so the type is always `bind`. - - The `source` of the mount. For bind mounts, this is the path to the file - or directory on the Docker daemon host. May be specified as `source` or - `src`. - - The `destination` takes as its value the path where the file or directory - is mounted in the container. May be specified as `destination`, `dst`, - or `target`. - - The `readonly` option, if present, causes the bind mount to be [mounted into - the container as read-only](#use-a-read-only-bind-mount). - - The `bind-propagation` option, if present, changes the - [bind propagation](#configure-bind-propagation). May be one of `rprivate`, - `private`, `rshared`, `shared`, `rslave`, `slave`. - - The `--mount` flag does not support `z` or `Z` options for modifying - selinux labels. - -The examples below show both the `--mount` and `-v` syntax where possible, and -`--mount` is presented first. - -### Differences between `-v` and `--mount` behavior - -Because the `-v` and `--volume` flags have been a part of Docker for a long -time, their behavior cannot be changed. This means that there is one behavior -that is different between `-v` and `--mount`. - -If you use `-v` or `--volume` to bind-mount a file or directory that does not -yet exist on the Docker host, `-v` creates the endpoint for you. It is -always created as a directory. - -If you use `--mount` to bind-mount a file or directory that does not -yet exist on the Docker host, Docker does not automatically create it for -you, but generates an error. +Bind mounts are also available for builds: you can bind mount source code from +the host into the build container to test, lint, or compile a project. + +## Bind-mounting over existing data + +If you bind mount file or directory into a directory in the container in which +files or directories exist, the pre-existing files are obscured by the mount. +This is similar to if you were to save files into `/mnt` on a Linux host, and +then mounted a USB drive into `/mnt`. The contents of `/mnt` would be obscured +by the contents of the USB drive until the USB drive was unmounted. + +With containers, there's no straightforward way of removing a mount to reveal +the obscured files again. Your best option is to recreate the container without +the mount. + +## Considerations and constraints + +- Bind mounts have write access to files on the host by default. + + One side effect of using bind mounts is that you can change the host + filesystem via processes running in a container, including creating, + modifying, or deleting important system files or directories. This capability + can have security implications. For example, it may affect non-Docker + processes on the host system. + + You can use the `readonly` or `ro` option to prevent the container from + writing to the mount. + +- Bind mounts are created to the Docker daemon host, not the client. + + If you're using a remote Docker daemon, you can't create a bind mount to + access files on the client machine in a container. + + For Docker Desktop, the daemon runs inside a Linux VM, not directly on the + native host. Docker Desktop has built-in mechanisms that transparently handle + bind mounts, allowing you to share native host filesystem paths with + containers running in the virtual machine. + +- Containers with bind mounts are strongly tied to the host. + + Bind mounts rely on the host machine's filesystem having a specific directory + structure available. This reliance means that containers with bind mounts may + fail if run on a different host without the same directory structure. + +## Syntax + +To create a bind mount, you can use either the `--mount` or `--volume` flag. + +```console +$ docker run --mount type=bind,src=,dst= +$ docker run --volume : +``` + +In general, `--mount` is preferred. The main difference is that the `--mount` +flag is more explicit and supports all the available options. + +If you use `--volume` to bind-mount a file or directory that does not yet +exist on the Docker host, Docker automatically creates the directory on the +host for you. It's always created as a directory. + +`--mount` does not automatically create a directory if the specified mount +path does not exist on the host. Instead, it produces an error: + +```console +$ docker run --mount type=bind,src=/dev/noexist,dst=/mnt/foo alpine +docker: Error response from daemon: invalid mount config for type "bind": bind source path does not exist: /dev/noexist. +``` + +### Options for --mount + +The `--mount` flag consists of multiple key-value pairs, separated by commas +and each consisting of a `=` tuple. The order of the keys isn't +significant. + +```console +$ docker run --mount type=bind,src=,dst=[,=...] +``` + +Valid options for `--mount type=bind` include: + +| Option | Description | +| ------------------------------ | --------------------------------------------------------------------------------------------------------------- | +| `source`, `src` | The location of the file or directory on the host. This can be an absolute or relative path. | +| `destination`, `dst`, `target` | The path where the file or directory is mounted in the container. Must be an absolute path. | +| `readonly`, `ro` | If present, causes the bind mount to be [mounted into the container as read-only](#use-a-read-only-bind-mount). | +| `bind-propagation` | If present, changes the [bind propagation](#configure-bind-propagation). | + +```console {title="Example"} +$ docker run --mount type=bind,src=.,dst=/project,ro,bind-propagation=rshared +``` + +### Options for --volume + +The `--volume` or `-v` flag consists of three fields, separated by colon +characters (`:`). The fields must be in the correct order. + +```console +$ docker run -v :[:opts] +``` + +The first field is the path on the host to bind mount into the container. The +second field is the path where the file or directory is mounted in the +container. + +The third field is optional, and is a comma-separated list of options. Valid +options for `--volume` with a bind mount include: + +| Option | Description | +| -------------------- | ------------------------------------------------------------------------------------------------------------------ | +| `readonly`, `ro` | If present, causes the bind mount to be [mounted into the container as read-only](#use-a-read-only-bind-mount). | +| `z`, `Z` | Configures SELinux labeling. See [Configure the SELinux label](#configure-the-selinux-label) | +| `rprivate` (default) | Sets bind propagation to `rprivate` for this mount. See [Configure bind propagation](#configure-bind-propagation). | +| `private` | Sets bind propagation to `private` for this mount. See [Configure bind propagation](#configure-bind-propagation). | +| `rshared` | Sets bind propagation to `rshared` for this mount. See [Configure bind propagation](#configure-bind-propagation). | +| `shared` | Sets bind propagation to `shared` for this mount. See [Configure bind propagation](#configure-bind-propagation). | +| `rslave` | Sets bind propagation to `rslave` for this mount. See [Configure bind propagation](#configure-bind-propagation). | +| `slave` | Sets bind propagation to `slave` for this mount. See [Configure bind propagation](#configure-bind-propagation). | + +```console {title="Example"} +$ docker run -v .:/project:ro,rshared +``` ## Start a container with a bind mount @@ -100,11 +159,11 @@ on your development host. Use the following command to bind-mount the `target/` directory into your container at `/app/`. Run the command from within the `source` directory. The `$(pwd)` sub-command expands to the current working directory on Linux or macOS hosts. -If you're on Windows, see also [Path conversions on Windows](/manuals/desktop/troubleshoot/topics.md). +If you're on Windows, see also [Path conversions on Windows](/manuals/desktop/troubleshoot-and-support/troubleshoot/topics.md). -The `--mount` and `-v` examples below produce the same result. You -can't run them both unless you remove the `devtest` container after running the -first one. +The following `--mount` and `-v` examples produce the same result. You can't +run them both unless you remove the `devtest` container after running the first +one. {{< tabs >}} {{< tab name="`--mount`" >}} @@ -151,21 +210,19 @@ This shows that the mount is a `bind` mount, it shows the correct source and destination, it shows that the mount is read-write, and that the propagation is set to `rprivate`. -Stop the container: +Stop and remove the container: ```console -$ docker container stop devtest - -$ docker container rm devtest +$ docker container rm -fv devtest ``` ### Mount into a non-empty directory on the container -If you bind-mount a directory into a non-empty directory on the container, the directory's -existing contents are obscured by the bind mount. This can be beneficial, -such as when you want to test a new version of your application without -building a new image. However, it can also be surprising and this behavior -differs from that of [docker volumes](volumes.md). +If you bind-mount a directory into a non-empty directory on the container, the +directory's existing contents are obscured by the bind mount. This can be +beneficial, such as when you want to test a new version of your application +without building a new image. However, it can also be surprising and this +behavior differs from that of [volumes](volumes.md). This example is contrived to be extreme, but replaces the contents of the container's `/usr/` directory with the `/tmp/` directory on the host machine. In @@ -216,7 +273,7 @@ For some development applications, the container needs to write into the bind mount, so changes are propagated back to the Docker host. At other times, the container only needs read access. -This example modifies the one above but mounts the directory as a read-only +This example modifies the previous one, but mounts the directory as a read-only bind mount, by adding `ro` to the (empty by default) list of options, after the mount point within the container. Where multiple options are present, separate them by commas. @@ -264,12 +321,10 @@ correctly. Look for the `Mounts` section: ], ``` -Stop the container: +Stop and remove the container: ```console -$ docker container stop devtest - -$ docker container rm devtest +$ docker container rm -fv devtest ``` ## Recursive mounts @@ -290,7 +345,7 @@ be read-only on a kernel version earlier than 5.12, using the Supported values for the `bind-recursive` option are: | Value | Description | -|:--------------------|:------------------------------------------------------------------------------------------------------------------| +| :------------------ | :---------------------------------------------------------------------------------------------------------------- | | `enabled` (default) | Read-only mounts are made recursively read-only if kernel is v5.12 or later. Otherwise, submounts are read-write. | | `disabled` | Submounts are ignored (not included in the bind mount). | | `writable` | Submounts are read-write. | @@ -310,12 +365,11 @@ propagation setting has a recursive counterpoint. In the case of recursion, consider that `/tmp/a` is also mounted as `/foo`. The propagation settings control whether `/mnt/a` and/or `/tmp/a` would exist. -> [!WARNING] -> +> [!NOTE] > Mount propagation doesn't work with Docker Desktop. | Propagation setting | Description | -|:--------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `shared` | Sub-mounts of the original mount are exposed to replica mounts, and sub-mounts of replica mounts are also propagated to the original mount. | | `slave` | similar to a shared mount, but only in one direction. If the original mount exposes a sub-mount, the replica mount can see it. However, if the replica mount exposes a sub-mount, the original mount cannot see it. | | `private` | The mount is private. Sub-mounts within it are not exposed to replica mounts, and sub-mounts of replica mounts are not exposed to the original mount. | @@ -364,9 +418,9 @@ $ docker run -d \ Now if you create `/app/foo/`, `/app2/foo/` also exists. -## Configure the selinux label +## Configure the SELinux label -If you use `selinux` you can add the `z` or `Z` options to modify the selinux +If you use SELinux, you can add the `z` or `Z` options to modify the SELinux label of the host file or directory being mounted into the container. This affects the file or directory on the host machine itself and can have consequences outside of the scope of Docker. @@ -381,14 +435,14 @@ inoperable and you may need to relabel the host machine files by hand. > [!IMPORTANT] > -> When using bind mounts with services, selinux labels +> When using bind mounts with services, SELinux labels > (`:Z` and `:z`), as well as `:ro` are ignored. See > [moby/moby #32579](https://github.com/moby/moby/issues/32579) for details. This example sets the `z` option to specify that multiple containers can share the bind mount's contents: -It is not possible to modify the selinux label using the `--mount` flag. +It is not possible to modify the SELinux label using the `--mount` flag. ```console $ docker run -d \ @@ -398,8 +452,7 @@ $ docker run -d \ nginx:latest ``` - -## Use a bind mount with compose +## Use a bind mount with Docker Compose A single Docker Compose service with a bind mount looks like this: diff --git a/content/manuals/engine/storage/containerd.md b/content/manuals/engine/storage/containerd.md index e77858c4e5f..e228227809a 100644 --- a/content/manuals/engine/storage/containerd.md +++ b/content/manuals/engine/storage/containerd.md @@ -12,7 +12,7 @@ aliases: > > The containerd image store is an experimental feature of Docker Engine. > If you're using Docker Desktop, refer to the instructions on the -> [containerd image store with Docker Desktop page](/manuals/desktop/containerd.md). +> [containerd image store with Docker Desktop page](/manuals/desktop/features/containerd.md). containerd, the industry-standard container runtime, uses snapshotters instead of the classic storage drivers for storing image and container data. @@ -20,7 +20,7 @@ While the `overlay2` driver still remains the default driver for Docker Engine, you can opt in to using containerd snapshotters as an experimental feature. To learn more about the containerd image store and its benefits, refer to -[containerd image store on Docker Desktop](/manuals/desktop/containerd.md). +[containerd image store on Docker Desktop](/manuals/desktop/features/containerd.md). ## Enable containerd image store on Docker Engine diff --git a/content/manuals/engine/storage/drivers/_index.md b/content/manuals/engine/storage/drivers/_index.md index 07ad123cfab..57bf355e7b8 100644 --- a/content/manuals/engine/storage/drivers/_index.md +++ b/content/manuals/engine/storage/drivers/_index.md @@ -48,7 +48,7 @@ CMD python /app/app.py ``` This Dockerfile contains four commands. Commands that modify the filesystem create -a layer. The `FROM` statement starts out by creating a layer from the `ubuntu:22.04` +a new layer. The `FROM` statement starts out by creating a layer from the `ubuntu:22.04` image. The `LABEL` command only modifies the image's metadata, and doesn't produce a new layer. The `COPY` command adds some files from your Docker client's current directory. The first `RUN` command builds your application using the `make` command, diff --git a/content/manuals/engine/storage/drivers/device-mapper-driver.md b/content/manuals/engine/storage/drivers/device-mapper-driver.md index 3b0dfb29d34..7eb9de9bb6a 100644 --- a/content/manuals/engine/storage/drivers/device-mapper-driver.md +++ b/content/manuals/engine/storage/drivers/device-mapper-driver.md @@ -834,14 +834,10 @@ storage driver. by thin provisioning and copy-on-write. Volumes have other benefits, such as allowing you to share data among containers and persisting even when no running container is using them. - -- **Note**: when using `devicemapper` and the `json-file` log driver, the log - files generated by a container are still stored in Docker's dataroot directory, - by default `/var/lib/docker`. If your containers generate lots of log messages, - this may lead to increased disk usage or the inability to manage your system due - to a full disk. You can configure a - [log driver](/manuals/engine/logging/configure.md) to store your container - logs externally. + + > [!NOTE] + > + > When using `devicemapper` and the `json-file` log driver, the log files generated by a container are still stored in Docker's dataroot directory, by default `/var/lib/docker`. If your containers generate lots of log messages, this may lead to increased disk usage or the inability to manage your system due to a full disk. You can configure a [log driver](/manuals/engine/logging/configure.md) to store your container logs externally. ## Related Information diff --git a/content/manuals/engine/storage/drivers/select-storage-driver.md b/content/manuals/engine/storage/drivers/select-storage-driver.md index b0f5dc38c1b..fe441ce5fc8 100644 --- a/content/manuals/engine/storage/drivers/select-storage-driver.md +++ b/content/manuals/engine/storage/drivers/select-storage-driver.md @@ -19,6 +19,12 @@ Docker host. After you have read the [storage driver overview](./_index.md), the next step is to choose the best storage driver for your workloads. Use the storage driver with the best overall performance and stability in the most usual scenarios. +> [!NOTE] +> This page discusses storage drivers for Docker Engine on Linux. If you're +> running the Docker daemon with Windows as the host OS, the only supported +> storage driver is windowsfilter. For more information, see +> [windowsfilter](windowsfilter-driver.md). + The Docker Engine provides the following storage drivers on Linux: | Driver | Description | @@ -53,7 +59,7 @@ the final decision. > > Modifying the storage driver by editing the daemon configuration file isn't > supported on Docker Desktop. Only the default `overlay2` driver or the -> [containerd storage](/manuals/desktop/containerd.md) are supported. The +> [containerd storage](/manuals/desktop/features/containerd.md) are supported. The > following table is also not applicable for the Docker Engine in rootless > mode. For the drivers available in rootless mode, see the [Rootless mode > documentation](/manuals/engine/security/rootless.md). @@ -189,7 +195,8 @@ to physical or logical disks on the Docker host. ## Related information -- [About images, containers, and storage drivers](./_index.md) -- [`overlay2` storage driver in practice](overlayfs-driver.md) -- [`btrfs` storage driver in practice](btrfs-driver.md) -- [`zfs` storage driver in practice](zfs-driver.md) +- [Storage drivers](./_index.md) +- [`overlay2` storage driver](overlayfs-driver.md) +- [`btrfs` storage driver](btrfs-driver.md) +- [`zfs` storage driver](zfs-driver.md) +- [`windowsfilter` storage driver](windowsfilter-driver.md) diff --git a/content/manuals/engine/storage/drivers/windowsfilter-driver.md b/content/manuals/engine/storage/drivers/windowsfilter-driver.md new file mode 100644 index 00000000000..a38f6d865d5 --- /dev/null +++ b/content/manuals/engine/storage/drivers/windowsfilter-driver.md @@ -0,0 +1,36 @@ +--- +description: Learn about the windowsfilter storage driver +keywords: container, storage, driver, windows, windowsfilter +title: windowsfilter storage driver +--- + +The windowsfilter storage driver is the default storage driver for Docker +Engine on Windows. The windowsfilter driver uses Windows-native file system +layers to for storing Docker layers and volume data on disk. The windowsfilter +storage driver only works on file systems formatted with NTFS. + +## Configure the windowsfilter storage driver + +For most use case, no configuring the windowsfilter storage driver is not +necessary. + +The default storage limit for Docker Engine on Windows is 127GB. To use a +different storage size, set the `size` option for the windowsfilter storage +driver. See [windowsfilter options](/reference/cli/dockerd.md#windowsfilter-options). + +Data is stored on the Docker host in `image` and `windowsfilter` subdirectories +within `C:\ProgramData\docker` by default. You can change the storage location +by configuring the `data-root` option in the [Daemon configuration file](/reference/cli/dockerd.md#on-windows): + +```json +{ + "data-root": "d:\\docker" +} +``` + +You must restart the daemon for the configuration change to take effect. + +## Additional information + +For more information about how container storage works on Windows, refer to +Microsoft's [Containers on Windows documentation](https://learn.microsoft.com/en-us/virtualization/windowscontainers/manage-containers/container-storage). diff --git a/content/manuals/engine/storage/drivers/zfs-driver.md b/content/manuals/engine/storage/drivers/zfs-driver.md index cf22f58348c..a0c7e1b753b 100644 --- a/content/manuals/engine/storage/drivers/zfs-driver.md +++ b/content/manuals/engine/storage/drivers/zfs-driver.md @@ -20,10 +20,9 @@ The ZFS on Linux (ZoL) port is healthy and maturing. However, at this point in time it is not recommended to use the `zfs` Docker storage driver for production use unless you have substantial experience with ZFS on Linux. -> ***Note***: There is also a FUSE implementation of ZFS on the Linux platform. -> This is not recommended. The native ZFS driver (ZoL) is more tested, more -> performant, and is more widely used. The remainder of this document refers -> to the native ZoL port. +> [!NOTE] +> +> There is also a FUSE implementation of ZFS on the Linux platform. This is not recommended. The native ZFS driver (ZoL) is more tested, has better performance, and is more widely used. The remainder of this document refers to the native ZoL port. ## Prerequisites @@ -38,8 +37,7 @@ use unless you have substantial experience with ZFS on Linux. > [!NOTE] > -> There is no need to use `MountFlags=slave` because `dockerd` and `containerd` -> are in different mount namespaces. +> There is no need to use `MountFlags=slave` because `dockerd` and `containerd` are in different mount namespaces. ## Configure Docker with the `zfs` storage driver diff --git a/content/manuals/engine/storage/images/types-of-mounts-bind.webp b/content/manuals/engine/storage/images/types-of-mounts-bind.webp deleted file mode 100644 index 533efb7cfaf..00000000000 Binary files a/content/manuals/engine/storage/images/types-of-mounts-bind.webp and /dev/null differ diff --git a/content/manuals/engine/storage/images/types-of-mounts-tmpfs.webp b/content/manuals/engine/storage/images/types-of-mounts-tmpfs.webp deleted file mode 100644 index 35b2f085944..00000000000 Binary files a/content/manuals/engine/storage/images/types-of-mounts-tmpfs.webp and /dev/null differ diff --git a/content/manuals/engine/storage/images/types-of-mounts-volume.webp b/content/manuals/engine/storage/images/types-of-mounts-volume.webp deleted file mode 100644 index 0c8d8d0bd3c..00000000000 Binary files a/content/manuals/engine/storage/images/types-of-mounts-volume.webp and /dev/null differ diff --git a/content/manuals/engine/storage/images/types-of-mounts.webp b/content/manuals/engine/storage/images/types-of-mounts.webp deleted file mode 100644 index 64f380c7705..00000000000 Binary files a/content/manuals/engine/storage/images/types-of-mounts.webp and /dev/null differ diff --git a/content/manuals/engine/storage/tmpfs.md b/content/manuals/engine/storage/tmpfs.md index 7c124a371a3..b4e186acb3d 100644 --- a/content/manuals/engine/storage/tmpfs.md +++ b/content/manuals/engine/storage/tmpfs.md @@ -4,61 +4,144 @@ title: tmpfs mounts weight: 30 keywords: storage, persistence, data persistence, tmpfs aliases: -- /engine/admin/volumes/tmpfs/ -- /storage/tmpfs/ + - /engine/admin/volumes/tmpfs/ + - /storage/tmpfs/ --- [Volumes](volumes.md) and [bind mounts](bind-mounts.md) let you share files between the host machine and container so that you can persist data even after the container is stopped. -If you're running Docker on Linux, you have a third option: `tmpfs` mounts. -When you create a container with a `tmpfs` mount, the container can create +If you're running Docker on Linux, you have a third option: tmpfs mounts. +When you create a container with a tmpfs mount, the container can create files outside the container's writable layer. -As opposed to volumes and bind mounts, a `tmpfs` mount is temporary, and only -persisted in the host memory. When the container stops, the `tmpfs` mount is +As opposed to volumes and bind mounts, a tmpfs mount is temporary, and only +persisted in the host memory. When the container stops, the tmpfs mount is removed, and files written there won't be persisted. -![tmpfs on the Docker host](images/types-of-mounts-tmpfs.webp?w=450&h=300) +tmpfs mounts are best used for cases when you do not want the data to persist +either on the host machine or within the container. This may be for security +reasons or to protect the performance of the container when your application +needs to write a large volume of non-persistent state data. -This is useful to temporarily store sensitive files that you don't want to -persist in either the host or the container writable layer. +> [!IMPORTANT] +> tmpfs mounts in Docker map directly to +> [tmpfs](https://en.wikipedia.org/wiki/Tmpfs) in the Linux kernel. As such, +> the temporary data may be written to a swap file, and thereby persisted to +> the filesystem. + +## Mounting over existing data + +If you create a tmpfs mount into a directory in the container in which files or +directories exist, the pre-existing files are obscured by the mount. This is +similar to if you were to save files into `/mnt` on a Linux host, and then +mounted a USB drive into `/mnt`. The contents of `/mnt` would be obscured by +the contents of the USB drive until the USB drive was unmounted. + +With containers, there's no straightforward way of removing a mount to reveal +the obscured files again. Your best option is to recreate the container without +the mount. ## Limitations of tmpfs mounts -* Unlike volumes and bind mounts, you can't share `tmpfs` mounts between -containers. -* This functionality is only available if you're running Docker on Linux. -* Setting permissions on tmpfs may cause them to [reset after container restart](https://github.com/docker/for-linux/issues/138). In some cases [setting the uid/gid](https://github.com/docker/compose/issues/3425#issuecomment-423091370) can serve as a workaround. +- Unlike volumes and bind mounts, you can't share tmpfs mounts between containers. +- This functionality is only available if you're running Docker on Linux. +- Setting permissions on tmpfs may cause them to [reset after container restart](https://github.com/docker/for-linux/issues/138). In some cases [setting the uid/gid](https://github.com/docker/compose/issues/3425#issuecomment-423091370) can serve as a workaround. -## Choose the --tmpfs or --mount flag +## Syntax -In general, `--mount` is more explicit and verbose. The biggest difference is -that the `--tmpfs` flag does not support any configurable options. +To mount a tmpfs with the `docker run` command, you can use either the +`--mount` or `--tmpfs` flag. -- `--tmpfs`: Mounts a `tmpfs` mount without allowing you to specify any - configurable options, and can only be used with standalone containers. +```console +$ docker run --mount type=tmpfs,dst= +$ docker run --tmpfs +``` -- `--mount`: Consists of multiple key-value pairs, separated by commas and each - consisting of a `=` tuple. The `--mount` syntax is more verbose - than `--tmpfs`: - - The `type` of the mount, which can be [`bind`](bind-mounts.md), `volume`, or - [`tmpfs`](tmpfs.md). This topic discusses `tmpfs`, so the type is always - `tmpfs`. - - The `destination` takes as its value the path where the `tmpfs` mount - is mounted in the container. May be specified as `destination`, `dst`, - or `target`. - - The `tmpfs-size` and `tmpfs-mode` options. See - [tmpfs options](#specify-tmpfs-options). +In general, `--mount` is preferred. The main difference is that the `--mount` +flag is more explicit. On the other hand, `--tmpfs` is less verbose and gives +you more flexibility as it lets you set more mount options. -The examples below show both the `--mount` and `--tmpfs` syntax where possible, -and `--mount` is presented first. +The `--tmpfs` flag cannot be used with swarm services. You must use `--mount`. -### Differences between `--tmpfs` and `--mount` behavior +### Options for --tmpfs -- The `--tmpfs` flag does not allow you to specify any configurable options. -- The `--tmpfs` flag cannot be used with swarm services. You must use `--mount`. +The `--tmpfs` flag consists of two fields, separated by a colon character +(`:`). + +```console +$ docker run --tmpfs [:opts] +``` + +The first field is the container path to mount into a tmpfs. The second field +is optional and lets you set mount options. Valid mount options for `--tmpfs` +include: + +| Option | Description | +| ------------ | ------------------------------------------------------------------------------------------- | +| `ro` | Creates a read-only tmpfs mount. | +| `rw` | Creates a read-write tmpfs mount (default behavior). | +| `nosuid` | Prevents `setuid` and `setgid` bits from being honored during execution. | +| `suid` | Allows `setuid` and `setgid` bits to be honored during execution (default behavior). | +| `nodev` | Device files can be created but are not functional (access results in an error). | +| `dev` | Device files can be created and are fully functional. | +| `exec` | Allows the execution of executable binaries in the mounted file system. | +| `noexec` | Does not allow the execution of executable binaries in the mounted file system. | +| `sync` | All I/O to the file system is done synchronously. | +| `async` | All I/O to the file system is done asynchronously (default behavior). | +| `dirsync` | Directory updates within the file system are done synchronously. | +| `atime` | Updates file access time each time the file is accessed. | +| `noatime` | Does not update file access times when the file is accessed. | +| `diratime` | Updates directory access times each time the directory is accessed. | +| `nodiratime` | Does not update directory access times when the directory is accessed. | +| `size` | Specifies the size of the tmpfs mount, for example, `size=64m`. | +| `mode` | Specifies the file mode (permissions) for the tmpfs mount (for example, `mode=1777`). | +| `uid` | Specifies the user ID for the owner of the tmpfs mount (for example, `uid=1000`). | +| `gid` | Specifies the group ID for the owner of the tmpfs mount (for example, `gid=1000`). | +| `nr_inodes` | Specifies the maximum number of inodes for the tmpfs mount (for example, `nr_inodes=400k`). | +| `nr_blocks` | Specifies the maximum number of blocks for the tmpfs mount (for example, `nr_blocks=1024`). | + +```console {title="Example"} +$ docker run --tmpfs /data:noexec,size=1024,mode=1777 +``` + +Not all tmpfs mount features available in the Linux mount command are supported +with the `--tmpfs` flag. If you require advanced tmpfs options or features, you +may need to use a privileged container or configure the mount outside of +Docker. + +> [!CAUTION] +> Running containers with `--privileged` grants elevated permissions and can +> expose the host system to security risks. Use this option only when +> absolutely necessary and in trusted environments. + +```console +$ docker run --privileged -it debian sh +/# mount -t tmpfs -o tmpfs /data +``` + +### Options for --mount + +The `--mount` flag consists of multiple key-value pairs, separated by commas +and each consisting of a `=` tuple. The order of the keys isn't +significant. + +```console +$ docker run --mount type=tmpfs,dst=[,=...] +``` + +Valid options for `--mount type=tmpfs` include: + +| Option | Description | +| :----------------------------- | :--------------------------------------------------------------------------------------------------------------------- | +| `destination`, `dst`, `target` | Size of the tmpfs mount in bytes. If unset, the default maximum size of a tmpfs volume is 50% of the host's total RAM. | +| `tmpfs-size` | Size of the tmpfs mount in bytes. If unset, the default maximum size of a tmpfs volume is 50% of the host's total RAM. | +| `tmpfs-mode` | File mode of the tmpfs in octal. For instance, `700` or `0770`. Defaults to `1777` or world-writable. | + +```console {title="Example"} +$ docker run --mount type=tmpfs,dst=/app,tmpfs-size=21474836480,tmpfs-mode=1770 +``` ## Use a tmpfs mount in a container @@ -79,6 +162,14 @@ $ docker run -d \ nginx:latest ``` +Verify that the mount is a `tmpfs` mount by looking in the `Mounts` section of +the `docker inspect` output: + +```console +$ docker inspect tmptest --format '{{ json .Mounts }}' +[{"Type":"tmpfs","Source":"","Destination":"/app","Mode":"","RW":true,"Propagation":""}] +``` + {{< /tab >}} {{< tab name="`--tmpfs`" >}} @@ -90,17 +181,17 @@ $ docker run -d \ nginx:latest ``` -{{< /tab >}} -{{< /tabs >}} - Verify that the mount is a `tmpfs` mount by looking in the `Mounts` section of the `docker inspect` output: ```console $ docker inspect tmptest --format '{{ json .Mounts }}' -[{"Type":"tmpfs","Source":"","Destination":"/app","Mode":"","RW":true,"Propagation":""}] +{"/app":""} ``` +{{< /tab >}} +{{< /tabs >}} + Stop and remove the container: ```console @@ -108,28 +199,6 @@ $ docker stop tmptest $ docker rm tmptest ``` -### Specify tmpfs options - -`tmpfs` mounts allow for two configuration options, neither of which is -required. If you need to specify these options, you must use the `--mount` flag, -as the `--tmpfs` flag does not support them. - -| Option | Description | -|:-------------|:--------------------------------------------------------------------------------------------------------------------------| -| `tmpfs-size` | Size of the tmpfs mount in bytes. If unset, the default maximum size of a tmpfs volume is 50% of the host's total RAM. | -| `tmpfs-mode` | File mode of the tmpfs in octal. For instance, `700` or `0770`. Defaults to `1777` or world-writable. | - -The following example sets the `tmpfs-mode` to `1770`, so that it is not -world-readable within the container. - -```console -docker run -d \ - -it \ - --name tmptest \ - --mount type=tmpfs,destination=/app,tmpfs-mode=1770 \ - nginx:latest -``` - ## Next steps - Learn about [volumes](volumes.md) diff --git a/content/manuals/engine/storage/volumes.md b/content/manuals/engine/storage/volumes.md index d682e4300e7..c99eed561d8 100644 --- a/content/manuals/engine/storage/volumes.md +++ b/content/manuals/engine/storage/volumes.md @@ -1,38 +1,55 @@ --- -description: Learn how to create, manage, and use volumes instead of bind mounts for +description: + Learn how to create, manage, and use volumes instead of bind mounts for persisting data generated and used by Docker. title: Volumes weight: 10 -keywords: docker compose volumes, docker volumes, docker compose volume, docker volume +keywords: + docker compose volumes, docker volumes, docker compose volume, docker volume mount, docker mount volume, docker volume create, docker volume location aliases: -- /userguide/dockervolumes/ -- /engine/tutorials/dockervolumes/ -- /engine/userguide/dockervolumes/ -- /engine/admin/volumes/volumes/ -- /storage/volumes/ + - /userguide/dockervolumes/ + - /engine/tutorials/dockervolumes/ + - /engine/userguide/dockervolumes/ + - /engine/admin/volumes/volumes/ + - /storage/volumes/ --- +Volumes are persistent data stores for containers, created and managed by +Docker. You can create a volume explicitly using the `docker volume create` +command, or Docker can create a volume during container or service creation. + +When you create a volume, it's stored within a directory on the Docker +host. When you mount the volume into a container, this directory is what's +mounted into the container. This is similar to the way that bind mounts work, +except that volumes are managed by Docker and are isolated from the core +functionality of the host machine. + +## When to use volumes + Volumes are the preferred mechanism for persisting data generated by and used by Docker containers. While [bind mounts](bind-mounts.md) are dependent on the directory structure and OS of the host machine, volumes are completely managed by -Docker. Volumes have several advantages over bind mounts: +Docker. Volumes are a good choice for the following use cases: - Volumes are easier to back up or migrate than bind mounts. - You can manage volumes using Docker CLI commands or the Docker API. - Volumes work on both Linux and Windows containers. - Volumes can be more safely shared among multiple containers. -- Volume drivers let you store volumes on remote hosts or cloud providers, encrypt the contents of volumes, or add other functionality. -- New volumes can have their content pre-populated by a container. -- Volumes on Docker Desktop have much higher performance than bind mounts from - Mac and Windows hosts. +- New volumes can have their content pre-populated by a container or build. +- When your application requires high-performance I/O. -In addition, volumes are often a better choice than persisting data in a -container's writable layer, because a volume doesn't increase the size of the -containers using it, and the volume's contents exist outside the lifecycle of a -given container. +Volumes are not a good choice if you need to access the files from the host, as +the volume is completely managed by Docker. Use [bind mounts](bind-mounts.md) +if you need to access files or directories from both containers and the host. -![Volumes on the Docker host](images/types-of-mounts-volume.webp?w=450&h=300) +Volumes are often a better choice than writing data directly to a container, +because a volume doesn't increase the size of the containers using it. Using a +volume is also faster; writing into a container's writable layer requires a +[storage driver](/manuals/engine/storage/drivers/_index.md) to manage the +filesystem. The storage driver provides a union filesystem, using the Linux +kernel. This extra abstraction reduces performance as compared to using +volumes, which write directly to the host filesystem. If your container generates non-persistent state data, consider using a [tmpfs mount](tmpfs.md) to avoid storing the data anywhere permanently, and to @@ -42,74 +59,122 @@ writable layer. Volumes use `rprivate` bind propagation, and bind propagation isn't configurable for volumes. -## Choose the -v or --mount flag - -In general, `--mount` is more explicit and verbose. The biggest difference is that -the `-v` syntax combines all the options together in one field, while the `--mount` -syntax separates them. Here is a comparison of the syntax for each flag. - -If you need to specify volume driver options, you must use `--mount`. - -- `-v` or `--volume`: Consists of three fields, separated by colon characters - (`:`). The fields must be in the correct order, and the meaning of each field - isn't immediately obvious. - - - In the case of named volumes, the first field is the name of the volume, and is - unique on a given host machine. For anonymous volumes, the first field is - omitted. - - The second field is the path where the file or directory is mounted in - the container. - - The third field is optional, and is a comma-separated list of options, such - as `ro`. These options are discussed below. - -- `--mount`: Consists of multiple key-value pairs, separated by commas and each - consisting of a `=` tuple. The `--mount` syntax is more verbose - than `-v` or `--volume`, but the order of the keys isn't significant, and - the value of the flag is easier to understand. - - The `type` of the mount, which can be [`bind`](bind-mounts.md), `volume`, or - [`tmpfs`](tmpfs.md). This topic discusses volumes, so the type is always - `volume`. - - The `source` of the mount. For named volumes, this is the name of the volume. - For anonymous volumes, this field is omitted. Can be specified as `source` - or `src`. - - The `destination` takes as its value the path where the file or directory - is mounted in the container. Can be specified as `destination`, `dst`, - or `target`. - - The `volume-subpath` option takes a path to a subdirectory within the - volume to mount into the container. The subdirectory must exist in the - volume before the volume is mounted to a container. - See [Mount a volume subdirectory](#mount-a-volume-subdirectory). - - The `readonly` option, if present, causes the bind mount to be [mounted into - the container as read-only](#use-a-read-only-volume). Can be specified as `readonly` or `ro`. - - The `volume-opt` option, which can be specified more than once, takes a - key-value pair consisting of the option name and its value. - -> [!WARNING] -> -> If your volume driver accepts a comma-separated list as an option, -> you must escape the value from the outer CSV parser. To escape a `volume-opt`, -> surround it with double quotes (`"`) and surround the entire mount parameter -> with single quotes (`'`). -> -> For example, the `local` driver accepts mount options as a comma-separated -> list in the `o` parameter. This example shows the correct way to escape the list. -> -> ```console -> $ docker service create \ -> --mount 'type=volume,src=,dst=,volume-driver=local,volume-opt=type=nfs,volume-opt=device=:,"volume-opt=o=addr=,vers=4,soft,timeo=180,bg,tcp,rw"' -> --name myservice \ -> -> ``` +## A volume's lifecycle + +A volume's contents exist outside the lifecycle of a given container. When a +container is destroyed, the writable layer is destroyed with it. Using a volume +ensures that the data is persisted even if the container using it is removed. + +A given volume can be mounted into multiple containers simultaneously. When no +running container is using a volume, the volume is still available to Docker +and isn't removed automatically. You can remove unused volumes using `docker +volume prune`. + +## Mounting a volume over existing data + +If you mount a _non-empty volume_ into a directory in the container in which +files or directories exist, the pre-existing files are obscured by the mount. +This is similar to if you were to save files into `/mnt` on a Linux host, and +then mounted a USB drive into `/mnt`. The contents of `/mnt` would be obscured +by the contents of the USB drive until the USB drive was unmounted. + +With containers, there's no straightforward way of removing a mount to reveal +the obscured files again. Your best option is to recreate the container without +the mount. + +If you mount an _empty volume_ into a directory in the container in which files +or directories exist, these files or directories are propagated (copied) into +the volume by default. Similarly, if you start a container and specify a volume +which does not already exist, an empty volume is created for you. This is a +good way to pre-populate data that another container needs. + +To prevent Docker from copying a container's pre-existing files into an empty +volume, use the `volume-nocopy` option, see [Options for --mount](#options-for---mount). + +## Named and anonymous volumes + +A volume may be named or anonymous. Anonymous volumes are given a random name +that's guaranteed to be unique within a given Docker host. Just like named +volumes, anonymous volumes persist even if you remove the container that uses +them, except if you use the `--rm` flag when creating the container, in which +case the anonymous volume associated with the container is destroyed. See +[Remove anonymous volumes](volumes.md#remove-anonymous-volumes). + +If you create multiple containers consecutively that each use anonymous +volumes, each container creates its own volume. Anonymous volumes aren't reused +or shared between containers automatically. To share an anonymous volume +between two or more containers, you must mount the anonymous volume using the +random volume ID. + +## Syntax + +To mount a volume with the `docker run` command, you can use either the +`--mount` or `--volume` flag. + +```console +$ docker run --mount type=volume,src=,dst= +$ docker run --volume : +``` + +In general, `--mount` is preferred. The main difference is that the `--mount` +flag is more explicit and supports all the available options. + +You must use `--mount` if you want to: -The examples below show both the `--mount` and `-v` syntax where possible, with -`--mount` first. +- Specify [volume driver options](#use-a-volume-driver) +- Mount a [volume subdirectory](#mount-a-volume-subdirectory) +- Mount a volume into a Swarm service -### Differences between `-v` and `--mount` behavior +### Options for --mount -As opposed to bind mounts, all options for volumes are available for both -`--mount` and `-v` flags. +The `--mount` flag consists of multiple key-value pairs, separated by commas +and each consisting of a `=` tuple. The order of the keys isn't +significant. -Volumes used with services, only support `--mount`. +```console +$ docker run --mount type=volume[,src=],dst=[,=...] +``` + +Valid options for `--mount type=volume` include: + +| Option | Description | +| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `source`, `src` | The source of the mount. For named volumes, this is the name of the volume. For anonymous volumes, this field is omitted. | +| `destination`, `dst`, `target` | The path where the file or directory is mounted in the container. | +| `volume-subpath` | A path to a subdirectory within the volume to mount into the container. The subdirectory must exist in the volume before the volume is mounted to a container. See [Mount a volume subdirectory](#mount-a-volume-subdirectory). | +| `readonly`, `ro` | If present, causes the volume to be [mounted into the container as read-only](#use-a-read-only-volume). | +| `volume-nocopy` | If present, data at the destination isn't copied into the volume if the volume is empty. By default, content at the target destination gets copied into a mounted volume if empty. | +| `volume-opt` | Can be specified more than once, takes a key-value pair consisting of the option name and its value. | + +```console {title="Example"} +$ docker run --mount type=volume,src=myvolume,dst=/data,ro,volume-subpath=/foo +``` + +### Options for --volume + +The `--volume` or `-v` flag consists of three fields, separated by colon +characters (`:`). The fields must be in the correct order. + +```console +$ docker run -v [:][:opts] +``` + +In the case of named volumes, the first field is the name of the volume, and is +unique on a given host machine. For anonymous volumes, the first field is +omitted. The second field is the path where the file or directory is mounted in +the container. + +The third field is optional, and is a comma-separated list of options. Valid +options for `--volume` with a data volume include: + +| Option | Description | +| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `readonly`, `ro` | If present, causes the volume to be [mounted into the container as read-only](#use-a-read-only-volume). | +| `volume-nocopy` | If present, data at the destination isn't copied into the volume if the volume is empty. By default, content at the target destination gets copied into a mounted volume if empty. | + +```console {title="Example"} +$ docker run -v myvolume:/data:ro +``` ## Create and manage volumes @@ -158,8 +223,8 @@ If you start a container with a volume that doesn't yet exist, Docker creates the volume for you. The following example mounts the volume `myvol2` into `/app/` in the container. -The `-v` and `--mount` examples below produce the same result. You can't run -them both unless you remove the `devtest` container and the `myvol2` volume +The following `-v` and `--mount` examples produce the same result. You can't +run them both unless you remove the `devtest` container and the `myvol2` volume after running the first one. {{< tabs >}} @@ -219,7 +284,7 @@ $ docker volume rm myvol2 ## Use a volume with Docker Compose -The example below shows a single Docker Compose service with a volume: +The following example shows a single Docker Compose service with a volume: ```yaml services: @@ -286,12 +351,6 @@ $ docker service rm devtest-service Removing the service doesn't remove any volumes created by the service. Volume removal is a separate step. -#### Syntax differences for services - -The `docker service create` command doesn't support the `-v` or `--volume` flag. -When mounting a volume into a service's containers, you must use the `--mount` -flag. - ### Populate a volume using a container If you start a container which creates a new volume, and the container @@ -349,7 +408,7 @@ the container only needs read access to the data. Multiple containers can mount the same volume. You can simultaneously mount a single volume as `read-write` for some containers and as `read-only` for others. -The following example changes the one above. It mounts the directory as a read-only +The following example changes the previous one. It mounts the directory as a read-only volume, by adding `ro` to the (empty by default) list of options, after the mount point within the container. Where multiple options are present, you can separate them using commas. @@ -457,7 +516,7 @@ One is to add logic to your application to store files on a cloud object storage system like Amazon S3. Another is to create volumes with a driver that supports writing files to an external storage system like NFS or Amazon S3. -Volume drivers allow you to abstract the underlying storage system from the +Volume drivers let you abstract the underlying storage system from the application logic. For example, if your services use a volume with an NFS driver, you can update the services to use a different driver. For example, to store data in the cloud, without changing the application logic. @@ -470,6 +529,23 @@ The following examples use the `vieux/sshfs` volume driver, first when creating a standalone volume, and then when starting a container which creates a new volume. +> [!NOTE] +> +> If your volume driver accepts a comma-separated list as an option, +> you must escape the value from the outer CSV parser. To escape a `volume-opt`, +> surround it with double quotes (`"`) and surround the entire mount parameter +> with single quotes (`'`). +> +> For example, the `local` driver accepts mount options as a comma-separated +> list in the `o` parameter. This example shows the correct way to escape the list. +> +> ```console +> $ docker service create \ +> --mount 'type=volume,src=,dst=,volume-driver=local,volume-opt=type=nfs,volume-opt=device=:,"volume-opt=o=addr=,vers=4,soft,timeo=180,bg,tcp,rw"' +> --name myservice \ +> +> ``` + ### Initial setup The following example assumes that you have two nodes, the first of which is a Docker @@ -579,7 +655,7 @@ $ mount -t -o **Important** + > [!IMPORTANT] > - > Adding more managers does NOT mean increased - > scalability or higher performance. In general, the opposite is true. + > Adding more managers does NOT mean increased scalability or higher performance. In general, the opposite is true. ## Worker nodes diff --git a/content/manuals/engine/swarm/services.md b/content/manuals/engine/swarm/services.md index 139a6c7b69c..711639b7866 100644 --- a/content/manuals/engine/swarm/services.md +++ b/content/manuals/engine/swarm/services.md @@ -762,7 +762,7 @@ $ docker service create \ --replicas 9 \ --name redis_2 \ --placement-pref 'spread=node.labels.datacenter' \ - redis:3.0.6 + redis:7.4.0 ``` > [!NOTE] @@ -786,7 +786,7 @@ $ docker service create \ --name redis_2 \ --placement-pref 'spread=node.labels.datacenter' \ --placement-pref 'spread=node.labels.rack' \ - redis:3.0.6 + redis:7.4.0 ``` You can also use placement preferences in conjunction with placement constraints diff --git a/content/manuals/engine/swarm/swarm-tutorial/_index.md b/content/manuals/engine/swarm/swarm-tutorial/_index.md index a0ae8ea367a..88c8ab6f9a8 100644 --- a/content/manuals/engine/swarm/swarm-tutorial/_index.md +++ b/content/manuals/engine/swarm/swarm-tutorial/_index.md @@ -39,11 +39,9 @@ Amazon EC2 instances, or hosted in some other way. Check out One of these machines is a manager (called `manager1`) and two of them are workers (`worker1` and `worker2`). ->**Note** +> [!NOTE] > -> You can follow many of the tutorial steps to test single-node swarm -> as well, in which case you need only one host. Multi-node commands do not -> work, but you can initialize a swarm, create services, and scale them. +> You can follow many of the tutorial steps to test single-node swarm as well, in which case you need only one host. Multi-node commands do not work, but you can initialize a swarm, create services, and scale them. #### Install Docker Engine on Linux machines diff --git a/content/manuals/engine/swarm/swarm-tutorial/drain-node.md b/content/manuals/engine/swarm/swarm-tutorial/drain-node.md index 74a596a5e06..1e412606a1e 100644 --- a/content/manuals/engine/swarm/swarm-tutorial/drain-node.md +++ b/content/manuals/engine/swarm/swarm-tutorial/drain-node.md @@ -41,7 +41,7 @@ node and launches replica tasks on a node with `Active` availability. [rolling update](rolling-update.md) tutorial, start it now: ```console - $ docker service create --replicas 3 --name redis --update-delay 10s redis:3.0.6 + $ docker service create --replicas 3 --name redis --update-delay 10s redis:7.4.0 c5uo6kdmzpon37mgj9mwglcfw ``` @@ -53,9 +53,9 @@ tasks to different nodes: $ docker service ps redis NAME IMAGE NODE DESIRED STATE CURRENT STATE - redis.1.7q92v0nr1hcgts2amcjyqg3pq redis:3.0.6 manager1 Running Running 26 seconds - redis.2.7h2l8h3q3wqy5f66hlv9ddmi6 redis:3.0.6 worker1 Running Running 26 seconds - redis.3.9bg7cezvedmkgg6c8yzvbhwsd redis:3.0.6 worker2 Running Running 26 seconds + redis.1.7q92v0nr1hcgts2amcjyqg3pq redis:7.4.0 manager1 Running Running 26 seconds + redis.2.7h2l8h3q3wqy5f66hlv9ddmi6 redis:7.4.0 worker1 Running Running 26 seconds + redis.3.9bg7cezvedmkgg6c8yzvbhwsd redis:7.4.0 worker2 Running Running 26 seconds ``` In this case the swarm manager distributed one task to each node. You may @@ -92,10 +92,10 @@ task assignments for the `redis` service: $ docker service ps redis NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR - redis.1.7q92v0nr1hcgts2amcjyqg3pq redis:3.0.6 manager1 Running Running 4 minutes - redis.2.b4hovzed7id8irg1to42egue8 redis:3.0.6 worker2 Running Running About a minute - \_ redis.2.7h2l8h3q3wqy5f66hlv9ddmi6 redis:3.0.6 worker1 Shutdown Shutdown 2 minutes ago - redis.3.9bg7cezvedmkgg6c8yzvbhwsd redis:3.0.6 worker2 Running Running 4 minutes + redis.1.7q92v0nr1hcgts2amcjyqg3pq redis:7.4.0 manager1 Running Running 4 minutes + redis.2.b4hovzed7id8irg1to42egue8 redis:7.4.0 worker2 Running Running About a minute + \_ redis.2.7h2l8h3q3wqy5f66hlv9ddmi6 redis:7.4.0 worker1 Shutdown Shutdown 2 minutes ago + redis.3.9bg7cezvedmkgg6c8yzvbhwsd redis:7.4.0 worker2 Running Running 4 minutes ``` The swarm manager maintains the desired state by ending the task on a node diff --git a/content/manuals/engine/swarm/swarm-tutorial/inspect-service.md b/content/manuals/engine/swarm/swarm-tutorial/inspect-service.md index 2288c7c37b2..49f9e441609 100644 --- a/content/manuals/engine/swarm/swarm-tutorial/inspect-service.md +++ b/content/manuals/engine/swarm/swarm-tutorial/inspect-service.md @@ -35,7 +35,7 @@ the Docker CLI to see details about the service running in the swarm. Endpoint Mode: vip ``` - >**Tip** + > [!TIP] > > To return the service details in json format, run the same command without the `--pretty` flag. @@ -110,7 +110,7 @@ the Docker CLI to see details about the service running in the swarm. 4. Run `docker ps` on the node where the task is running to see details about the container for the task. - >**Tip** + > [!TIP] > > If `helloworld` is running on a node other than your manager node, you must ssh to that node. diff --git a/content/manuals/engine/swarm/swarm-tutorial/rolling-update.md b/content/manuals/engine/swarm/swarm-tutorial/rolling-update.md index 49676e49e58..e00be072926 100644 --- a/content/manuals/engine/swarm/swarm-tutorial/rolling-update.md +++ b/content/manuals/engine/swarm/swarm-tutorial/rolling-update.md @@ -8,8 +8,8 @@ notoc: true In a previous step of the tutorial, you [scaled](scale-service.md) the number of instances of a service. In this part of the tutorial, you deploy a service based -on the Redis 3.0.6 container tag. Then you upgrade the service to use the -Redis 3.0.7 container image using rolling updates. +on the Redis 7.4.0 container tag. Then you upgrade the service to use the +Redis 7.4.1 container image using rolling updates. 1. If you haven't already, open a terminal and ssh into the machine where you run your manager node. For example, the tutorial uses a machine named @@ -23,7 +23,7 @@ Redis 3.0.7 container image using rolling updates. --replicas 3 \ --name redis \ --update-delay 10s \ - redis:3.0.6 + redis:7.4.0 0u6a4s31ybk7yw2wyvtikmu50 ``` @@ -61,7 +61,7 @@ Redis 3.0.7 container image using rolling updates. Parallelism: 1 Delay: 10s ContainerSpec: - Image: redis:3.0.6 + Image: redis:7.4.0 Resources: Endpoint Mode: vip ``` @@ -70,7 +70,7 @@ Redis 3.0.7 container image using rolling updates. applies the update to nodes according to the `UpdateConfig` policy: ```console - $ docker service update --image redis:3.0.7 redis + $ docker service update --image redis:7.4.1 redis redis ``` @@ -100,7 +100,7 @@ Redis 3.0.7 container image using rolling updates. Parallelism: 1 Delay: 10s ContainerSpec: - Image: redis:3.0.7 + Image: redis:7.4.1 Resources: Endpoint Mode: vip ``` @@ -135,16 +135,16 @@ Redis 3.0.7 container image using rolling updates. $ docker service ps redis NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR - redis.1.dos1zffgeofhagnve8w864fco redis:3.0.7 worker1 Running Running 37 seconds - \_ redis.1.88rdo6pa52ki8oqx6dogf04fh redis:3.0.6 worker2 Shutdown Shutdown 56 seconds ago - redis.2.9l3i4j85517skba5o7tn5m8g0 redis:3.0.7 worker2 Running Running About a minute - \_ redis.2.66k185wilg8ele7ntu8f6nj6i redis:3.0.6 worker1 Shutdown Shutdown 2 minutes ago - redis.3.egiuiqpzrdbxks3wxgn8qib1g redis:3.0.7 worker1 Running Running 48 seconds - \_ redis.3.ctzktfddb2tepkr45qcmqln04 redis:3.0.6 mmanager1 Shutdown Shutdown 2 minutes ago + redis.1.dos1zffgeofhagnve8w864fco redis:7.4.1 worker1 Running Running 37 seconds + \_ redis.1.88rdo6pa52ki8oqx6dogf04fh redis:7.4.0 worker2 Shutdown Shutdown 56 seconds ago + redis.2.9l3i4j85517skba5o7tn5m8g0 redis:7.4.1 worker2 Running Running About a minute + \_ redis.2.66k185wilg8ele7ntu8f6nj6i redis:7.4.0 worker1 Shutdown Shutdown 2 minutes ago + redis.3.egiuiqpzrdbxks3wxgn8qib1g redis:7.4.1 worker1 Running Running 48 seconds + \_ redis.3.ctzktfddb2tepkr45qcmqln04 redis:7.4.0 mmanager1 Shutdown Shutdown 2 minutes ago ``` Before Swarm updates all of the tasks, you can see that some are running - `redis:3.0.6` while others are running `redis:3.0.7`. The output above shows + `redis:7.4.0` while others are running `redis:7.4.1`. The output above shows the state once the rolling updates are done. ## Next steps diff --git a/content/manuals/extensions/_index.md b/content/manuals/extensions/_index.md index c3fbb6fc116..92beb943cb3 100644 --- a/content/manuals/extensions/_index.md +++ b/content/manuals/extensions/_index.md @@ -1,9 +1,11 @@ --- -title: Overview of Docker Extensions -linkTitle: Docker Extensions -weight: 100 +title: Docker Extensions +weight: 60 description: Extensions keywords: Docker Extensions, Docker Desktop, Linux, Mac, Windows +params: + sidebar: + group: Products aliases: - /desktop/extensions/ --- diff --git a/content/manuals/extensions/settings-feedback.md b/content/manuals/extensions/settings-feedback.md index c430289f7ae..e1f672489ab 100644 --- a/content/manuals/extensions/settings-feedback.md +++ b/content/manuals/extensions/settings-feedback.md @@ -19,9 +19,9 @@ Docker Extensions is switched on by default. To change your settings: 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**. ->**Note** +> [!NOTE] > -> If you are an [organization owner](/manuals/admin/organization/manage-a-team.md#organization-owner), you can turn off extensions for your users. Open the `settings-store.json` file, and set `"extensionsEnabled"` to `false`. +> If you are an [organization owner](/manuals/admin/organization/manage-a-team.md#organization-owner), you can turn off extensions for your users. Open the `settings-store.json` file, and set `"extensionsEnabled"` to `false`. > The `settings-store.json` file (or `settings.json` for Docker Desktop versions 4.34 and earlier) is located at: > - `~/Library/Group Containers/group.com.docker/settings-store.json` on Mac > - `C:\Users\[USERNAME]\AppData\Roaming\Docker\settings-store.json` on Windows diff --git a/content/manuals/harmonia/_index.md b/content/manuals/harmonia/_index.md index ab615153261..b3a6b88d5f4 100644 --- a/content/manuals/harmonia/_index.md +++ b/content/manuals/harmonia/_index.md @@ -3,6 +3,9 @@ title: Project Harmonia description: Learn how you can run your applications in the cloud with Project Harmonia keywords: run, cloud, docker desktop, resources sitemap: false +params: + sidebar: + group: Products aliases: - /run-cloud/ --- @@ -138,7 +141,7 @@ Running a container with a cloud engine is just as straightforward as running it ### Step four: Use a file sync for your cloud engine -Project Harmonia takes advantage of [Synchronized file shares](/manuals/desktop/synchronized-file-sharing.md) to enable local-to-remote file shares and port mappings. +Project Harmonia takes advantage of [Synchronized file shares](/manuals/desktop/features/synchronized-file-sharing.md) to enable local-to-remote file shares and port mappings. {{< tabs group="method" >}} {{< tab name="Docker Desktop">}} @@ -260,7 +263,9 @@ Run `docker harmonia doctor` to print helpful troubleshooting information. - KinD does not run on Project Harmonia due to some hard-coded assumptions to ensure it's running in a privileged container. K3d is a good alternative. - Containers cannot access host through DNS `host.docker.internal`. - File binds (non-directory binds) are currently static, meaning changes will not be reflected until the container is restarted. This also affects Compose configs and secrets directives. -- Bind volumes are not supported. +- Bind _mounts_, such as `-v /localpath:/incontainer` in the `docker run` command, require creating a file-sync. +- Creating a [synchronized file share](/manuals/desktop/features/synchronized-file-sharing.md) for a directory with a large amount of may take extra time to sync and become ready for use in a container. +- Bind _volumes_, such as those created with `docker volume create --driver local --opt type=none --opt o=bind --opt device=/some/host/path myvolname` or via the compose equivalent, are not supported. - Port-forwarding for UDP is not supported. - Docker Compose projects relying on `watch` in `sync` mode are not working with the `tar` synchronizer. Configure it to use `docker cp` instead, disable tar sync by setting `COMPOSE_EXPERIMENTAL_WATCH_TAR=0` in your environment. - Some Docker Engine features that let you access the underlying host, such as `--pid=host`, `--network=host`, and `--ipc=host`, are currently disabled. diff --git a/content/manuals/registry.md b/content/manuals/registry.md index c4b34bef8be..ac668945ee4 100644 --- a/content/manuals/registry.md +++ b/content/manuals/registry.md @@ -2,6 +2,9 @@ title: Registry description: The Docker Hub registry implementation keywords: registry, distribution, docker hub, spec, schema, api, manifest, auth +params: + sidebar: + group: Open source aliases: - /registry/compatibility/ - /registry/configuration/ @@ -41,7 +44,7 @@ aliases: > [!IMPORTANT] > -> The ability to push [deprecated Docker image manifest version 2, schema 1](https://distribution.github.io/distribution/spec/deprecated-schema-v1/) images to Docker Hub will be deprecated on November 4th, 2024. +> The ability to push [deprecated Docker image manifest version 2, schema 1](https://distribution.github.io/distribution/spec/deprecated-schema-v1/) images to Docker Hub is deprecated as of November 4th, 2024. Registry, the open source implementation for storing and distributing container images and other content, has been donated to the CNCF. Registry now goes under @@ -84,7 +87,7 @@ For documentation related to authentication to the Docker Hub registry, see: [specification]: https://github.com/opencontainers/distribution-spec/blob/v1.0.1/spec.md [OCI image manifest]: https://github.com/opencontainers/image-spec/blob/main/manifest.md [Docker image manifest version 2, schema 2]: https://distribution.github.io/distribution/spec/manifest-v2-2/ -[OCI artifacts]: /docker-hub/oci-artifacts/ +[OCI artifacts]: /docker-hub/repos/manage/hub-images/oci-artifacts/ [oauth2]: https://distribution.github.io/distribution/spec/auth/oauth/ [jwt]: https://distribution.github.io/distribution/spec/auth/jwt/ [token]: https://distribution.github.io/distribution/spec/auth/token/ diff --git a/content/manuals/release-lifecycle.md b/content/manuals/release-lifecycle.md index b5b7c22bb04..4b54d2cc3c3 100644 --- a/content/manuals/release-lifecycle.md +++ b/content/manuals/release-lifecycle.md @@ -4,6 +4,9 @@ linkTitle: Release lifecycle description: Describes the various stages of feature lifecycle from beta to GA. keywords: beta, GA, Early Access, +params: + sidebar: + group: Products --- This page details Docker's product release lifecycle and how Docker defines each stage. It also provides information on the product retirement process. Features and products may progress through some or all of these phases. diff --git a/content/manuals/scout/_index.md b/content/manuals/scout/_index.md index e08c4253be8..a7e3c3b3cd6 100644 --- a/content/manuals/scout/_index.md +++ b/content/manuals/scout/_index.md @@ -1,11 +1,14 @@ --- title: Docker Scout -weight: 100 +weight: 40 keywords: scout, supply chain, vulnerabilities, packages, cves, scan, analysis, analyze description: Get an overview on Docker Scout to proactively enhance your software supply chain security aliases: - /engine/scan/ +params: + sidebar: + group: Products grid: - title: Quickstart link: /scout/quickstart/ @@ -35,9 +38,9 @@ grid: Ensure that your artifacts align with supply chain best practices. icon: policy - title: Upgrade - link: /billing/scout-billing/ + link: /subscription/change/ description: | - The free plan includes up to 3 repositories. Upgrade for more. + The free plan includes up to 1 repository. Upgrade for more. icon: upgrade --- diff --git a/content/manuals/scout/deep-dive/advisory-db-sources.md b/content/manuals/scout/deep-dive/advisory-db-sources.md index feb50a30e00..ee85f2039f2 100644 --- a/content/manuals/scout/deep-dive/advisory-db-sources.md +++ b/content/manuals/scout/deep-dive/advisory-db-sources.md @@ -22,32 +22,33 @@ is represented using the latest available information, in real-time. Docker Scout uses the following package repositories and security trackers: -- [Alpine secdb](https://secdb.alpinelinux.org/) + + - [AlmaLinux Security Advisory](https://errata.almalinux.org/) +- [Alpine secdb](https://secdb.alpinelinux.org/) - [Amazon Linux Security Center](https://alas.aws.amazon.com/) - [Bitnami Vulnerability Database](https://github.com/bitnami/vulndb) -- [CISA Known Exploited Vulnerability - Catalog](https://www.cisa.gov/known-exploited-vulnerabilities-catalog) +- [CISA Known Exploited Vulnerability Catalog](https://www.cisa.gov/known-exploited-vulnerabilities-catalog) - [CISA Vulnrichment](https://github.com/cisagov/vulnrichment) +- [Chainguard Security Feed](https://packages.cgr.dev/chainguard/osv/all.json) - [Debian Security Bug Tracker](https://security-tracker.debian.org/tracker/) - [Exploit Prediction Scoring System (EPSS)](https://api.first.org/epss/) - [GitHub Advisory Database](https://github.com/advisories/) -- [GitLab Advisory - Database](https://gitlab.com/gitlab-org/advisories-community/) +- [GitLab Advisory Database](https://gitlab.com/gitlab-org/advisories-community/) - [Golang VulnDB](https://github.com/golang/vulndb) -- [inTheWild, a community-driven open database of vulnerability - exploitation](https://github.com/gmatuz/inthewilddb) - [National Vulnerability Database](https://nvd.nist.gov/) - [Oracle Linux Security](https://linux.oracle.com/security/) -- [Python Packaging Advisory - Database](https://github.com/pypa/advisory-database) +- [Photon OS 3.0 Security Advisories](https://github.com/vmware/photon/wiki/Security-Updates-3) +- [Python Packaging Advisory Database](https://github.com/pypa/advisory-database) - [RedHat Security Data](https://www.redhat.com/security/data/metrics/) - [Rocky Linux Security Advisory](https://errata.rockylinux.org/) - [RustSec Advisory Database](https://github.com/rustsec/advisory-db) - [SUSE Security CVRF](http://ftp.suse.com/pub/projects/security/cvrf/) - [Ubuntu CVE Tracker](https://people.canonical.com/~ubuntu-security/cve/) - [Wolfi Security Feed](https://packages.wolfi.dev/os/security.json) -- [Chainguard Security Feed](https://packages.cgr.dev/chainguard/osv/all.json) +- [inTheWild, a community-driven open database of vulnerability exploitation](https://github.com/gmatuz/inthewilddb) + + When you enable Docker Scout for your Docker organization, a new database instance is provisioned on the Docker Scout platform. diff --git a/content/manuals/scout/explore/analysis.md b/content/manuals/scout/explore/analysis.md index 8f917ff1621..a4f16b2ef37 100644 --- a/content/manuals/scout/explore/analysis.md +++ b/content/manuals/scout/explore/analysis.md @@ -20,8 +20,7 @@ If you run image analysis as a one-off task using the CLI or Docker Desktop, Docker Scout won't store any data about your image. If you enable Docker Scout for your container image repositories however, Docker Scout saves a metadata snapshot of your images after the analysis. -As new vulnerability data becomes available, Docker Scout recalibrates the analysis using the metadata snapshot, -which means your security status for images is updated in real-time. +As new vulnerability data becomes available, Docker Scout recalibrates the analysis using the metadata snapshot, which means your security status for images is updated in real-time. This dynamic evaluation means there's no need to re-analyze images when new CVE information is disclosed. Docker Scout image analysis is available by default for Docker Hub repositories. @@ -30,10 +29,11 @@ see [Integrating Docker Scout with other systems](/manuals/scout/integrations/_i ## Activate Docker Scout on a repository -The free tier of Docker Scout lets you use Docker Scout for up to 3 -repositories per Docker organization. You can update your Docker Scout plan if -you need additional repositories, see [Docker Scout -billing](/manuals/billing/scout-billing.md). +Docker Personal comes with 1 Scout-enabled repository. You can upgrade your +Docker subscription if you need additional repositories. +See [Subscriptions and features](../../subscription/details.md) +to learn how many Scout-enabled +repositories come with each subscription tier. Before you can activate image analysis on a repository in a third-party registry, the registry must be integrated with Docker Scout for your Docker organization. @@ -81,7 +81,7 @@ analysis is activated. > [!NOTE] > > The default `docker` driver only supports build attestations if you use the - > [containerd image store](/manuals/desktop/containerd.md). + > [containerd image store](/manuals/desktop/features/containerd.md). 3. Go to the [Images page](https://scout.docker.com/reports/images) in the Docker Scout Dashboard. diff --git a/content/manuals/scout/explore/dashboard.md b/content/manuals/scout/explore/dashboard.md index 49992ec06fb..af6d75e4e65 100644 --- a/content/manuals/scout/explore/dashboard.md +++ b/content/manuals/scout/explore/dashboard.md @@ -45,7 +45,7 @@ sections of the Docker Scout Dashboard: - **Packages**: lists all packages across repositories in the organization - **Vulnerabilities**: lists all CVEs in the organization's images, see [Vulnerabilities](#vulnerabilities) - **Integrations**: create and manage third-party integrations, see [Integrations](#integrations) -- **Settings**: manage repository and billing settings, see [Settings](#settings) +- **Settings**: manage repository settings, see [Settings](#settings) ## Policies @@ -112,20 +112,9 @@ more information on how to get started with integrations, see The settings menu in the Docker Scout Dashboard contains: -- [**Billing**](#billing-settings) for managing your Docker Scout subscription and payments - [**Repository settings**](#repository-settings) for enabling and disabling repositories - [**Notifications**](#notification-settings) for managing your notification preferences for Docker Scout. -### Billing settings - -The [Billing settings](https://scout.docker.com/settings/billing) page shows -you the Docker Scout plan for the current organization. Here you can see what's -included in your plan, compare it with other available plans, and change the -plan if you're an organization owner. - -For more information about subscription plans, see -[Docker Scout subscriptions and features](/manuals/subscription/scout-details.md) - ### Repository settings When you enable Docker Scout for a repository, diff --git a/content/manuals/scout/how-tos/artifact-types.md b/content/manuals/scout/how-tos/artifact-types.md index 524219fc8c5..e62a1452dff 100644 --- a/content/manuals/scout/how-tos/artifact-types.md +++ b/content/manuals/scout/how-tos/artifact-types.md @@ -56,7 +56,7 @@ You can use prefixes with the following commands: This section contains a few examples showing how you can use prefixes to specify artifacts for `docker scout` commands. -## Analyze a local project +### Analyze a local project The `fs://` prefix lets you analyze local source code directly, without having to build it into a container image. @@ -112,7 +112,7 @@ pkg:npm/fastify@3.29.0 CRITICAL 0 ``` -## Compare a local project to an image +### Compare a local project to an image With `docker scout compare`, you can compare the analysis of source code on your local filesystem with the analysis of a container image. diff --git a/content/manuals/scout/how-tos/create-exceptions-vex.md b/content/manuals/scout/how-tos/create-exceptions-vex.md index 7cbcdc5a883..5f420ae2f00 100644 --- a/content/manuals/scout/how-tos/create-exceptions-vex.md +++ b/content/manuals/scout/how-tos/create-exceptions-vex.md @@ -24,7 +24,7 @@ To create exceptions using OpenVEX documents, you need: - The latest version of Docker Desktop or the Docker Scout CLI plugin - The [`vexctl`](https://github.com/openvex/vexctl) command line tool. -- The [containerd image store](/manuals/desktop/containerd.md) must be enabled +- The [containerd image store](/manuals/desktop/features/containerd.md) must be enabled - Write permissions to the registry repository where the image is stored ## Introduction to VEX diff --git a/content/manuals/scout/how-tos/view-create-sboms.md b/content/manuals/scout/how-tos/view-create-sboms.md index 103c2d797c3..c05cdc838dd 100644 --- a/content/manuals/scout/how-tos/view-create-sboms.md +++ b/content/manuals/scout/how-tos/view-create-sboms.md @@ -76,7 +76,7 @@ $ docker build --tag / \ ``` To build images with SBOM attestations, you must use either the [containerd -image store](/manuals/desktop/containerd.md) feature, or use a `docker-container` +image store](/manuals/desktop/features/containerd.md) feature, or use a `docker-container` builder together with the `--push` flag to push the image (with attestations) directly to a registry. The classic image store doesn't support manifest lists or image indices, which is required for adding attestations to an image. diff --git a/content/manuals/scout/install.md b/content/manuals/scout/install.md index eeb546ad4e5..078f5db791a 100644 --- a/content/manuals/scout/install.md +++ b/content/manuals/scout/install.md @@ -46,11 +46,16 @@ $ sh install-scout.sh ```json { "cliPluginsExtraDirs": [ - "$HOME/.docker/scout" + "/home//.docker/scout" ] } ``` + Substitute `` with your username on the system. + + > [!NOTE] + > The path for `cliPluginsExtraDirs` must be an absolute path. + {{< /tab >}} {{< tab name="macOS" >}} @@ -65,13 +70,13 @@ $ sh install-scout.sh 4. Make the binary executable: ```console - $ chmod +x $HOME/.docker/scout/docker-scout` + $ chmod +x $HOME/.docker/scout/docker-scout ``` 5. Authorize the binary to be executable on macOS: ```console - xattr -d com.apple.quarantine $HOME/.docker/scout/docker-scout`. + xattr -d com.apple.quarantine $HOME/.docker/scout/docker-scout. ``` 6. Add the `scout` subdirectory to your `.docker/config.json` as a plugin directory: @@ -79,11 +84,16 @@ $ sh install-scout.sh ```json { "cliPluginsExtraDirs": [ - "$HOME/.docker/scout" + "/Users//.docker/scout" ] } ``` + Substitute `` with your username on the system. + + > [!NOTE] + > The path for `cliPluginsExtraDirs` must be an absolute path. + {{< /tab >}} {{< tab name="Windows" >}} @@ -100,11 +110,16 @@ $ sh install-scout.sh ```json { "cliPluginsExtraDirs": [ - "C:\Users\MobyWhale\.docker\scout" + "C:\Users\\.docker\scout" ] } ``` + Substitute `` with your username on the system. + + > [!NOTE] + > The path for `cliPluginsExtraDirs` must be an absolute path. + {{< /tab >}} {{< /tabs >}} diff --git a/content/manuals/scout/integrations/ci/azure.md b/content/manuals/scout/integrations/ci/azure.md index 5b017cc6a26..b58e7fb1dae 100644 --- a/content/manuals/scout/integrations/ci/azure.md +++ b/content/manuals/scout/integrations/ci/azure.md @@ -55,7 +55,7 @@ stages: # Install the Docker Scout CLI curl -sSfL https://raw.githubusercontent.com/docker/scout-cli/main/install.sh | sh -s -- # Login to Docker Hub required for Docker Scout CLI - docker login -u $(DOCKER_HUB_USER) -p $(DOCKER_HUB_PAT) + echo $(DOCKER_HUB_PAT) | docker login -u $(DOCKER_HUB_USER) --password-stdin # Get a CVE report for the built image and fail the pipeline when critical or high CVEs are detected docker scout cves $(image):$(tag) --exit-code --only-severity critical,high ``` diff --git a/content/manuals/scout/integrations/ci/gha.md b/content/manuals/scout/integrations/ci/gha.md index 7fbb3379930..9b1ad746455 100644 --- a/content/manuals/scout/integrations/ci/gha.md +++ b/content/manuals/scout/integrations/ci/gha.md @@ -56,9 +56,6 @@ jobs: pull-requests: write steps: - - name: Setup Docker buildx - uses: docker/setup-buildx-action@v3 - # Authenticate to the container registry - name: Authenticate to registry ${{ env.REGISTRY }} uses: docker/login-action@v3 @@ -66,6 +63,9 @@ jobs: registry: ${{ env.REGISTRY }} username: ${{ secrets.REGISTRY_USER }} password: ${{ secrets.REGISTRY_TOKEN }} + + - name: Setup Docker buildx + uses: docker/setup-buildx-action@v3 # Extract metadata (tags, labels) for Docker - name: Extract Docker metadata diff --git a/content/manuals/scout/integrations/ci/gitlab.md b/content/manuals/scout/integrations/ci/gitlab.md index 61f6dcecac9..0887d3540ad 100644 --- a/content/manuals/scout/integrations/ci/gitlab.md +++ b/content/manuals/scout/integrations/ci/gitlab.md @@ -34,7 +34,7 @@ docker-build: apk del curl rm -rf /var/cache/apk/* # Login to Docker Hub required for Docker Scout CLI - - docker login -u "$DOCKER_HUB_USER" -p "$DOCKER_HUB_PAT" + - echo "$DOCKER_HUB_PAT" | docker login -u "$DOCKER_HUB_USER" --password-stdin ``` This sets up the workflow to build Docker images with Docker-in-Docker mode, diff --git a/content/manuals/scout/integrations/environment/sysdig.md b/content/manuals/scout/integrations/environment/sysdig.md index 38bf50657e2..c2430eaa0a5 100644 --- a/content/manuals/scout/integrations/environment/sysdig.md +++ b/content/manuals/scout/integrations/environment/sysdig.md @@ -1,8 +1,8 @@ --- title: Integrate Docker Scout with Sysdig linkTitle: Sysdig -description: scout, sysdig, integration, image analysis, environments, supply chain -keywords: Integrate your runtime environments with Docker Scout using Sysdig +description: Integrate your runtime environments with Docker Scout using Sysdig +keywords: scout, sysdig, integration, image analysis, environments, supply chain --- {{< include "scout-early-access.md" >}} diff --git a/content/manuals/scout/policy/ci.md b/content/manuals/scout/policy/ci.md index bdd41f761f4..1d50a6b149e 100644 --- a/content/manuals/scout/policy/ci.md +++ b/content/manuals/scout/policy/ci.md @@ -94,15 +94,15 @@ jobs: runs-on: ubuntu-latest steps: - - name: Setup Docker buildx - uses: docker/setup-buildx-action@v3 - - name: Log into registry ${{ env.REGISTRY }} uses: docker/login-action@v3 with: registry: ${{ env.REGISTRY }} username: ${{ secrets.REGISTRY_USER }} password: ${{ secrets.REGISTRY_TOKEN }} + + - name: Setup Docker buildx + uses: docker/setup-buildx-action@v3 - name: Extract metadata id: meta diff --git a/content/manuals/scout/quickstart.md b/content/manuals/scout/quickstart.md index ca108f9b783..86d58151ea4 100644 --- a/content/manuals/scout/quickstart.md +++ b/content/manuals/scout/quickstart.md @@ -55,7 +55,6 @@ You can do this from Docker Hub, the Docker Scout Dashboard, and CLI. ```console $ docker scout enroll - ✓ Successfully enrolled organization with Docker Scout Free ``` 3. Enable Docker Scout for your image repository with the `docker scout repo enable` command. @@ -204,7 +203,7 @@ Docker Scout uses the provenance attestations to determine how the image was built so that it can provide a better evaluation result. Before you can build an image with attestations, -you must enable the [containerd image store](/manuals/desktop/containerd.md) +you must enable the [containerd image store](/manuals/desktop/features/containerd.md) (or create a custom builder using the `docker-container` driver). The classic image store doesn't support manifest lists, which is how the provenance attestations are attached to an image. diff --git a/content/manuals/scout/release-notes/cli.md b/content/manuals/scout/release-notes/cli.md index 5c2f9eacc39..1ed667573f5 100644 --- a/content/manuals/scout/release-notes/cli.md +++ b/content/manuals/scout/release-notes/cli.md @@ -9,6 +9,43 @@ This page contains information about the new features, improvements, known issues, and bug fixes in the Docker Scout [CLI plugin](https://github.com/docker/scout-cli/) and the `docker/scout-action` [GitHub Action](https://github.com/docker/scout-action). +## 1.15.0 + +{{< release-date date="2024-10-31" >}} + +### New + +- New `--format=cyclonedx` flag for the `docker scout sbom` to output the SBOM in CycloneDX format. + +### Enhancements + +- Use high-to-low sort order for CVE summary. +- Support for enabling and disabling repositories that enabled by `docker scout push` or `docker scout watch`. + +### Bug fixes + +- Improve messaging when analyzing `oci` directories without attestations. + Only single-platform images and multi-platform image _with attestations_ are supported. + Multi-platform images without attestations are not supported. +- Improve classifiers and SBOM indexer: + - Add classifier for Liquibase `lpm`. + - Add Rakudo Star/MoarVM binary classifier. + - Add binary classifiers for silverpeas utilities. +- Improve reading and caching of attestations with the containerd image store. + +## 1.14.0 + +{{< release-date date="2024-09-24" >}} + +### New + +- Add suppression information at the CVE level in the `docker scout cves` command. + +### Bug fixes + +- Fix listing CVEs for dangling images, for example: `local://sha256:...` +- Fix panic when analysing a file system input, for instance with `docker scout cves fs://.` + ## 1.13.0 {{< release-date date="2024-08-05" >}} @@ -373,7 +410,7 @@ Discarded in favor of [1.9.1](#191). instance by Docker Desktop there's no need anymore to re-index it on WSL2 side. - Indexing is now blocked in the CLI if it has been disabled using - [Settings Management](/manuals/security/for-admins/hardened-desktop/settings-management/configure.md) feature. + [Settings Management](/manuals/security/for-admins/hardened-desktop/settings-management/_index.md) feature. - Fix a panic that would occur when analyzing a single-image `oci-dir` input - Improve local attestation support with the containerd image store diff --git a/content/manuals/security/_index.md b/content/manuals/security/_index.md index 4b5eb7bf5a7..c7d4dc29a9f 100644 --- a/content/manuals/security/_index.md +++ b/content/manuals/security/_index.md @@ -1,8 +1,10 @@ --- title: Security -weight: 200 description: Learn about security features Docker has to offer and explore best practices keywords: docker, docker hub, docker desktop, security +params: + sidebar: + group: Platform grid_admins: - title: Settings Management description: Learn how Settings Management can secure your developers' workflows. @@ -64,7 +66,7 @@ grid_developers: - title: Static vulnerability scanning description: Automatically run a point-in-time scan on your Docker images for vulnerabilities. icon: image_search - link: /docker-hub/vulnerability-scanning/ + link: /docker-hub/repos/manage/vulnerability-scanning/ - title: Docker Engine security description: Understand how to keep Docker Engine secure. icon: security diff --git a/content/manuals/security/faqs/networking-and-vms.md b/content/manuals/security/faqs/networking-and-vms.md index 546ae7114da..39df4646213 100644 --- a/content/manuals/security/faqs/networking-and-vms.md +++ b/content/manuals/security/faqs/networking-and-vms.md @@ -35,4 +35,4 @@ On Mac it is an unprivileged operation to start a VM, so that is not enforced by ### How does Docker Desktop achieve network level isolation when Hyper-V and/or WSL2 is used? -The VM processes are the same for both WSL 2 (running inside the `docker-desktop` distro) and Hyper-V (running inside the `DockerDesktopVM`). Host/VM communication uses `AF_VSOCK` hypervisor sockets (shared memory). It does not use Hyper-V network switches or network interfaces. All host networking is performed using normal TCP/IP sockets from the `com.docker.vpnkit.exe` and `com.docker.backend.exe` processes. For more information see [How Docker Desktop networking works under the hood](https://www.docker.com/blog/how-docker-desktop-networking-works-under-the-hood/). +The VM processes are the same for both WSL 2 (running inside the `docker-desktop` distribution) and Hyper-V (running inside the `DockerDesktopVM`). Host/VM communication uses `AF_VSOCK` hypervisor sockets (shared memory). It does not use Hyper-V network switches or network interfaces. All host networking is performed using normal TCP/IP sockets from the `com.docker.vpnkit.exe` and `com.docker.backend.exe` processes. For more information see [How Docker Desktop networking works under the hood](https://www.docker.com/blog/how-docker-desktop-networking-works-under-the-hood/). diff --git a/content/manuals/security/faqs/single-sign-on/enforcement-faqs.md b/content/manuals/security/faqs/single-sign-on/enforcement-faqs.md index 1e1605bae78..23be1ea11f8 100644 --- a/content/manuals/security/faqs/single-sign-on/enforcement-faqs.md +++ b/content/manuals/security/faqs/single-sign-on/enforcement-faqs.md @@ -10,7 +10,7 @@ aliases: ### We currently have a Docker Team subscription. How do we enable SSO? -SSO is available with a Docker Business subscription. To enable SSO, you must first upgrade your subscription to a Docker Business subscription. To learn how to upgrade your existing account, see [Upgrade your subscription](../../../subscription/core-subscription/upgrade.md). +SSO is available with a Docker Business subscription. To enable SSO, you must first upgrade your subscription to a Docker Business subscription. To learn how to upgrade your existing account, see [Upgrade your subscription](../../../subscription/change.md). ### How do service accounts work with SSO? diff --git a/content/manuals/security/faqs/single-sign-on/faqs.md b/content/manuals/security/faqs/single-sign-on/faqs.md index d4cd64b3637..85964d83d01 100644 --- a/content/manuals/security/faqs/single-sign-on/faqs.md +++ b/content/manuals/security/faqs/single-sign-on/faqs.md @@ -15,7 +15,7 @@ aliases: ### Is Docker SSO available for all paid subscriptions? -Docker single sign-on (SSO) is only available with the Docker Business subscription. [Upgrade your existing subscription](/subscription/core-subscription/upgrade/) to start using Docker SSO. +Docker single sign-on (SSO) is only available with the Docker Business subscription. [Upgrade your existing subscription](../../../subscription/change.md) to start using Docker SSO. ### How does Docker SSO work? diff --git a/content/manuals/security/for-admins/access-tokens.md b/content/manuals/security/for-admins/access-tokens.md index c99888979bd..afdc5eef8ec 100644 --- a/content/manuals/security/for-admins/access-tokens.md +++ b/content/manuals/security/for-admins/access-tokens.md @@ -12,12 +12,15 @@ The organization access tokens feature is currently in [Beta](../../release-life > [!WARNING] > -> Organization access tokens aren't currently compatible with the following services: +> Organization access tokens (OATs) are not intended to be used with Docker Desktop, and are incompatible. +> +> OATs are also currently incompatible with the following services: > > - Docker Build Cloud > - Docker Scout +> - Docker REST APIs > -> If you use these services, you must use personal access tokens instead. +> If you use Docker Desktop or one of these services, you must use personal access tokens instead. An organization access token (OAT) is like a [personal access token (PAT)](/security/for-developers/access-tokens/), but an OAT is associated with diff --git a/content/manuals/security/for-admins/domain-audit.md b/content/manuals/security/for-admins/domain-audit.md index 6e7e4d8c388..fb107c896b7 100644 --- a/content/manuals/security/for-admins/domain-audit.md +++ b/content/manuals/security/for-admins/domain-audit.md @@ -33,7 +33,7 @@ Although domain audit can't identify all Docker users in your environment, you c Before you audit your domains, review the following required prerequisites: -- Your organization must be part of a Docker Business subscription. To upgrade your existing account to a Docker Business subscription, see [Upgrade your subscription](../../subscription/core-subscription/upgrade.md). +- Your organization must be part of a Docker Business subscription. To upgrade your existing account to a Docker Business subscription, see [Upgrade your subscription](../../subscription/change.md). - You must [add and verify your domains](./single-sign-on/configure/_index.md#step-one-add-and-verify-your-domain). > [!IMPORTANT] diff --git a/content/manuals/security/for-admins/enforce-sign-in/_index.md b/content/manuals/security/for-admins/enforce-sign-in/_index.md index f4f26318bae..530c1148553 100644 --- a/content/manuals/security/for-admins/enforce-sign-in/_index.md +++ b/content/manuals/security/for-admins/enforce-sign-in/_index.md @@ -13,11 +13,12 @@ weight: 30 By default, members of your organization can use Docker Desktop without signing in. When users don’t sign in as a member of your organization, they don’t receive the [benefits of your organization’s -subscription](../../../subscription/core-subscription/details.md) and they can circumvent [Docker’s +subscription](../../../subscription/details.md) and they can circumvent [Docker’s security features](/manuals/security/for-admins/hardened-desktop/_index.md) for your organization. There are multiple methods for enforcing sign-in, depending on your companies' set up and preferences: - [Registry key method (Windows only)](methods.md#registry-key-method-windows-only){{< badge color=green text="New" >}} +- [Configuration profiles method (Mac only)](methods.md#configuration-profiles-method-mac-only){{< badge color=green text="New" >}} - [`.plist` method (Mac only)](methods.md#plist-method-mac-only){{< badge color=green text="New" >}} - [`registry.json` method (All)](methods.md#registryjson-method-all) diff --git a/content/manuals/security/for-admins/enforce-sign-in/methods.md b/content/manuals/security/for-admins/enforce-sign-in/methods.md index 796e351bfa5..218e2e480ac 100644 --- a/content/manuals/security/for-admins/enforce-sign-in/methods.md +++ b/content/manuals/security/for-admins/enforce-sign-in/methods.md @@ -23,7 +23,7 @@ To enforce sign-in for Docker Desktop on Windows, you can configure a registry k 2. Create a multi-string value `allowedOrgs`. > [!IMPORTANT] > - > Only one entry for `allowedOrgs` is currently supported. If you add more than one value, sign-in enforcement silently fails. + > As of Docker Desktop version 4.36 and later, you can add more than one organization. With Docker Desktop version 4.35 and earlier, if you add more than one organization sign-in enforcement silently fails. 3. Use your organization's name, all lowercase as string data. 4. Restart Docker Desktop. 5. When Docker Desktop restarts, verify that the **Sign in required!** prompt appears. @@ -43,11 +43,84 @@ The following example outlines how to deploy a registry key to enforce sign-in o 3. Within the GPO, navigate to **Computer Configuration** and select **Preferences**. 4. Select **Windows Settings** then **Registry**. 5. To add the registry item, right-click on the **Registry** node, select **New**, and then **Registry Item**. -6. Configure the new registry item to match the registry script you created, specifying the action as **Update**. Make sure you input the correct path, value name (`allowedOrgs`), and value data (your organization’s name). +6. Configure the new registry item to match the registry script you created, specifying the action as **Update**. Make sure you input the correct path, value name (`allowedOrgs`), and value data (your organization names). 7. Link the GPO to an Organizational Unit (OU) that contains the machines you want to apply this setting to. 8. Test the GPO on a small set of machines first to ensure it behaves as expected. You can use the `gpupdate /force` command on a test machine to manually refresh its group policy settings and check the registry to confirm the changes. 9. Once verified, you can proceed with broader deployment. Monitor the deployment to ensure the settings are applied correctly across the organization's computers. +## Configuration profiles method (Mac only) + +> [!NOTE] +> +> The configuration profiles method is in [Early Access](/manuals/release-lifecycle.md) +> and is available with Docker Desktop version 4.36 and later. + +Configuration profiles are a feature of macOS that let you distribute +configuration information to the Macs you manage. It is the safest method to +enforce sign-in on macOS because the installed configuration profiles are +protected by Apples' System Integrity Protection (SIP) and therefore can't be +tampered with by the users. + +1. Save the following XML file with the extension `.mobileconfig`, for example + `docker.mobileconfig`: + + ```xml + + + + + PayloadContent + + + PayloadType + com.docker.config + PayloadVersion + 1 + PayloadIdentifier + com.docker.config + PayloadUUID + eed295b0-a650-40b0-9dda-90efb12be3c7 + PayloadDisplayName + Docker Desktop Configuration + PayloadDescription + Configuration profile to manage Docker Desktop settings. + PayloadOrganization + Your Company Name + allowedOrgs + first_org;second_org + + + PayloadType + Configuration + PayloadVersion + 1 + PayloadIdentifier + com.yourcompany.docker.config + PayloadUUID + 0deedb64-7dc9-46e5-b6bf-69d64a9561ce + PayloadDisplayName + Docker Desktop Config Profile + PayloadDescription + Config profile to enforce Docker Desktop settings for allowed organizations. + PayloadOrganization + Your Company Name + + + ``` + +2. Change the placeholders `com.yourcompany.docker.config` and `Your Company Name` to the name of your company. + +3. Add your organization name. The names of the allowed organizations are stored in the `allowedOrgs` + property. It can contain either the name of a single organization or a list of organization names, + separated by a semicolon: + + ```xml + allowedOrgs + first_org;second_org + ``` + +4. Use a MDM solution to distribute your modified `.mobileconfig` file to your macOS clients. + ## plist method (Mac only) > [!NOTE] @@ -66,14 +139,15 @@ To enforce sign-in for Docker Desktop on macOS, you can use a `plist` file that allowedOrgs - myorg + myorg1 + myorg2 ``` > [!IMPORTANT] > - > Only one entry for `allowedOrgs` is currently supported. If you add more than one value, sign-in enforcement silently fails. + > As of Docker Desktop version 4.36 and later, you can add more than one organization. With Docker Desktop version 4.35 and earlier, sign-in enforcement silently fails if you add more than one organization. 3. Modify the file permissions to ensure the file cannot be edited by any non-administrator users. 4. Restart Docker Desktop. @@ -140,12 +214,12 @@ details, see [Manage members](/admin/organization/members/). ```json { - "allowedOrgs": ["myorg"] + "allowedOrgs": ["myorg1", "myorg2"] } ``` > [!IMPORTANT] > - > Only one entry for `allowedOrgs` is currently supported. If you add more than one value, sign-in enforcement silently fails. + > As of Docker Desktop version 4.36 and later, you can add more than one organization. With Docker Desktop version 4.35 and earlier, if you add more than one organization sign-in enforcement silently fails. 4. Verify that sign-in is enforced. @@ -182,6 +256,9 @@ If you're using the Windows Command Prompt: ```console C:\Users\Admin> "Docker Desktop Installer.exe" install --allowed-org=myorg ``` +> [!IMPORTANT] +> +> As of Docker Desktop version 4.36 and later, you can add more than one organization to a single `registry.json` file. With Docker Desktop version 4.35 and earlier, if you add more than one organization sign-in enforcement silently fails. {{< /tab >}} {{< tab name="Mac" >}} @@ -231,6 +308,10 @@ Path Owner Access registry.json BUILTIN\Administrators NT AUTHORITY\SYSTEM Allow FullControl... ``` +> [!IMPORTANT] +> +> As of Docker Desktop version 4.36 and later, you can add more than one organization to a single `registry.json` file. With Docker Desktop version 4.35 and earlier, if you add more than one organization sign-in enforcement silently fails. + {{< /tab >}} {{< tab name="Mac" >}} @@ -264,6 +345,10 @@ $ sudo ls -l "/Library/Application Support/com.docker.docker/registry.json" -rw-r--r-- 1 root admin 26 Jul 27 22:01 /Library/Application Support/com.docker.docker/registry.json ``` +> [!IMPORTANT] +> +> As of Docker Desktop version 4.36 and later, you can add more than one organization to a single `registry.json` file. With Docker Desktop version 4.35 and earlier, if you add more than one organization sign-in enforcement silently fails. + {{< /tab >}} {{< tab name="Linux" >}} @@ -297,6 +382,10 @@ $ sudo ls -l /usr/share/docker-desktop/registry/registry.json -rw-r--r-- 1 root root 26 Jul 27 22:01 /usr/share/docker-desktop/registry/registry.json ``` +> [!IMPORTANT] +> +> As of Docker Desktop version 4.36 and later, you can add more than one organization to a single `registry.json` file. With Docker Desktop version 4.35 and earlier, if you add more than one organization sign-in enforcement silently fails. + {{< /tab >}} {{< /tabs >}} diff --git a/content/manuals/security/for-admins/hardened-desktop/_index.md b/content/manuals/security/for-admins/hardened-desktop/_index.md index 0ef103c2ce5..067476c2d1a 100644 --- a/content/manuals/security/for-admins/hardened-desktop/_index.md +++ b/content/manuals/security/for-admins/hardened-desktop/_index.md @@ -37,9 +37,9 @@ weight: 60 Hardened Docker Desktop is a group of security features, designed to improve the security of developer environments with minimal impact on developer experience or productivity. -It lets administrators enforce strict security settings, preventing developers and their containers from bypassing these controls, either intentionally or unintentionally. Additionally, you can enhance container isolation, to mitigate potential security threats such as malicious payloads breaching the Docker Desktop Linux VM and the underlying host. +It lets you enforce strict security settings, preventing developers and their containers from bypassing these controls, either intentionally or unintentionally. Additionally, you can enhance container isolation, to mitigate potential security threats such as malicious payloads breaching the Docker Desktop Linux VM and the underlying host. -Hardened Docker Desktop moves the ownership boundary for Docker Desktop configuration to the organization, meaning that any security controls administrators set cannot be altered by the user of Docker Desktop. +Hardened Docker Desktop moves the ownership boundary for Docker Desktop configuration to the organization, meaning that any security controls you set cannot be altered by the user of Docker Desktop. It is for security conscious organizations who: - Don’t give their users root or administrator access on their machines @@ -50,8 +50,8 @@ It is for security conscious organizations who: Hardened Desktop features work independently but collectively to create a defense-in-depth strategy, safeguarding developer workstations against potential attacks across various functional layers, such as configuring Docker Desktop, pulling container images, and running container images. This multi-layered defense approach ensures comprehensive security. It helps mitigate against threats such as: - - Malware and supply chain attacks: Registry Access Management and Image Access Management prevent developers from accessing certain container registries and image types, significantly lowering the risk of malicious payloads. Additionally, ECI restricts the impact of containers with malicious payloads by running them without root privileges inside a Linux user namespace. - - Lateral movement: Air-Gapped Containers lets administrators configure network access restrictions for containers, thereby preventing malicious containers from performing lateral movement within the organization's network. - - Insider threats: Settings Management configures and locks various Docker Desktop settings so administrators can enforce company policies and prevent developers from introducing insecure configurations, intentionally or unintentionally. + - Malware and supply chain attacks: Registry Access Management and Image Access Management prevent developers from accessing certain container registries and image types, significantly lowering the risk of malicious payloads. Additionally, Enhanced Container Isolation (ECI) restricts the impact of containers with malicious payloads by running them without root privileges inside a Linux user namespace. + - Lateral movement: Air-gapped containers lets you configure network access restrictions for containers, thereby preventing malicious containers from performing lateral movement within the organization's network. + - Insider threats: Settings Management configures and locks various Docker Desktop settings so you can enforce company policies and prevent developers from introducing insecure configurations, intentionally or unintentionally. {{< grid >}} diff --git a/content/manuals/security/for-admins/hardened-desktop/air-gapped-containers.md b/content/manuals/security/for-admins/hardened-desktop/air-gapped-containers.md index d3993b474ea..107de364329 100644 --- a/content/manuals/security/for-admins/hardened-desktop/air-gapped-containers.md +++ b/content/manuals/security/for-admins/hardened-desktop/air-gapped-containers.md @@ -9,11 +9,11 @@ aliases: {{< introduced desktop 4.29.0 "/manuals/desktop/release-notes.md#4290" >}} -Air-Gapped Containers allows administrators to restrict containers from accessing network resources, limiting where data can be uploaded to or downloaded from. +Air-gapped containers let you restrict containers from accessing network resources, limiting where data can be uploaded to or downloaded from. Docker Desktop can apply a custom set of proxy rules to network traffic from containers. The proxy can be configured to: -- Allow network connections +- Accept network connections - Reject network connections - Tunnel through an HTTP or SOCKS proxy @@ -79,9 +79,9 @@ The `FindProxyForURL` can return the following values: - `PROXY host_or_ip:port`: Tunnels this request through the HTTP proxy `host_or_ip:port` - `SOCKS5 host_or_ip:port`: Tunnels this request through the SOCKS proxy `host_or_ip:port` -- `DIRECT`: Allows this request to go direct, without a proxy +- `DIRECT`: Lets this request go direct, without a proxy - `PROXY reject.docker.internal:any_port`: Rejects this request In this particular example, HTTP and HTTPS requests for `internal.corp` are sent via the HTTP proxy `10.0.0.1:3128`. Requests to connect to IPs on the subnet `192.168.0.0/24` connect directly. All other requests are blocked. -To restrict traffic connecting to ports on the developers local machine, [match the special hostname `host.docker.internal`](/manuals/desktop/networking.md#i-want-to-connect-from-a-container-to-a-service-on-the-host). +To restrict traffic connecting to ports on the developers local machine, [match the special hostname `host.docker.internal`](/manuals/desktop/features/networking.md#i-want-to-connect-from-a-container-to-a-service-on-the-host). diff --git a/content/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/_index.md b/content/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/_index.md index a8228d4a6a3..f08fd5383b2 100644 --- a/content/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/_index.md +++ b/content/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/_index.md @@ -13,49 +13,41 @@ weight: 20 > > Enhanced Container Isolation is available to Docker Business customers only. -Enhanced Container Isolation provides an additional layer of security to prevent malicious workloads running in containers from compromising Docker Desktop or the host. +Enhanced Container Isolation (ECI) provides an additional layer of security to prevent malicious workloads running in containers from compromising Docker Desktop or the host. -It uses a variety of advanced techniques to harden container isolation, but without impacting developer productivity. It is available with [Docker Desktop 4.13.0 and later](/manuals/desktop/release-notes.md). +It uses a variety of advanced techniques to harden container isolation, but without impacting developer productivity. -These techniques include: -- Running all containers unprivileged through the Linux user-namespace, even those launched with the `--privileged` flag. This makes it harder for malicious container workloads to escape the container and infect the Docker Desktop VM and host. -- Ensuring Docker Desktop VM immutability (e.g., its internal settings can't be modified by containers or users). -- Vetting some critical system calls to prevent container escapes, and partially virtualizing portions of `/proc` and `/sys` inside the container for further isolation. -- Preventing user console access to the Docker Desktop VM. - -When Enhanced Container Isolation is enabled, these mechanisms are applied automatically and with minimal functional or performance impact to developers. Developers continue to use Docker Desktop as usual, but the containers they launch are more strongly isolated. - -Enhanced Container Isolation ensures stronger container isolation and also locks in any security configurations that have been created by IT admins, for instance through [Registry Access Management policies](/manuals/security/for-admins/hardened-desktop/registry-access-management.md) or with [Settings Management](../settings-management/_index.md). +Enhanced Container Isolation ensures stronger container isolation and also locks in any security configurations that have been created by administrators, for instance through [Registry Access Management policies](/manuals/security/for-admins/hardened-desktop/registry-access-management.md) or with [Settings Management](../settings-management/_index.md). > [!NOTE] > -> Enhanced Container Isolation is in addition to other container security techniques used by Docker. For example, reduced Linux Capabilities, Seccomp, AppArmor. +> ECI is in addition to other container security techniques used by Docker. For example, reduced Linux Capabilities, seccomp, and AppArmor. -### Who is it for? +## Who is it for? - For organizations and developers that want to prevent container attacks and reduce vulnerabilities in developer environments. - For organizations that want to ensure stronger container isolation that is easy and intuitive to implement on developers' machines. -### What happens when Enhanced Container Isolation is turned on? +## What happens when Enhanced Container Isolation is turned on? -When Enhanced Container Isolation is turned on, the following features are enabled: +When Enhanced Container Isolation is turned on, the following features and security techniques are enabled: -- All user containers are automatically run in Linux User Namespaces which ensures stronger isolation. Each container runs in a dedicated Linux user-namespace. +- All user containers are automatically run in Linux user namespaces which ensures stronger isolation. Each container runs in a dedicated Linux user-namespace. - The root user in the container maps to an unprivileged user inside the Docker Desktop Linux VM. -- Containers become harder to breach. For example, sensitive system calls are vetted and portions of `/proc` and `/sys` are emulated. +- Containers become harder to breach. For example, sensitive system calls are vetted and portions of `/proc` and `/sys` are emulated inside the container. - Users can continue using containers as usual, including bind mounting host directories, volumes, etc. - No change in the way developers run containers, and no special container images are required. -- Privileged containers (e.g., `--privileged` flag) work, but they are only privileged within the container's Linux User Namespace, not in the Docker Desktop VM. Therefore they can't be used to breach the Docker Desktop VM. +- Privileged containers (e.g., `--privileged` flag) work, but they are only privileged within the container's Linux user namespace, not in the Docker Desktop VM. Therefore they can't be used to breach the Docker Desktop VM. - Docker-in-Docker and even Kubernetes-in-Docker works, but run unprivileged inside the Docker Desktop Linux VM. In addition, the following restrictions are imposed: - Containers can no longer share namespaces with the Docker Desktop VM (e.g., `--network=host`, `--pid=host` are disallowed). - Containers can no longer modify configuration files inside the Docker Desktop VM (e.g., mounting any VM directory into the container is disallowed). -- Containers can no longer access the Docker engine (e.g., mounting the Docker engine's socket into the container is restricted); this prevents malicious containers from gaining control of the Docker engine. Admins can relax this for [trusted container images](config.md). +- Containers can no longer access the Docker Engine. For example, mounting the Docker Engine's socket into the container is restricted which prevents malicious containers from gaining control of the Docker Engine. Administrators can relax this for [trusted container images](config.md). - Console access to the Docker Desktop VM is forbidden for all users. -These features and restrictions ensure that containers are better secured at runtime, with minimal impact to developer experience and productivity. +These features and restrictions ensure that containers are better secured at runtime, with minimal impact to developer experience and productivity. Developers can continue to use Docker Desktop as usual, but the containers they launch are more strongly isolated. For more information on how Enhanced Container Isolation work, see [How does it work](how-eci-works.md). @@ -65,20 +57,9 @@ For more information on how Enhanced Container Isolation work, see [How does it > Kubernetes pods and Extension containers. For more information on known > limitations and workarounds, see [FAQs](faq.md). -### What host OSes / platforms is Enhanced Container Isolation supported on? - -Enhanced Container Isolation (ECI) was introduced in Docker Desktop 4.13, for all platforms (Windows, Mac, and Linux). - -For Windows hosts, ECI works with both the Docker Desktop Hyper-V and WSL 2 backends, as follows: - -- Docker Desktop 4.19 or prior: ECI only works with Hyper-V. -- Docker Desktop 4.20 or later: ECI Works with both Hyper-V and WSL 2 (with WSL version 1.1.3.0 and above). +## How do I enable Enhanced Container Isolation? -See [ECI Support for WSL](limitations.md#eci-support-for-wsl) for further info as well as security caveats when using Enhanced Container Isolation on WSL 2. - -### How do I enable Enhanced Container Isolation? - -#### As a developer +### As a developer To enable Enhanced Container Isolation as a developer: 1. Ensure your organization has a Docker Business subscription. @@ -92,21 +73,15 @@ To enable Enhanced Container Isolation as a developer: > > Enhanced Container Isolation does not protect containers created prior to enabling ECI. For more information on known limitations and workarounds, see [FAQs](faq.md). -#### As an admin - -##### Prerequisite +### As an administrator -To enable Enhanced Container Isolation as an admin, you first need to [enforce -sign-in](/manuals/security/for-admins/enforce-sign-in/_index.md). This is -because the Enhanced Container Isolation feature requires a Docker Business -subscription and therefore your Docker Desktop users must authenticate to your -organization for this configuration to take effect. +#### Prerequisite -Enforcing sign-in ensures that your Docker Desktop developers always authenticate to your organization. +You first need to [enforce sign-in](/manuals/security/for-admins/enforce-sign-in/_index.md) to ensure that all Docker Desktop developers authenticate with your organization. Since Settings Management requires a Docker Business subscription, enforced sign-in guarantees that only authenticated users have access and that the feature consistently takes effect across all users, even though it may still work without enforced sign-in. -##### Setup +#### Setup -[Create and configure the `admin-settings.json` file](../settings-management/configure.md) and specify: +[Create and configure the `admin-settings.json` file](/manuals/security/for-admins/hardened-desktop/settings-management/configure-json-file.md) and specify: ```json { @@ -118,13 +93,13 @@ Enforcing sign-in ensures that your Docker Desktop developers always authenticat } ``` -By setting `"value": true`, the admin ensures ECI is enabled by default. By -setting `"locked": true`, the admin ensures ECI can't be disabled by -developers. If you wish to give developers the ability to disable the feature, +Setting `"value": true` ensures ECI is enabled by default. By +setting `"locked": true`, ECI can't be disabled by +developers. If you want to give developers the ability to disable the feature, set `"locked": false`. -In addition, starting with Docker Desktop 4.27, admins can also configure Docker -socket mount permissions for containers, as described [here](config.md). +In addition, you can also [configure Docker +socket mount permissions for containers](config.md). For this to take effect: @@ -135,7 +110,11 @@ For this to take effect: > > Selecting **Restart** from the Docker menu isn't enough as it only restarts some components of Docker Desktop. -### What do users see when this setting is enforced by an admin? +## What do users see when this setting is enforced by an administrator? + +> [!TIP] +> +> You can now also configure these settings in the [Docker Admin Console](/manuals/security/for-admins/hardened-desktop/settings-management/configure-admin-console.md). When Enhanced Container Isolation is enabled, users see: - **Use Enhanced Container Isolation** toggled on in **Settings** > **General**. diff --git a/content/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/config.md b/content/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/config.md index 50ddf3c5614..f4a64cd38bb 100644 --- a/content/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/config.md +++ b/content/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/config.md @@ -8,16 +8,9 @@ aliases: weight: 30 --- -> [!NOTE] -> -> This feature is available with Docker Desktop version 4.27 (and later) on Mac, Linux, and Windows (Hyper-V). -> For Windows with WSL 2, this feature requires Docker Desktop 4.28 and later. - -This page describes optional, advanced configurations for ECI, once ECI is enabled. - ## Docker socket mount permissions -By default, when ECI is enabled, Docker Desktop does not allow bind-mounting the +By default, when Enhanced Container Isolation (ECI) is enabled, Docker Desktop does not allow bind-mounting the Docker Engine socket into containers: ```console @@ -25,8 +18,8 @@ $ docker run -it --rm -v /var/run/docker.sock:/var/run/docker.sock docker:cli docker: Error response from daemon: enhanced container isolation: docker socket mount denied for container with image "docker.io/library/docker"; image is not in the allowed list; if you wish to allow it, configure the docker socket image list in the Docker Desktop settings. ``` This prevents malicious containers from gaining access to the Docker Engine, as -such access could allow them to perform supply chain attacks (e.g., build and -push malicious images into the organization's repositories) or similar. +such access could allow them to perform supply chain attacks. For example, build and +push malicious images into the organization's repositories or similar. However, some legitimate use cases require containers to have access to the Docker Engine socket. For example, the popular [Testcontainers](https://testcontainers.com/) @@ -35,11 +28,12 @@ manage them or perform post-test cleanup. Similarly, some Buildpack frameworks, for example [Paketo](https://paketo.io/), require Docker socket bind-mounts into containers. -Starting with Docker Desktop 4.27, admins can optionally configure ECI to allow +Administrators can optionally configure ECI to allow bind mounting the Docker Engine socket into containers, but in a controlled way. This can be done via the Docker Socket mount permissions section in the -[admin-settings.json](../settings-management/configure.md) file. For example: +[`admin-settings.json`](../settings-management/configure-json-file.md) file. For example: + ```json { @@ -53,7 +47,8 @@ This can be done via the Docker Socket mount permissions section in the "docker.io/localstack/localstack:*", "docker.io/testcontainers/ryuk:*", "docker:cli" - ] + ], + "allowDerivedImages": true }, "commandList": { "type": "deny", @@ -64,6 +59,10 @@ This can be done via the Docker Socket mount permissions section in the } ``` +> [!TIP] +> +> You can now also configure these settings in the [Docker Admin Console](/manuals/security/for-admins/hardened-desktop/settings-management/configure-admin-console.md). + As shown above, there are two configurations for bind-mounting the Docker socket into containers: the `imageList` and the `commandList`. These are described below. @@ -71,8 +70,8 @@ described below. ### Image list The `imageList` is a list of container images that are allowed to bind-mount the -Docker socket. By default the list is empty (i.e., no containers are allowed to -bind-mount the Docker socket when ECI is enabled). However, an admin can add +Docker socket. By default the list is empty, no containers are allowed to +bind-mount the Docker socket when ECI is enabled. However, an administrator can add images to the list, using either of these formats: | Image Reference Format | Description | @@ -83,7 +82,7 @@ images to the list, using either of these formats: The image name follows the standard convention, so it can point to any registry and repository. -In the example above, the image list was configured with three images: +In the previous example, the image list was configured with three images: ```json "imageList": { @@ -107,11 +106,10 @@ $ docker run -it -v /var/run/docker.sock:/var/run/docker.sock docker:cli sh > [!TIP] > -> Be restrictive on the images you allow, as described in [Recommendations](#recommendations) below. +> Be restrictive with the images you allow, as described in [Recommendations](#recommendations). -In general, it's easier to specify the image using the tag wildcard format -(e.g., `:*`) because then `imageList` doesn't need to be updated whenever a new version of the -image is used. Alternatively, you can use an immutable tag (e.g., `:latest`), +In general, it's easier to specify the image using the tag wildcard format, for example `:*`, because then `imageList` doesn't need to be updated whenever a new version of the +image is used. Alternatively, you can use an immutable tag, for example `:latest`, but it does not always work as well as the wildcard because, for example, Testcontainers uses specific versions of the image, not necessarily the latest one. @@ -122,10 +120,9 @@ memory. Then, when a container is started with a Docker socket bind-mount, Docker Desktop checks if the container's image digest matches one of the allowed digests. If so, the container is allowed to start, otherwise it's blocked. -Note that due to the digest comparison mentioned in the prior paragraph, it's -not possible to bypass the Docker socket mount permissions by retagging a -disallowed image to the name of an allowed one. In other words, if a user -does: +Due to the digest comparison, it's not possible to bypass the Docker socket +mount permissions by re-tagging a disallowed image to the name of an allowed +one. In other words, if a user does: ```console $ docker image rm @@ -139,11 +136,9 @@ ones in the repository. ### Docker Socket Mount Permissions for derived images -> [!NOTE] -> -> This feature is available with Docker Desktop version 4.34 and later. +{{< introduced desktop 4.34.0 "../../../../desktop/release-notes.md#4340" >}} -As described in the prior section, admins can configure the list of container +As described in the prior section, administrators can configure the list of container images that are allowed to mount the Docker socket via the `imageList`. This works for most scenarios, but not always, because it requires knowing upfront @@ -160,7 +155,7 @@ also apply to any local images derived (i.e., built from) an image in the That is, if a local image called "myLocalImage" is built from "myBaseImage" (i.e., has a Dockerfile with a `FROM myBaseImage`), then if "myBaseImage" is in the `imageList`, both "myBaseImage" and "myLocalImage" are allowed to mount the -Docker socket (i.e., ECI won't block the mount). +Docker socket. For example, to enable Paketo buildpacks to work with Docker Desktop and ECI, simply add the following image to the `imageList`: @@ -168,7 +163,7 @@ simply add the following image to the `imageList`: ```json "imageList": { "images": [ - "paketobuildpacks/builder:base", + "paketobuildpacks/builder:base" ], "allowDerivedImages": true } @@ -179,29 +174,53 @@ When the buildpack runs, it will create an ephemeral image derived from allow this because it will notice that the ephemeral image is derived from an allowed image. -The behavior is enabled by default. It can be disabled by setting -`allowDerivedImages=false` in the `admin-settings.json` file. In general it is -not recommended that you disable this setting unless you know it won't be -required. +The behavior is disabled by default and must be explicitly enabled by setting +`"allowDerivedImages": true` as shown above. In general it is recommended that +you disable this setting unless you know it's required. + +A few caveats: -A couple of caveats: +* Setting `"allowedDerivedImages" :true` will impact the startup time of + containers by up to 1 extra second, as Docker Desktop needs to perform + some more checks on the container image. * The `allowDerivedImages` setting only applies to local-only images built from an allowed image. That is, the derived image must not be present in a remote - repository (because if it were, you would just list it's name in the `imageList`). + repository because if it were, you would just list its name in the `imageList`. * For derived image checking to work, the parent image (i.e., the image in the `imageList`) must be present locally (i.e., must have been explicitly pulled from a repository). This is usually not a problem as the tools that need this feature (e.g., Paketo buildpacks) will do the pre-pull of the parent image. -* The `allowDerivedImages` setting applies to all images in the `imageList` - specified with an explicit tag (e.g., `:`). It does not apply to - images specified using the tag wildcard (e.g., `:*`) described in the - prior section, because Docker Desktop needs to know the tag in order to - perform ancestor-descendant image checks. Therefore, if you want Docker socket - mounts to be allowed for images derived from a parent image in the - `imageList`, make sure the parent image is listed with name and tag. +* For Docker Desktop versions 4.34 and 4.35 only: The `allowDerivedImages` setting + applies to all images in the `imageList` specified with an explicit tag (e.g., + `:`). It does not apply to images specified using the tag wildcard + (e.g., `:*`) described in the prior section. In Docker Desktop 4.36 and + later, this caveat no longer applies, meaning that the `allowDerivedImages` + settings applies to images specified with or without a wildcard tag. This + makes it easier to manage the ECI Docker socket image list. + +### Allowing all containers to mount the Docker socket + +In Docker Desktop version 4.36 and later, it's possible to configure the image +list to allow any container to mount the Docker socket. You do this by adding +`"*"` to the `imageList`: + +```json +"imageList": { + "images": [ + "*" + ] +} +``` + +This tells Docker Desktop to allow all containers to mount the Docker socket +which increases flexibility but reduces security. It also improves container +startup time when using Enhanced Container Isolation. + +It is recommended that you use this only in scenarios where explicitly listing +allowed container images is not flexible enough. ### Command list @@ -302,10 +321,13 @@ Whether to configure the list as an allow or deny list depends on the use case. this case, remove the local image and pull it again (e.g., `docker rm ` and `docker pull `). -* It's not possible to allow Docker socket bind-mounts on local images (i.e., images that are not on - a registry) unless they are [derived from an allowed image](#docker-socket-mount-permissions-for-derived-images). - That's because Docker Desktop pulls the digests for the allowed images from the - registry, and then uses that to compare against the local copy of the image. +* It's not possible to allow Docker socket bind-mounts on containers using + local-only images (i.e., images that are not on a registry) unless they are + [derived from an allowed image](#docker-socket-mount-permissions-for-derived-images) + or you've [allowed all containers to mount the Docker socket](#allowing-all-containers-to-mount-the-docker-socket). + That is because Docker Desktop pulls the digests for the allowed images from + the registry, and then uses that to compare against the local copy of the + image. * The `commandList` configuration applies to all containers that are allowed to bind-mount the Docker socket. Therefore it can't be configured differently per @@ -315,17 +337,16 @@ Whether to configure the list as an allow or deny list depends on the use case. | Unsupported command | Description | | :------------------- | :---------- | -| compose | Docker compose | -| dev | Docker dev environments | -| extension | Manages Docker extensions | -| feedback | Send feedback to Docker | -| init | Creates Docker-related starter files | -| manifest | Manages Docker image manifests | -| plugins | Manages plugins | -| sbom | View Software Bill of Materials (SBOM) | -| scan | Docker Scan | -| scout | Docker Scout | -| trust | Manage trust on Docker images | +| `compose` | Docker Compose | +| `dev` | Dev environments | +| `extension` | Manages Docker Extensions | +| `feedback` | Send feedback to Docker | +| `init` | Creates Docker-related starter files | +| `manifest` | Manages Docker image manifests | +| `plugin` | Manages plugins | +| `sbom` | View Software Bill of Materials (SBOM) | +| `scout` | Docker Scout | +| `trust` | Manage trust on Docker images | > [!NOTE] > diff --git a/content/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/faq.md b/content/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/faq.md index 313b5509252..a2f7048eee3 100644 --- a/content/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/faq.md +++ b/content/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/faq.md @@ -1,5 +1,5 @@ --- -title: Enhanced Container Isolation (ECI) FAQs +title: Enhanced Container Isolation FAQs linkTitle: FAQs description: Frequently asked questions for Enhanced Container Isolation keywords: enhanced container isolation, security, faq, sysbox, Docker Desktop @@ -26,12 +26,12 @@ minimum. Yes, you can use the `--privileged` flag in containers but unlike privileged containers without ECI, the container can only use it's elevated privileges to access resources assigned to the container. It can't access global kernel -resources in the Docker Desktop Linux VM. This allows you to run privileged +resources in the Docker Desktop Linux VM. This lets you run privileged containers securely (including Docker-in-Docker). For more information, see [Key features and benefits](features-benefits.md#privileged-containers-are-also-secured). ### Will all privileged container workloads run with ECI? -No. Privileged container workloads that wish to access global kernel resources +No. Privileged container workloads that want to access global kernel resources inside the Docker Desktop Linux VM won't work. For example, you can't use a privileged container to load a kernel module. @@ -61,7 +61,7 @@ when using [Testcontainers](https://testcontainers.com/) for local testing. To enable such use cases, it's possible to configure ECI to allow Docker socket mounts into containers, but only for your chosen (i.e,. trusted) container images, and -even restrict what commands the container can send to the Docker engine via the socket. +even restrict what commands the container can send to the Docker Engine via the socket. See [ECI Docker socket mount permissions](config.md#docker-socket-mount-permissions). ### Does ECI protect all containers launched with Docker Desktop? @@ -80,16 +80,16 @@ Desktop 4.19 and on all supported platforms (Windows with WSL 2 or Hyper-V, Mac, and Linux). ECI does not yet protect Docker Desktop Kubernetes pods, Extension containers, -and [Dev Environments containers](/manuals/desktop/dev-environments/_index.md). +and [Dev Environments containers](/manuals/desktop/features/dev-environments/_index.md). ### Does ECI protect containers launched prior to enabling ECI? -No. Containers created prior to switching on ECI are not protected. Therefore, we -recommend removing all containers prior to switching on ECI. +No. Containers created prior to switching on ECI are not protected. Therefore, it is +recommended you remove all containers prior to switching on ECI. ### Does ECI affect the performance of containers? -ECI has very little impact on the performance of +ECI has little impact on the performance of containers. The exception is for containers that perform lots of `mount` and `umount` system calls, as these are trapped and vetted by the Sysbox container runtime to ensure they are not being used to breach the container's filesystem. @@ -101,10 +101,10 @@ containers deployed by Docker Desktop users. If a user attempts to override the runtime (e.g., `docker run --runtime=runc`), this request is ignored and the container is created through the Sysbox runtime. -The reason `runc` is disallowed with ECI because it allows users to run as "true +The reason `runc` is disallowed is it lets users run as "true root" on the Docker Desktop Linux VM, thereby providing them with implicit control of the VM and the ability to modify the administrative configurations -for Docker Desktop, for example. +for Docker Desktop. ### How is ECI different from Docker Engine's userns-remap mode? diff --git a/content/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/features-benefits.md b/content/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/features-benefits.md index ac55982f881..87e58442a36 100644 --- a/content/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/features-benefits.md +++ b/content/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/features-benefits.md @@ -7,9 +7,9 @@ aliases: weight: 20 --- -### Linux User Namespace on all containers +## Linux user namespace on all containers -With Enhanced Container Isolation, all user containers leverage the [Linux user-namespace](https://man7.org/linux/man-pages/man7/user_namespaces.7.html) +With Enhanced Container Isolation, all user containers leverage the [Linux user namespace](https://man7.org/linux/man-pages/man7/user_namespaces.7.html) for extra isolation. This means that the root user in the container maps to an unprivileged user in the Docker Desktop Linux VM. @@ -21,7 +21,7 @@ $ docker run -it --rm --name=first alpine 0 100000 65536 ``` -The output `0 100000 65536` is the signature of the Linux user-namespace. It +The output `0 100000 65536` is the signature of the Linux user namespace. It means that the root user (0) in the container is mapped to unprivileged user 100000 in the Docker Desktop Linux VM, and the mapping extends for a continuous range of 64K user IDs. The same applies to group IDs. @@ -44,28 +44,25 @@ $ docker run -it --rm alpine 0 0 4294967295 ``` -By virtue of using the Linux user-namespace, Enhanced Container Isolation +By virtue of using the Linux user namespace, Enhanced Container Isolation ensures the container processes never run as user ID 0 (true root) in the Linux VM. In fact they never run with any valid user-ID in the Linux VM. Thus, their Linux capabilities are constrained to resources within the container only, increasing isolation significantly compared to regular containers, both container-to-host and cross-container isolation. -### Privileged containers are also secured +## Privileged containers are also secured Privileged containers `docker run --privileged ...` are insecure because they give the container full access to the Linux kernel. That is, the container runs as true root with all capabilities enabled, seccomp and AppArmor restrictions are disabled, all hardware devices are exposed, for example. -For organizations that wish to secure Docker Desktop on their developer's -machines, privileged containers are problematic as they allow container -workloads whether benign or malicious to gain control of the Linux kernel -inside the Docker Desktop VM and thus modify security related settings, for example registry +Organizations aiming to secure Docker Desktop on developers' machines face challenges with privileged containers. These containers, whether running benign or malicious workloads, can gain control of the Linux kernel within the Docker Desktop VM, potentially altering security related settings, for example registry access management, and network proxies. With Enhanced Container Isolation, privileged containers can no longer do -this. The combination of the Linux user-namespace and other security techniques +this. The combination of the Linux user namespace and other security techniques used by Sysbox ensures that processes inside a privileged container can only access resources assigned to the container. @@ -74,13 +71,12 @@ access resources assigned to the container. > Enhanced Container Isolation does not prevent users from launching privileged > containers, but rather runs them securely by ensuring that they can only > modify resources associated with the container. Privileged workloads that -> modify global kernel settings, for example loading a kernel module or changing BPF +> modify global kernel settings, for example loading a kernel module or changing Berkeley Packet Filters (BPF) > settings will not work properly as they will receive "permission > denied" error when attempting such operations. For example, Enhanced Container Isolation ensures privileged containers can't -access Docker Desktop network settings in the Linux VM configured via Berkeley -Packet Filters (BPF): +access Docker Desktop network settings in the Linux VM configured via BPF: ```console $ docker run --privileged djs55/bpftool map show @@ -105,13 +101,13 @@ example Docker-in-Docker, Kubernetes-in-Docker, etc. With Enhanced Container Isolation you can still run such workloads but do so much more securely than before. -### Containers can't share namespaces with the Linux VM +## Containers can't share namespaces with the Linux VM When Enhanced Container Isolation is enabled, containers can't share Linux -namespaces with the host (e.g., pid, network, uts, etc.) as that essentially +namespaces with the host (e.g., PID, network, uts, etc.) as that essentially breaks isolation. -For example, sharing the pid namespace fails: +For example, sharing the PID namespace fails: ```console $ docker run -it --rm --pid=host alpine @@ -125,7 +121,7 @@ $ docker run -it --rm --network=host alpine docker: Error response from daemon: failed to create shim task: OCI runtime create failed: error in the container spec: invalid or unsupported container spec: sysbox containers can't share a network namespace with the host (because they use the linux user-namespace for isolation): unknown. ``` -In addition, the `--userns=host` flag, used to disable the user-namespace on the +In addition, the `--userns=host` flag, used to disable the user namespace on the container, is ignored: ```console @@ -138,7 +134,7 @@ Finally, Docker build `--network=host` and Docker buildx entitlements (`network.host`, `security.insecure`) are not allowed. Builds that require these won't work properly. -### Bind mount restrictions +## Bind mount restrictions When Enhanced Container Isolation is enabled, Docker Desktop users can continue to bind mount host directories into containers as configured via **Settings** > @@ -147,7 +143,7 @@ arbitrary Linux VM directories into containers. This prevents containers from modifying sensitive files inside the Docker Desktop Linux VM, files that can hold configurations for registry access -management, proxies, docker engine configurations, and more. +management, proxies, Docker Engine configurations, and more. For example, the following bind mount of the Docker Engine's configuration file (`/etc/docker/daemon.json` inside the Linux VM) into a container is restricted @@ -162,7 +158,7 @@ In contrast, without Enhanced Container Isolation this mount works and gives the container full read and write access to the Docker Engine's configuration. Of course, bind mounts of host files continue to work as usual. For example, -assuming a user configures Docker Desktop to file share her $HOME directory, +assuming a user configures Docker Desktop to file share her `$HOME` directory, she can bind mount it into the container: ```console @@ -173,16 +169,16 @@ $ docker run -it --rm -v $HOME:/mnt alpine > [!NOTE] > > By default, Enhanced Container Isolation won't allow bind mounting the Docker Engine socket -> (/var/run/docker.sock) into a container, as doing so essentially grants the +> (`/var/run/docker.sock`) into a container, as doing so essentially grants the > container control of Docker Engine, thus breaking container isolation. However, > as some legitimate use cases require this, it's possible to relax > this restriction for trusted container images. See [Docker socket mount permissions](config.md#docker-socket-mount-permissions). -### Vetting sensitive system calls +## Vetting sensitive system calls Another feature of Enhanced Container Isolation is that it intercepts and vets a few highly sensitive system calls inside containers, such as `mount` and -`umount`. This ensures that processes that have capabilities to execute these +`umount`. This ensures that processes that have capabilities to execute these system calls can't use them to breach the container. For example, a container that has `CAP_SYS_ADMIN` (required to execute the @@ -200,7 +196,7 @@ read-only, it can't be changed from within the container to read-write, even if ensures container processes can't use `mount`, or `umount`, to breach the container's root filesystem. -Note however that in the example above the container can still create mounts +Note however that in the previous example the container can still create mounts within the container, and mount them read-only or read-write as needed. Those mounts are allowed since they occur within the container, and therefore don't breach it's root filesystem: @@ -226,43 +222,42 @@ that it does not affect the performance of containers in the great majority of cases. It intercepts control-path system calls that are rarely used in most container workloads but data-path system calls are not intercepted. -### Filesystem user-ID mappings +## Filesystem user-ID mappings -As mentioned above, Enhanced Container Isolation enables the Linux -user-namespace on all containers and this ensures that the container's user-ID +As mentioned, ECI enables the Linux +user namespace on all containers. This ensures that the container's user-ID range (0->64K) maps to an unprivileged range of "real" user-IDs in the Docker Desktop Linux VM (e.g., 100000->165535). Moreover, each container gets an exclusive range of real user-IDs in the Linux VM (e.g., container 0 could get mapped to 100000->165535, container 2 to -165536->231071, container 3 to 231072->296607, and so on). Same applies to +165536->231071, container 3 to 231072->296607, and so on). The same applies to group-IDs. In addition, if a container is stopped and restarted, there is no -guarantee it will receive the same mapping as before. This by design and further -improves security. +guarantee it will receive the same mapping as before. This is by design and +further improves security. -However the above presents a problem when mounting Docker volumes into -containers, as the files written to such volumes will have the real -user/group-IDs and will therefore won't be accessible across a container's +However this presents a problem when mounting Docker volumes into +containers. Files written to such volumes have the real +user/group-IDs and therefore won't be accessible across a container's start/stop/restart, or between containers due to the different real user-ID/group-ID of each container. To solve this problem, Sysbox uses "filesystem user-ID remapping" via the Linux -Kernel's ID-mapped mounts feature (added in 2021) or an alternative module -called shiftfs. These technologies map filesystem accesses from the container's +Kernel's ID-mapped mounts feature (added in 2021) or an alternative `shiftsfs` module. These technologies map filesystem accesses from the container's real user-ID (e.g., range 100000->165535) to the range (0->65535) inside Docker Desktop's Linux VM. This way, volumes can now be mounted or shared across containers, even if each container uses an exclusive range of user-IDs. Users need not worry about the container's real user-IDs. -Note that although filesystem user-ID remapping may cause containers to access -Linux VM files mounted into the container with real user-ID 0 (i.e., root), the -[restricted mounts feature](#bind-mount-restrictions) described above ensures -that no Linux VM sensitive files can be mounted into the container. +Although filesystem user-ID remapping may cause containers to access +Linux VM files mounted into the container with real user-ID 0, the +[restricted mounts feature](#bind-mount-restrictions) ensures +that sensitive Linux VM files can't be mounted into the container. -### Procfs & Sysfs Emulation +## Procfs & sysfs emulation Another feature of Enhanced Container Isolation is that inside each container, -the procfs ("/proc") and sysfs ("/sys") filesystems are partially emulated. This +the `/proc` and `/sys` filesystems are partially emulated. This serves several purposes, such as hiding sensitive host information inside the container and namespacing host kernel resources that are not yet namespaced by the Linux kernel itself. diff --git a/content/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/how-eci-works.md b/content/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/how-eci-works.md index 8311006ffe2..9b8c3b65fdc 100644 --- a/content/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/how-eci-works.md +++ b/content/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/how-eci-works.md @@ -12,9 +12,6 @@ container runtime](https://github.com/nestybox/sysbox). Sysbox is a fork of the standard OCI runc runtime that was modified to enhance standard container isolation and workloads. For more details see [Under the hood](#under-the-hood). -Starting with version 4.13, Docker Desktop includes a customized version of -Sysbox. - When [Enhanced Container Isolation is enabled](index.md#how-do-i-enable-enhanced-container-isolation), containers created by users through `docker run` or `docker create` are automatically launched using Sysbox instead of the standard OCI runc runtime. Users need not @@ -28,11 +25,10 @@ to breach the Docker Desktop Virtual Machine (VM) or other containers. > [!NOTE] > > When Enhanced Container Isolation is enabled in Docker Desktop, the Docker CLI -> "--runtime" flag is ignored. Docker's default runtime continues to be "runc", +> `--runtime` flag is ignored. Docker's default runtime continues to be `runc`, > but all user containers are implicitly launched with Sysbox. -Enhanced Container Isolation is not the same as Docker Engine's userns-remap -mode or Rootless Docker. This is explained further below. +Enhanced Container Isolation is not the same as [Docker Engine's userns-remap mode or Rootless Docker](#enhanced-container-isolation-versus-user-namespace-remapping). ### Under the hood @@ -42,23 +38,23 @@ Sysbox enhances container isolation by using techniques such as: * Restricting the container from mounting sensitive VM directories. * Vetting sensitive system-calls between the container and the Linux kernel. * Mapping filesystem user/group IDs between the container's user-namespace and the Linux VM. -* Emulating portions of the procfs and sysfs filesystems inside the container. +* Emulating portions of the `/proc` and `/sys` filesystems inside the container. Some of these are made possible by recent advances in the Linux kernel which Docker Desktop now incorporates. Sysbox applies these techniques with minimal functional or performance impact to containers. These techniques complement Docker's traditional container security mechanisms -such as using other Linux namespaces, cgroups, restricted Linux capabilities, -seccomp, and AppArmor. They add a strong layer of isolation between the +such as using other Linux namespaces, cgroups, restricted Linux Capabilities, +Seccomp, and AppArmor. They add a strong layer of isolation between the container and the Linux kernel inside the Docker Desktop VM. For more information, see [Key features and benefits](features-benefits.md). -### Enhanced Container Isolation vs Docker Userns-Remap Mode +### Enhanced Container Isolation versus user namespace remapping The Docker Engine includes a feature called [userns-remap mode](/engine/security/userns-remap/) -that enables the user-namespace in all containers. However it suffers from a few +that enables the user namespace in all containers. However it suffers from a few [limitations](/engine/security/userns-remap/) and it's not supported within Docker Desktop. @@ -70,16 +66,16 @@ exclusive user-namespace mappings per container automatically and adds several other [container isolation features](#under-the-hood) meant to secure Docker Desktop in organizations with stringent security requirements. -### Enhanced Container Isolation vs Rootless Docker +### Enhanced Container Isolation versus Rootless Docker -[Rootless Docker](/engine/security/rootless/) allows the Docker Engine, and by +[Rootless Docker](/engine/security/rootless/) lets Docker Engine, and by extension the containers, to run without root privileges natively on a Linux host. This -allows non-root users to install and run Docker natively on Linux. +lets non-root users to install and run Docker natively on Linux. Rootless Docker is not supported within Docker Desktop. While it's a valuable feature when running Docker natively on Linux, its value within Docker Desktop is reduced since Docker Desktop runs the Docker Engine within a Linux VM. That -is, Docker Desktop already allows non-root host users to run Docker and +is, Docker Desktop already lets non-root host users to run Docker and isolates the Docker Engine from the host using a virtual machine. Unlike Rootless Docker, Enhanced Container Isolation does not run Docker Engine diff --git a/content/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/limitations.md b/content/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/limitations.md index 96eb70aa2c0..758e5389701 100644 --- a/content/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/limitations.md +++ b/content/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/limitations.md @@ -8,44 +8,35 @@ weight: 50 ### ECI support for WSL -Prior to Docker Desktop 4.20, Enhanced Container Isolation (ECI) on -Windows hosts was only supported when Docker Desktop was configured to use -Hyper-V to create the Docker Desktop Linux VM. ECI was not supported when Docker -Desktop was configured to use Windows Subsystem for Linux (aka WSL). - -Starting with Docker Desktop 4.20, ECI is supported when Docker Desktop is -configured to use either Hyper-V or WSL 2. - ->**Note** +> [!NOTE] > > Docker Desktop requires WSL 2 version 1.1.3.0 or later. To get the current > version of WSL on your host, type `wsl --version`. If the command fails or if > it returns a version number prior to 1.1.3.0, update WSL to the latest version > by typing `wsl --update` in a Windows command or PowerShell terminal. -Note however that ECI on WSL is not as secure as on Hyper-V because: +ECI on WSL is not as secure as on Hyper-V because: -* While ECI on WSL still hardens containers so that malicious workloads can't +- While ECI on WSL still hardens containers so that malicious workloads can't easily breach Docker Desktop's Linux VM, ECI on WSL can't prevent Docker Desktop users from breaching the Docker Desktop Linux VM. Such users can trivially access that VM (as root) with the `wsl -d docker-desktop` command, and use that access to modify Docker Engine settings inside the VM. This gives - Docker Desktop users control of the Docker Desktop VM and allows them to - bypass Docker Desktop configs set by admins via the + Docker Desktop users control of the Docker Desktop VM and lets them bypass Docker Desktop configs set by administrators via the [settings-management](../settings-management/_index.md) feature. In contrast, - ECI on Hyper-V does not allow Docker Desktop users to breach the Docker + ECI on Hyper-V does not let Docker Desktop users to breach the Docker Desktop Linux VM. -* With WSL 2, all WSL 2 distros on the same Windows host share the same instance +- With WSL 2, all WSL 2 distributions on the same Windows host share the same instance of the Linux kernel. As a result, Docker Desktop can't ensure the integrity of - the kernel in the Docker Desktop Linux VM since another WSL 2 distro could + the kernel in the Docker Desktop Linux VM since another WSL 2 distribution could modify shared kernel settings. In contrast, when using Hyper-V, the Docker Desktop Linux VM has a dedicated kernel that is solely under the control of Docker Desktop. -The table below summarizes this. +The following table summarizes this. -| Security Feature | ECI on WSL | ECI on Hyper-V | Comment | +| Security feature | ECI on WSL | ECI on Hyper-V | Comment | | -------------------------------------------------- | ------------ | ---------------- | --------------------- | | Strongly secure containers | Yes | Yes | Makes it harder for malicious container workloads to breach the Docker Desktop Linux VM and host. | | Docker Desktop Linux VM protected from user access | No | Yes | On WSL, users can access Docker Engine directly or bypass Docker Desktop security settings. | @@ -53,27 +44,21 @@ The table below summarizes this. In general, using ECI with Hyper-V is more secure than with WSL 2. But WSL 2 offers advantages for performance and resource utilization on the host machine, -and it's an excellent way for users to run their favorite Linux distro on -Windows hosts and access Docker from within (see Docker Desktop's WSL distro -integration feature, enabled via the Dashboard's **Settings** > **Resources** > **WSL Integration**). +and it's an excellent way for users to run their favorite Linux distribution on +Windows hosts and access Docker from within. -### ECI protection for Docker Builds with the "Docker" driver +### ECI protection for Docker builds with the "docker" driver Prior to Docker Desktop 4.30, `docker build` commands that use the buildx -`docker` driver (the default) are not protected by ECI (i.e., the build runs -rootful inside the Docker Desktop VM). +`docker` driver (the default) are not protected by ECI, in other words the build runs +rootful inside the Docker Desktop VM. Starting with Docker Desktop 4.30, `docker build` commands that use the buildx -`docker` driver are protected by ECI (i.e., the build runs rootless inside -the Docker Desktop VM), except when Docker Desktop is configured to use WSL 2 -(on Windows hosts). We expect to improve on this in future versions of Docker -Desktop. +`docker` driver are protected by ECI, except when Docker Desktop is configured to use WSL 2 +(on Windows hosts). Note that `docker build` commands that use the `docker-container` driver are -always protected by ECI (i.e., the build runs inside a rootless Docker -container). This is true since Docker Desktop 4.19 (when ECI was introduced) and -on all platforms where Docker Desktop is supported (Windows with WSL or Hyper-V, -Mac, and Linux). +always protected by ECI. ### Docker Build and Buildx have some restrictions @@ -98,17 +83,15 @@ arrangements are needed, just enable ECI and run the KinD tool as usual. Extension containers are also not yet protected by ECI. Ensure you extension containers come from trusted entities to avoid issues. -### Docker Desktop dev environments are not yet protected +### Docker Desktop Dev Environments are not yet protected Containers launched by the Docker Desktop Dev Environments feature are not yet -protected either. We expect to improve on this in future versions of Docker -Desktop. +protected. ### Docker Debug containers are not yet protected [Docker Debug](https://docs.docker.com/reference/cli/docker/debug/) containers -are not yet protected by ECI. We expect to improve on this in future versions of -Docker Desktop. +are not yet protected by ECI. ### Native Windows containers are not supported diff --git a/content/manuals/security/for-admins/hardened-desktop/image-access-management.md b/content/manuals/security/for-admins/hardened-desktop/image-access-management.md index 2314c8d983f..cb6115b7a8e 100644 --- a/content/manuals/security/for-admins/hardened-desktop/image-access-management.md +++ b/content/manuals/security/for-admins/hardened-desktop/image-access-management.md @@ -12,22 +12,17 @@ weight: 40 > [!NOTE] > -> Image Access Management is available to [Docker Business](/manuals/subscription/core-subscription/details.md#docker-business) customers only. +> Image Access Management is available to [Docker Business](/manuals/subscription/details.md#docker-business) customers only. -Image Access Management gives administrators control over which types of images, such as Docker Official Images, Docker Verified Publisher Images, or community images, their developers can pull from Docker Hub. +Image Access Management gives you control over which types of images, such as Docker Official Images, Docker Verified Publisher Images, or community images, your developers can pull from Docker Hub. For example, a developer, who is part of an organization, building a new containerized application could accidentally use an untrusted, community image as a component of their application. This image could be malicious and pose a security risk to the company. Using Image Access Management, the organization owner can ensure that the developer can only access trusted content like Docker Official Images, Docker Verified Publisher Images, or the organization’s own images, preventing such a risk. ## Prerequisites -You need to [enforce sign-in](../enforce-sign-in/_index.md). For Image Access -Management to take effect, Docker Desktop users must authenticate to your -organization. Enforcing sign-in ensures that your Docker Desktop developers -always authenticate to your organization, even though they can authenticate -without it and the feature will take effect. Enforcing sign-in guarantees the -feature always takes effect. +You first need to [enforce sign-in](/manuals/security/for-admins/enforce-sign-in/_index.md) to ensure that all Docker Desktop developers authenticate with your organization. Since Image Access Management requires a Docker Business subscription, enforced sign-in guarantees that only authenticated users have access and that the feature consistently takes effect across all users, even though it may still work without enforced sign-in. -## Configure Image Access Management permissions +## Configure {{< tabs >}} {{< tab name="Docker Hub" >}} diff --git a/content/manuals/security/for-admins/hardened-desktop/registry-access-management.md b/content/manuals/security/for-admins/hardened-desktop/registry-access-management.md index fa8763e1570..7c710090796 100644 --- a/content/manuals/security/for-admins/hardened-desktop/registry-access-management.md +++ b/content/manuals/security/for-admins/hardened-desktop/registry-access-management.md @@ -12,7 +12,7 @@ weight: 30 > [!NOTE] > -> Registry Access Management is available to [Docker Business](/manuals/subscription/core-subscription/details.md) customers only. +> Registry Access Management is available to [Docker Business](/manuals/subscription/details.md) customers only. With Registry Access Management (RAM), administrators can ensure that their developers using Docker Desktop only access allowed registries. This is done through the Registry Access Management dashboard in Docker Hub or the Docker Admin Console. @@ -62,7 +62,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 by default. For Registry Access Management to take effect on Windows Container mode, you must allow the Windows Docker daemon to use Docker Desktop's internal proxy by selecting the [Use proxy for Windows Docker daemon](/manuals/desktop/settings.md#proxies) setting. +- Windows image pulls and image builds are not restricted by default. For Registry Access Management to take effect on Windows Container mode, you must allow the Windows Docker daemon to use Docker Desktop's internal proxy by selecting the [Use proxy for Windows Docker daemon](/manuals/desktop/settings-and-maintenance/settings.md#proxies) setting. - 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/content/manuals/security/for-admins/hardened-desktop/settings-management/_index.md b/content/manuals/security/for-admins/hardened-desktop/settings-management/_index.md index 03cd8324bf1..cb08fa970c9 100644 --- a/content/manuals/security/for-admins/hardened-desktop/settings-management/_index.md +++ b/content/manuals/security/for-admins/hardened-desktop/settings-management/_index.md @@ -9,31 +9,31 @@ aliases: weight: 10 --- ->**Note** +> [!NOTE] > ->Settings Management is available to Docker Business customers only. +> Settings Management is available to Docker Business customers only. -Settings Management is a feature that helps admins to control certain Docker Desktop settings on client machines within their organization. +Settings Management helps you control key Docker Desktop settings, like proxies and network configurations, on your developers' machines within your organization. -With a few lines of JSON, admins can configure controls for Docker Desktop settings such as proxies and network settings. For an extra layer of security, admins can also use Settings Management to enable and lock in [Enhanced Container Isolation](../enhanced-container-isolation/_index.md) which ensures that any configurations set with Settings Management cannot be modified by containers. +For an extra layer of security, you can also use Settings Management to enable and lock in [Enhanced Container Isolation](../enhanced-container-isolation/_index.md), which prevents containers from modifying any Settings Management configurations. -It is available with [Docker Desktop 4.13.0 and later](/manuals/desktop/release-notes.md). - -### Who is it for? +## Who is it for? - For organizations that want to configure Docker Desktop to be within their organization's centralized control. - For organizations that want to create a standardized Docker Desktop environment at scale. - For Docker Business customers who want to confidently manage their use of Docker Desktop within tightly regulated environments. -### How does it work? +## How does it work? -Administrators can configure several Docker Desktop settings using an `admin-settings.json` file. This file is located on the Docker Desktop host and can only be accessed by developers with root or admin privileges. +You can configure several Docker Desktop settings using either: + - An `admin-settings.json` file. This file is located on the Docker Desktop host and can only be accessed by developers with root or administrator privileges. + - Creating a settings policy in the Docker Admin Console -Values that are set to `locked: true` within the `admin-settings.json` override any previous values set by developers and ensure that these cannot be modified. For more information, see [Configure Settings Management](configure.md#step-two-configure-the-settings-you-want-to-lock-in). +Settings that are defined by an administrator override any previous values set by developers and ensure that these cannot be modified. -### What features can I configure with Settings Management? +## What features can I configure with Settings Management? -Using the `admin-settings.json` file, admins can: +Using the `admin-settings.json` file, you can: - Turn on and lock in [Enhanced Container Isolation](../enhanced-container-isolation/_index.md) - Configure HTTP proxies @@ -46,40 +46,38 @@ Using the `admin-settings.json` file, admins can: - Turn off Docker Extensions - Turn off Docker Scout SBOM indexing - Turn off beta and experimental features +- Turn off Docker AI ([Ask Gordon](../../../../desktop/features/gordon.md)) - Turn off Docker Desktop's onboarding survey - Control whether developers can use the Docker terminal - Control the file sharing implementation for your developers on macOS - Specify which paths your developers can add file shares to -- Configure Air-Gapped Containers - -For more details on the syntax and options admins can set, see [Configure Settings Management](configure.md). +- Configure Air-gapped containers -### How do I set up and enforce Settings Management? +For more details on the syntax and options, see [Configure Settings Management](configure-json-file.md). -As an administrator, you first need to [enforce -sign-in](/manuals/security/for-admins/enforce-sign-in/_index.md). This is -because the Settings Management feature requires a Docker Business subscription -and therefore your Docker Desktop developers must authenticate to your -organization. Enforcing sign-in ensures that your Docker Desktop developers -always authenticate to your organization, even though they can authenticate -without it and the feature will take effect. Enforcing sign-in guarantees the -feature always takes effect. +## How do I set up and enforce Settings Management? +You first need to [enforce sign-in](/manuals/security/for-admins/enforce-sign-in/_index.md) to ensure that all Docker Desktop developers authenticate with your organization. Since the Settings Management feature requires a Docker Business subscription, enforced sign-in guarantees that only authenticated users have access and that the feature consistently takes effect across all users, even though it may still work without enforced sign-in. -Next, you must either manually [create and configure the admin-settings.json file](configure.md), or use the `--admin-settings` installer flag on [macOS](/manuals/desktop/install/mac-install.md#install-from-the-command-line) or [Windows](/manuals/desktop/install/windows-install.md#install-from-the-command-line) to automatically create the `admin-settings.json` and save it in the correct location. +Next, you must either: + - Manually [create and configure the `admin-settings.json` file](configure-json-file.md), or use the `--admin-settings` installer flag on [macOS](/manuals/desktop/setup/install/mac-install.md#install-from-the-command-line) or [Windows](/manuals/desktop/setup/install/windows-install.md#install-from-the-command-line) to automatically create the `admin-settings.json` and save it in the correct location. + - Fill out the **Settings policy** creation form in the [Docker Admin Console](configure-admin-console.md). Once this is done, Docker Desktop developers receive the changed settings when they either: - Quit, re-launch, and sign in to Docker Desktop - Launch and sign in to Docker Desktop for the first time -Docker doesn't automatically mandate that developers re-launch and re-authenticate once a change has been made, so as not to disrupt your developers' workflow. +To avoid disrupting your developers' workflows, Docker doesn't automatically require that developers re-launch and re-authenticate once a change has been made. + +## What do developers see when the settings are enforced? -### What do developers see when the settings are enforced? +Enforced settings appear grayed out in Docker Desktop. They can't be edited via the Docker Desktop Dashboard, CLI, or `settings-store.json` (or `settings.json` for Docker Desktop 4.34 and earlier). -Any settings that are enforced, are grayed out in Docker Desktop and the user is unable to edit them, either via the Docker Desktop UI, CLI, or the `settings-store.json` file (or `settings.json` for Docker Desktop versions 4.34 and earlier). In addition, if Enhanced Container Isolation is enforced, developers can't use privileged containers or similar techniques to modify enforced settings within the Docker Desktop Linux VM, for example, reconfigure proxy and networking of reconfigure Docker Engine. +In addition, if Enhanced Container Isolation is enforced, developers can't use privileged containers or similar techniques to modify enforced settings within the Docker Desktop Linux VM. For example, they can't reconfigure proxy and networking, or Docker Engine. ![Proxy settings grayed out](/assets/images/grayed-setting.png) -## More resources +## What's next? -- [Video: Settings Management](https://www.youtube.com/watch?v=I9oJOJ1P9PQ) +- [Configure Settings Management with a `.json` file](configure-json-file.md) +- [Configure Settings Management with the Docker Admin Console](configure-admin-console.md) diff --git a/content/manuals/security/for-admins/hardened-desktop/settings-management/configure-admin-console.md b/content/manuals/security/for-admins/hardened-desktop/settings-management/configure-admin-console.md new file mode 100644 index 00000000000..11a6f052970 --- /dev/null +++ b/content/manuals/security/for-admins/hardened-desktop/settings-management/configure-admin-console.md @@ -0,0 +1,81 @@ +--- +description: How to configure Settings Management for Docker Desktop using the Docker Admin Console +keywords: admin, controls, rootless, enhanced container isolation +title: Configure Settings Management with the Admin Console +linkTitle: Use the Admin Console +weight: 20 +params: + sidebar: + badge: + color: violet + text: EA +--- + +{{% restricted title="Early Access" %}} +Settings Management in the Docker Admin Console is an [early access](/release-lifecycle#early-access-ea) feature and is available to Docker Business customers only. +{{% /restricted %}} + +This page contains information for administrators on how to configure Settings Management with the Docker Admin Console. You can specify and lock configuration parameters to create a standardized Docker Desktop environment across your Docker company or organization. + +## Prerequisites + +- [Download and install Docker Desktop 4.36.0 or later](/manuals/desktop/release-notes.md). +- [Verify your domain](/manuals/security/for-admins/single-sign-on/configure.md#step-one-add-and-verify-your-domain). +- [Enforce sign-in](/manuals/security/for-admins/enforce-sign-in/_index.md). The Settings Management feature requires a Docker Business +subscription, therefore your Docker Desktop users must authenticate to your +organization for configurations to take effect. + +## Create a settings policy + +1. Within the [Docker Admin Console](https://admin.docker.com/) navigate to the company or organization you want to define a settings policy for. +2. Under the **Security and access** section, select **Desktop Settings Management**. +3. In the top-right corner, select **Create a settings policy**. +4. Give your settings policy a name and an optional description. + + > [!TIP] + > + > If you have already configured Settings Management with an `admin-settings.json` file for an organization, you can upload it using the **Upload existing settings** button which then automatically populates the form for you. + > + > Settings policies deployed via the Docker Admin Console take precedence over manually deployed `admin-settings.json` files. + +5. Assign the setting policy to all your users within the company or organization, or specific users. + + > [!NOTE] + > + > If a settings policy is assigned to all users, it sets the policy as the global default policy. You can only have one global settings policy at a time. + > If a user already has a user-specific settings policy assigned, the user-specific policy takes precedence over a global policy. + + > [!TIP] + > + > Before setting a global settings policy, it is recommended that you first test it as a user-specific policy to make sure you're happy with the changes before proceeding. + +6. Configure the settings for the policy. Go through each setting and select your chosen setting state. You can choose: + - **User-defined**. Your developers are able to control and change this setting. + - **Always enabled**. This means the setting is turned on and your users won't be able to edit this setting from Docker Desktop or the CLI. + - **Enabled**. The setting is turned on and users can edit this setting from Docker Desktop or the CLI. + - **Always disabled**. This means the setting is turned off and your users won't be able to edit this setting from Docker Desktop or the CLI. + - **Disabled**. The setting is turned off and users can edit this setting from Docker Desktop or the CLI. +7. Select **Create** + +For the settings policy to take effect: +- On a new install, users need to launch Docker Desktop and authenticate to their organization. +- On an existing install, users need to quit Docker Desktop through the Docker menu, and then re-launch Docker Desktop. If they are already signed in, they don't need to sign in again for the changes to take effect. + + > [!IMPORTANT] + > + > Selecting **Restart** from the Docker menu isn't enough as it only restarts some components of Docker Desktop. + +To avoid disrupting your users' workflows, Docker doesn't automatically require that users re-launch once a change has been made. + +> [!NOTE] +> +> Settings are synced to Docker Desktop and the CLI when a user is signed in and starts Docker Desktop, and then every 60 minutes. + +If your settings policy needs to be rolled back, either delete the policy or edit the policy to set individual settings to **User-defined**. + +## Settings policy actions + +From the **Actions** menu on the **Desktop Settings Management** page in the Docker Admin Console, you can: +- Edit or delete an existing settings policy. +- Export a settings policy as an `admin-settings.json` file. +- Promote a policy that is applied to a select group of users, to be the new global default policy for all users. \ No newline at end of file diff --git a/content/manuals/security/for-admins/hardened-desktop/settings-management/configure-json-file.md b/content/manuals/security/for-admins/hardened-desktop/settings-management/configure-json-file.md new file mode 100644 index 00000000000..b59e1293881 --- /dev/null +++ b/content/manuals/security/for-admins/hardened-desktop/settings-management/configure-json-file.md @@ -0,0 +1,289 @@ +--- +description: How to configure Settings Management for Docker Desktop +keywords: admin, controls, rootless, enhanced container isolation +title: Configure Settings Management with a JSON file +linkTitle: Use a JSON file +weight: 10 +aliases: + - /desktop/hardened-desktop/settings-management/configure/ + - /security/for-admins/hardened-desktop/settings-management/configure/ +--- + +> [!NOTE] +> +> Settings Management is available to Docker Business customers only. + +This page contains information on how to configure Settings Management with an `admin-settings.json` file. You can specify and lock configuration parameters to create a standardized Docker Desktop environment across your company or organization. + +Settings Management is designed specifically for organizations who don’t give developers root access to their machines. + +## Prerequisites + +You first need to [enforce sign-in](/manuals/security/for-admins/enforce-sign-in/_index.md) to ensure that all Docker Desktop developers authenticate with your organization. Since Settings Management requires a Docker Business subscription, enforced sign-in guarantees that only authenticated users have access and that the feature consistently takes effect across all users, even though it may still work without enforced sign-in. + +## Step one: Create the `admin-settings.json` file and save it in the correct location + +You can either use the `--admin-settings` installer flag on [macOS](/manuals/desktop/setup/install/mac-install.md#install-from-the-command-line) or [Windows](/manuals/desktop/setup/install/windows-install.md#install-from-the-command-line) to automatically create the `admin-settings.json` and save it in the correct location, or set it up manually. + +To set it up manually: +1. Create a new, empty JSON file and name it `admin-settings.json`. +2. Save the `admin-settings.json` file on your developers' machines in the following locations: + - Mac: `/Library/Application\ Support/com.docker.docker/admin-settings.json` + - Windows: `C:\ProgramData\DockerDesktop\admin-settings.json` + - Linux: `/usr/share/docker-desktop/admin-settings.json` + + By placing this file in a protected directory, developers are unable to modify it. + + > [!IMPORTANT] + > + > It is assumed that you have the ability to push the `admin-settings.json` settings file to the locations specified through a device management software such as [Jamf](https://www.jamf.com/lp/en-gb/apple-mobile-device-management-mdm-jamf-shared/?attr=google_ads-brand-search-shared&gclid=CjwKCAjw1ICZBhAzEiwAFfvFhEXjayUAi8FHHv1JJitFPb47C_q_RCySTmF86twF1qJc_6GST-YDmhoCuJsQAvD_BwE). + +## Step two: Configure the settings you want to lock in + +> [!NOTE] +> +> Some of the configuration parameters only apply to certain platforms or to specific Docker Desktop versions. This is highlighted in the following table. + +The `admin-settings.json` file requires a nested list of configuration parameters, each of which must contain the `locked` parameter. You can add or remove configuration parameters as per your requirements. + +If `locked: true`, users aren't able to edit this setting from Docker Desktop or the CLI. + +If `locked: false`, it's similar to setting a factory default in that: + - For new installs, `locked: false` pre-populates the relevant settings in the Docker Desktop Dashboard, but users are able to modify it. + + - If Docker Desktop is already installed and being used, `locked: false` is ignored. This is because existing users of Docker Desktop may have already updated a setting, which in turn will have been written to the relevant config file, for example the `settings-store.json` (or `settings.json` for Docker Desktop versions 4.34 and earlier) or `daemon.json`. In these instances, the user's preferences are respected and the values aren't altered. These can be controlled by setting `locked: true`. + +The following `admin-settings.json` code and table provides an example of the required syntax and descriptions for parameters and values: + +```json {collapse=true} +{ + "configurationFileVersion": 2, + "exposeDockerAPIOnTCP2375": { + "locked": true, + "value": false + }, + "proxy": { + "locked": true, + "mode": "system", + "http": "", + "https": "", + "exclude": [], + "windowsDockerdPort": 65000, + "enableKerberosNtlm": false + }, + "containersProxy": { + "locked": true, + "mode": "manual", + "http": "", + "https": "", + "exclude": [], + "pac":"", + "transparentPorts": "" + }, + "enhancedContainerIsolation": { + "locked": true, + "value": true, + "dockerSocketMount": { + "imageList": { + "images": [ + "docker.io/localstack/localstack:*", + "docker.io/testcontainers/ryuk:*" + ] + }, + "commandList": { + "type": "deny", + "commands": ["push"] + } + } + }, + "linuxVM": { + "wslEngineEnabled": { + "locked": false, + "value": false + }, + "dockerDaemonOptions": { + "locked": false, + "value":"{\"debug\": false}" + }, + "vpnkitCIDR": { + "locked": false, + "value":"192.168.65.0/24" + } + }, + "kubernetes": { + "locked": false, + "enabled": false, + "showSystemContainers": false, + "imagesRepository": "" + }, + "windowsContainers": { + "dockerDaemonOptions": { + "locked": false, + "value":"{\"debug\": false}" + } + }, + "disableUpdate": { + "locked": false, + "value": false + }, + "analyticsEnabled": { + "locked": false, + "value": true + }, + "extensionsEnabled": { + "locked": true, + "value": false + }, + "scout": { + "locked": false, + "sbomIndexing": true, + "useBackgroundIndexing": true + }, + "allowExperimentalFeatures": { + "locked": false, + "value": false + }, + "allowBetaFeatures": { + "locked": false, + "value": false + }, + "blockDockerLoad": { + "locked": false, + "value": true + }, + "filesharingAllowedDirectories": [ + { + "path": "$HOME", + "sharedByDefault": true + }, + { + "path":"$TMP", + "sharedByDefault": false + } + ], + "useVirtualizationFrameworkVirtioFS": { + "locked": true, + "value": true + }, + "useVirtualizationFrameworkRosetta": { + "locked": true, + "value": true + }, + "useGrpcfuse": { + "locked": true, + "value": true + }, + "displayedOnboarding": { + "locked": true, + "value": true + }, + "desktopTerminalEnabled": { + "locked": false, + "value": false + } +} +``` + +### General + +|Parameter|OS|Description|Version| +|:-------------------------------|---|:-------------------------------|---| +|`configurationFileVersion`| |Specifies the version of the configuration file format.| | +|`analyticsEnabled`| |If `value` is set to false, Docker Desktop doesn't send usage statistics to Docker. | | +|`disableUpdate`| |If `value` is set to true, checking for and notifications about Docker Desktop updates is disabled.| | +|`extensionsEnabled`| |If `value` is set to false, Docker extensions are disabled. | | +| `blockDockerLoad` | | If `value` is set to `true`, users are no longer able to run [`docker load`](/reference/cli/docker/image/load/) and receive an error if they try to.| | +| `displayedOnboarding` | | If `value` is set to `true`, the onboarding survey will not be displayed to new users. Setting `value` to `false` has no effect. | Docker Desktop version 4.30 and later | +| `desktopTerminalEnabled` | | If `value` is set to `false`, developers cannot use the Docker terminal to interact with the host machine and execute commands directly from Docker Desktop. | | +|`exposeDockerAPIOnTCP2375`| Windows only| Exposes the Docker API on a specified port. If `value` is set to true, the Docker API is exposed on port 2375. Note: This is unauthenticated and should only be enabled if protected by suitable firewall rules.| | + +### File sharing and emulation + +|Parameter|OS|Description|Version| +|:-------------------------------|---|:-------------------------------|---| +| `filesharingAllowedDirectories` | | Specify which paths your developers can add file shares to. Also accepts `$HOME`, `$TMP`, or `$TEMP` as `path` variables. When a path is added, its subdirectories are allowed. If `sharedByDefault` is set to `true`, that path will be added upon factory reset or when Docker Desktop first starts. | | +| `useVirtualizationFrameworkVirtioFS`| macOS only | If `value` is set to `true`, VirtioFS is set as the file sharing mechanism. Note: If both `useVirtualizationFrameworkVirtioFS` and `useGrpcfuse` have `value` set to `true`, VirtioFS takes precedence. Likewise, if both `useVirtualizationFrameworkVirtioFS` and `useGrpcfuse` have `value` set to `false`, osxfs is set as the file sharing mechanism. | | +| `useGrpcfuse` | macOS only | If `value` is set to `true`, gRPC Fuse is set as the file sharing mechanism. | | +| `useVirtualizationFrameworkRosetta`| macOS only | If `value` is set to `true`, Docker Desktop turns on Rosetta to accelerate x86_64/amd64 binary emulation on Apple Silicon. Note: This also automatically enables `Use Virtualization framework`. | Docker Desktop version 4.29 and later. | + +### Docker Scout + +|Parameter|OS|Description|Version| +|:-------------------------------|---|:-------------------------------|---| +|`scout`| | Setting `useBackgroundIndexing` to `false` disables automatic indexing of images loaded to the image store. Setting `sbomIndexing` to `false` prevents users from being able to index image by inspecting them in Docker Desktop or using `docker scout` CLI commands. | | + +### Proxy + +|Parameter|OS|Description|Version| +|:-------------------------------|---|:-------------------------------|---| +|`proxy`| |If `mode` is set to `system` instead of `manual`, Docker Desktop gets the proxy values from the system and ignores and values set for `http`, `https` and `exclude`. Change `mode` to `manual` to manually configure proxy servers. If the proxy port is custom, specify it in the `http` or `https` property, for example `"https": "http://myotherproxy.com:4321"`. The `exclude` property specifies a comma-separated list of hosts and domains to bypass the proxy. | | +|       `windowsDockerdPort`| Windows only | Exposes Docker Desktop's internal proxy locally on this port for the Windows Docker daemon to connect to. If it is set to 0, a random free port is chosen. If the value is greater than 0, use that exact value for the port. The default value is -1 which disables the option. | | +|       `enableKerberosNtlm`| |When set to `true`, Kerberos and NTLM authentication is enabled. Default is `false`. For more information, see the settings documentation. | Docker Desktop version 4.32 and later. | + +### Container proxy + +|Parameter|OS|Description|Version| +|:-------------------------------|---|:-------------------------------|---| +|`containersProxy` | | Creates air-gapped containers. For more information see [Air-Gapped Containers](../air-gapped-containers.md).| Docker Desktop version 4.29 and later. | + +### Linux VM + +|Parameter|OS|Description|Version| +|:-------------------------------|---|:-------------------------------|---| +| `linuxVM` | |Parameters and settings related to Linux VM options - grouped together here for convenience. | | +|        `wslEngineEnabled` | Windows only | If `value` is set to true, Docker Desktop uses the WSL 2 based engine. This overrides anything that may have been set at installation using the `--backend=` flag. | | +|        `dockerDaemonOptions` | |If `value` is set to true, it overrides the options in the Docker Engine config file. See the [Docker Engine reference](/reference/cli/dockerd/#daemon-configuration-file). Note that for added security, a few of the config attributes may be overridden when Enhanced Container Isolation is enabled. | | +|        `vpnkitCIDR` | |Overrides the network range used for vpnkit DHCP/DNS for `*.docker.internal` | | + +### Windows containers + +|Parameter|OS|Description|Version| +|:-------------------------------|---|:-------------------------------|---| +| `windowsContainers` | | Parameters and settings related to `windowsContainers` options - grouped together here for convenience. | | +|        `dockerDaemonOptions` | | Overrides the options in the Linux daemon config file. See the [Docker Engine reference](/reference/cli/dockerd/#daemon-configuration-file).| | + +> [!NOTE] +> +> This setting is not available to configure via the Docker Admin Console. + +### Kubernetes + +|Parameter|OS|Description|Version| +|:-------------------------------|---|:-------------------------------|---| +|`kubernetes`| | If `enabled` is set to true, a Kubernetes single-node cluster is started when Docker Desktop starts. If `showSystemContainers` is set to true, Kubernetes containers are displayed in the Docker Desktop Dashboard and when you run `docker ps`. `imagesRepository` lets you specify which repository Docker Desktop pulls the Kubernetes images from. For example, `"imagesRepository": "registry-1.docker.io/docker"`. | | + +### Features in development + +|Parameter|OS|Description|Version| +|:-------------------------------|---|:-------------------------------|---| +| `allowExperimentalFeatures`| | If `value` is set to `false`, experimental features are disabled.| | +| `allowBetaFeatures`| | If `value` is set to `false`, beta features are disabled.| | +| `enableDockerAI` | | If `value` is set to `false`, Docker AI (Ask Gordon) features are disabled. | | + +### Enhanced Container Isolation + +|Parameter|OS|Description|Version| +|:-------------------------------|---|:-------------------------------|---| +|`enhancedContainerIsolation`| | If `value` is set to true, Docker Desktop runs all containers as unprivileged, via the Linux user-namespace, prevents them from modifying sensitive configurations inside the Docker Desktop VM, and uses other advanced techniques to isolate them. For more information, see [Enhanced Container Isolation](../enhanced-container-isolation/_index.md).| | +|        `dockerSocketMount` | | By default, enhanced container isolation blocks bind-mounting the Docker Engine socket into containers (e.g., `docker run -v /var/run/docker.sock:/var/run/docker.sock ...`). This lets you relax this in a controlled way. See [ECI Configuration](../enhanced-container-isolation/config.md) for more info. | | +|               `imageList` | | Indicates which container images are allowed to bind-mount the Docker Engine socket. | | +|               `commandList` | | Restricts the commands that containers can issue via the bind-mounted Docker Engine socket. | | + +## Step three: Re-launch Docker Desktop + +> [!NOTE] +> +> Test the changes made through the `admin-settings.json` file locally to see if the settings work as expected. + +For settings to take effect: +- On a new install, developers need to launch Docker Desktop and authenticate to their organization. +- On an existing install, developers need to quit Docker Desktop through the Docker menu, and then re-launch Docker Desktop. If they are already signed in, they don't need to sign in again for the changes to take effect. + > [!IMPORTANT] + > + > Selecting **Restart** from the Docker menu isn't enough as it only restarts some components of Docker Desktop. + +So as not to disrupt your developers' workflow, Docker doesn't automatically mandate that developers re-launch and re-authenticate once a change has been made. + +In Docker Desktop, developers see the relevant settings grayed out and the message **Locked by your administrator**. + +![Proxy settings grayed out with Settings Management](/assets/images/grayed-setting.png) diff --git a/content/manuals/security/for-admins/hardened-desktop/settings-management/configure.md b/content/manuals/security/for-admins/hardened-desktop/settings-management/configure.md deleted file mode 100644 index 01e34698c58..00000000000 --- a/content/manuals/security/for-admins/hardened-desktop/settings-management/configure.md +++ /dev/null @@ -1,246 +0,0 @@ ---- -description: How to configure Settings Management for Docker Desktop -keywords: admin, controls, rootless, enhanced container isolation -title: Configure Settings Management -linkTitle: Configure -aliases: - - /desktop/hardened-desktop/settings-management/configure/ ---- - ->**Note** -> ->Settings Management is available to Docker Business customers only. - -This page contains information for admins on how to configure Settings Management to specify and lock configuration parameters to create a standardized Docker Desktop environment across the organization. - -Settings Management is designed specifically for organizations who don’t give developers root access to their machines. - -### Prerequisites - -- [Download and install Docker Desktop 4.13.0 or later](/manuals/desktop/release-notes.md). -- As an administrator, you need to [enforce - sign-in](/manuals/security/for-admins/enforce-sign-in/_index.md). This is - because this feature requires a Docker Business subscription and therefore - your Docker Desktop users must authenticate to your organization for this - configuration to take effect. Enforcing sign-in ensures that your Docker - Desktop developers always authenticate to your organization, even though they - can authenticate without it and the feature will take effect. Enforcing - sign-in guarantees the feature always takes effect. - - -### Step one: Create the `admin-settings.json` file and save it in the correct location - -You can either use the `--admin-settings` installer flag on [macOS](/manuals/desktop/install/mac-install.md#install-from-the-command-line) or [Windows](/manuals/desktop/install/windows-install.md#install-from-the-command-line) to automatically create the `admin-settings.json` and save it in the correct location, or set it up manually. - -To set it up manually: -1. Create a new, empty JSON file and name it `admin-settings.json`. -2. Save the `admin-settings.json` file on your developers' machines in the following locations: - - - Mac: `/Library/Application\ Support/com.docker.docker/admin-settings.json` - - Windows: `C:\ProgramData\DockerDesktop\admin-settings.json` - - Linux: `/usr/share/docker-desktop/admin-settings.json` - - By placing this file in the above protected directories, end users are unable to modify it. - - > [!IMPORTANT] - > - > It is assumed that you have the ability to push the `admin-settings.json` settings file to the locations specified above through a device management software such as [Jamf](https://www.jamf.com/lp/en-gb/apple-mobile-device-management-mdm-jamf-shared/?attr=google_ads-brand-search-shared&gclid=CjwKCAjw1ICZBhAzEiwAFfvFhEXjayUAi8FHHv1JJitFPb47C_q_RCySTmF86twF1qJc_6GST-YDmhoCuJsQAvD_BwE). - -### Step two: Configure the settings you want to lock in - ->**Note** -> ->Some of the configuration parameters only apply to Windows. This is highlighted in the table below. - -The `admin-settings.json` file requires a nested list of configuration parameters, each of which must contain the `locked` parameter. You can add or remove configuration parameters as per your requirements. - -If `locked: true`, users aren't able to edit this setting from Docker Desktop or the CLI. - -If `locked: false`, it's similar to setting a factory default in that: -- For new installs, `locked: false` pre-populates the relevant settings in the Docker Desktop UI, but users are able to modify it. - -- If Docker Desktop is already installed and being used, `locked: false` is ignored. This is because existing users of Docker Desktop may have already updated a setting, which in turn will have been written to the relevant config file, for example the `settings-store.json` (or `settings.json` for Docker Desktop versions 4.34 and earlier) or `daemon.json`. In these instances, the user's preferences are respected and we don't alter these values. These can be controlled by the admin by setting `locked: true`. - -The following `admin-settings.json` code and table provides an example of the required syntax and descriptions for parameters and values: - -```json -{ - "configurationFileVersion": 2, - "exposeDockerAPIOnTCP2375": { - "locked": true, - "value": false - }, - "proxy": { - "locked": true, - "mode": "system", - "http": "", - "https": "", - "exclude": [], - "windowsDockerdPort": 65000, - "enableKerberosNtlm": false - }, - "containersProxy": { - "locked": true, - "mode": "manual", - "http": "", - "https": "", - "exclude": [], - "pac":"", - "transparentPorts": "" - }, - "enhancedContainerIsolation": { - "locked": true, - "value": true, - "dockerSocketMount": { - "imageList": { - "images": [ - "docker.io/localstack/localstack:*", - "docker.io/testcontainers/ryuk:*" - ] - }, - "commandList": { - "type": "deny", - "commands": ["push"] - } - } - }, - "linuxVM": { - "wslEngineEnabled": { - "locked": false, - "value": false - }, - "dockerDaemonOptions": { - "locked": false, - "value":"{\"debug\": false}" - }, - "vpnkitCIDR": { - "locked": false, - "value":"192.168.65.0/24" - } - }, - "kubernetes": { - "locked": false, - "enabled": false, - "showSystemContainers": false, - "imagesRepository": "" - }, - "windowsContainers": { - "dockerDaemonOptions": { - "locked": false, - "value":"{\"debug\": false}" - } - }, - "disableUpdate": { - "locked": false, - "value": false - }, - "analyticsEnabled": { - "locked": false, - "value": true - }, - "extensionsEnabled": { - "locked": true, - "value": false - }, - "scout": { - "locked": false, - "sbomIndexing": true, - "useBackgroundIndexing": true - }, - "allowExperimentalFeatures": { - "locked": false, - "value": false - }, - "allowBetaFeatures": { - "locked": false, - "value": false - }, - "blockDockerLoad": { - "locked": false, - "value": true - }, - "filesharingAllowedDirectories": [ - { - "path": "$HOME", - "sharedByDefault": true - }, - { - "path":"$TMP", - "sharedByDefault": false - } - ], - "useVirtualizationFrameworkVirtioFS": { - "locked": true, - "value": true - }, - "useVirtualizationFrameworkRosetta": { - "locked": true, - "value": true - }, - "useGrpcfuse": { - "locked": true, - "value": true - }, - "displayedOnboarding": { - "locked": true, - "value": true - }, - "desktopTerminalEnabled": { - "locked": false, - "value": false - } -} -``` - -| Parameter | | Description | -| :------------------------------- |---| :------------------------------- | -| `configurationFileVersion` | |Specifies the version of the configuration file format. | -| `exposeDockerAPIOnTCP2375` | Windows only| Exposes the Docker API on a specified port. If `value` is set to true, the Docker API is exposed on port 2375. Note: This is unauthenticated and should only be enabled if protected by suitable firewall rules.| -| `proxy` | |If `mode` is set to `system` instead of `manual`, Docker Desktop gets the proxy values from the system and ignores and values set for `http`, `https` and `exclude`. Change `mode` to `manual` to manually configure proxy servers. If the proxy port is custom, specify it in the `http` or `https` property, for example `"https": "http://myotherproxy.com:4321"`. The `exclude` property specifies a comma-separated list of hosts and domains to bypass the proxy. | -|        `windowsDockerdPort` | Windows only | Exposes Docker Desktop's internal proxy locally on this port for the Windows Docker daemon to connect to. If it is set to 0, a random free port is chosen. If the value is greater than 0, use that exact value for the port. The default value is -1 which disables the option. Note: This is available for Windows containers only. | -|        `enableKerberosNtlm` | |When set to `true`, Kerberos and NTLM authentication is enabled. Default is `false`. Available in Docker Desktop version 4.32 and later. For more information, see the settings documentation. | -| `containersProxy` (Beta) | | Allows you to create air-gapped containers. For more information see [Air-Gapped Containers](../air-gapped-containers.md).| -| `enhancedContainerIsolation` | | If `value` is set to true, Docker Desktop runs all containers as unprivileged, via the Linux user-namespace, prevents them from modifying sensitive configurations inside the Docker Desktop VM, and uses other advanced techniques to isolate them. For more information, see [Enhanced Container Isolation](../enhanced-container-isolation/_index.md).| -|        `dockerSocketMount` | | By default, enhanced container isolation blocks bind-mounting the Docker Engine socket into containers (e.g., `docker run -v /var/run/docker.sock:/var/run/docker.sock ...`). This allows admins to relax this in a controlled way. See [ECI Configuration](../enhanced-container-isolation/config.md) for more info. | -|               `imageList` | | Indicates which container images are allowed to bind-mount the Docker Engine socket. | -|               `commandList` | | Restricts the commands that containers can issue via the bind-mounted Docker Engine socket. | -| `linuxVM` | |Parameters and settings related to Linux VM options - grouped together here for convenience. | -|        `wslEngineEnabled` | Windows only | If `value` is set to true, Docker Desktop uses the WSL 2 based engine. This overrides anything that may have been set at installation using the `--backend=` flag. | -|       `dockerDaemonOptions`| |If `value` is set to true, it overrides the options in the Docker Engine config file. See the [Docker Engine reference](/reference/cli/dockerd/#daemon-configuration-file). Note that for added security, a few of the config attributes may be overridden when Enhanced Container Isolation is enabled. | -|       `vpnkitCIDR` | |Overrides the network range used for vpnkit DHCP/DNS for `*.docker.internal` | -|`kubernetes`| | If `enabled` is set to true, a Kubernetes single-node cluster is started when Docker Desktop starts. If `showSystemContainers` is set to true, Kubernetes containers are displayed in the UI and when you run `docker ps`. `imagesRepository` allows you to specify which repository Docker Desktop pulls the Kubernetes images from. For example, `"imagesRepository": "registry-1.docker.io/docker"`. | -| `windowsContainers` | | Parameters and settings related to `windowsContainers` options - grouped together here for convenience. | -|        `dockerDaemonOptions` | | Overrides the options in the Linux daemon config file. See the [Docker Engine reference](/reference/cli/dockerd/#daemon-configuration-file).| -|`disableUpdate`| |If `value` is set to true, checking for and notifications about Docker Desktop updates is disabled.| -|`analyticsEnabled`| |If `value` is set to false, Docker Desktop doesn't send usage statistics to Docker. | -|`extensionsEnabled`| |If `value` is set to false, Docker extensions are disabled. | -|`scout`|| Setting `useBackgroundIndexing` to `false` disables automatic indexing of images loaded to the image store. Setting `sbomIndexing` to `false` prevents users from being able to index image by inspecting them in Docker Desktop or using `docker scout` CLI commands. | -| `allowExperimentalFeatures`| | If `value` is set to `false`, experimental features are disabled.| -| `allowBetaFeatures`| | If `value` is set to `false`, beta features are disabled.| -| `blockDockerLoad` | | If `value` is set to `true`, users are no longer able to run [`docker load`](/reference/cli/docker/image/load/) and receive an error if they try to.| -| `filesharingAllowedDirectories` | | Specify which paths your developers can add file shares to. Also accepts `$HOME`, `$TMP`, or `$TEMP` as `path` variables. When a path is added, its subdirectories are allowed. If `sharedByDefault` is set to `true`, that path will be added upon factory reset or when Docker Desktop first starts. | -| `useVirtualizationFrameworkVirtioFS`| macOS only | If `value` is set to `true`, VirtioFS is set as the file sharing mechanism. Note: If both `useVirtualizationFrameworkVirtioFS` and `useGrpcfuse` have `value` set to `true`, VirtioFS takes precedence. Likewise, if both `useVirtualizationFrameworkVirtioFS` and `useGrpcfuse` have `value` set to `false`, osxfs is set as the file sharing mechanism. | -| `useVirtualizationFrameworkRosetta`| macOS only | If `value` is set to `true`, Docker Desktop turns on Rosetta to accelerate x86_64/amd64 binary emulation on Apple Silicon. Note: This also automatically enables `Use Virtualization framework`. | -| `useGrpcfuse` | macOS only | If `value` is set to `true`, gRPC Fuse is set as the file sharing mechanism. | -| `displayedOnboarding` | | If `value` is set to `true`, the onboarding survey will not be displayed to new users. Setting `value` to `false` has no effect. | -| `desktopTerminalEnabled` | | If `value` is set to `false`, developers cannot use the Docker terminal to interact with the host machine and execute commands directly from Docker Desktop. | - -### Step three: Re-launch Docker Desktop - ->**Note** -> ->Administrators should test the changes made through the `admin-settings.json` file locally to see if the settings work as expected. - -For settings to take effect: -- On a new install, developers need to launch Docker Desktop and authenticate to their organization. -- On an existing install, developers need to quit Docker Desktop through the Docker menu, and then relaunch Docker Desktop. If they are already signed in, they don't need to sign in again for the changes to take effect. - >**Important** - > - >Selecting **Restart** from the Docker menu isn't enough as it only restarts some components of Docker Desktop. - -Docker doesn't automatically mandate that developers re-launch and sign in once a change has been made so as not to disrupt your developers' workflow. - - -In Docker Desktop, developers see the relevant settings grayed out and the message **Locked by your administrator**. - -![Proxy settings grayed out with Settings Management](/assets/images/grayed-setting.png) diff --git a/content/manuals/security/for-admins/provisioning/just-in-time.md b/content/manuals/security/for-admins/provisioning/just-in-time.md index d412f8b6b7e..dc006697753 100644 --- a/content/manuals/security/for-admins/provisioning/just-in-time.md +++ b/content/manuals/security/for-admins/provisioning/just-in-time.md @@ -63,7 +63,7 @@ You may want to disable JIT provisioning for reasons such as the following: Users are provisioned with JIT by default. If you enable SCIM, you can disable JIT: -1. Sign in to the [Admin Console](https://app.docker.com/). -2. Select your organization or company in the left-hand navigation drop-down, and then select **SSO and SCIM**. +1. In the [Admin Console](https://app.docker.com/admin), select your organization. +2. Select **SSO and SCIM**. 3. In the SSO connections table, select the **Action** icon and then **Disable JIT provisioning**. 4. Select **Disable** to confirm. diff --git a/content/manuals/security/for-admins/provisioning/scim.md b/content/manuals/security/for-admins/provisioning/scim.md index a56ea77572c..c7500ec5c8d 100644 --- a/content/manuals/security/for-admins/provisioning/scim.md +++ b/content/manuals/security/for-admins/provisioning/scim.md @@ -5,6 +5,7 @@ linkTitle: SCIM description: Learn how System for Cross-domain Identity Management works and how to set it up. aliases: - /security/for-admins/scim/ + - /docker-hub/scim/ weight: 30 --- diff --git a/content/manuals/security/for-admins/roles-and-permissions.md b/content/manuals/security/for-admins/roles-and-permissions.md index 517088b771e..5165ee39d2b 100644 --- a/content/manuals/security/for-admins/roles-and-permissions.md +++ b/content/manuals/security/for-admins/roles-and-permissions.md @@ -9,30 +9,35 @@ aliases: weight: 40 --- -Organization and company owners can assign roles to individuals giving them different permissions in the organization. This section is for owners who want to learn about the defined roles and their permission scopes. +Organization and company owners can assign roles to individuals giving them different permissions in the organization. This guide outlines Docker's organization roles and their permission scopes. ## Roles -When you invite users to your organization, you assign a role. A role is a collection of permissions. Roles define access to perform actions like creating repositories, pulling images, creating teams, and configuring organization settings. +When you invite users to your organization, you assign them a role. A role is a collection of permissions. Roles define whether users can create repositories, pull images, create teams, and configure organization settings. The following roles are available to assign: -- **Member** - Non-administrative role. Members can view other members that are in the same organization. -- **Editor** - Partial administrative access to the organization. Editors can create, edit, and delete repositories. They can also edit an existing team's access permissions. -- **Organization owner** - Full organization administrative access. Organization owners can manage organization repositories, teams, members, settings, and billing. -- **Company owner** - In addition to the permissions of an organization owner, company owners can configure settings for their associated organizations. +- Member: Non-administrative role. Members can view other members that are in the same organization. +- Editor: Partial administrative access to the organization. Editors can create, edit, and delete repositories. They can also edit an existing team's access permissions. +- Organization owner: Full organization administrative access. Organization owners can manage organization repositories, teams, members, settings, and billing. +- Company owner: In addition to the permissions of an organization owner, company owners can configure settings for their associated organizations. -Owners can manage roles for members of an organization on [Docker Hub](/manuals/admin/organization/members.md#update-a-member-role), as well members of an [organization](/manuals/admin/organization/members.md#update-a-member-role) or a [company](/manuals/admin/company/users.md#update-a-member-role) in the [Docker Admin Console](/manuals/admin/_index.md). +Owners can manage roles for members of an organization using Docker Hub or the Admin Console: +- Update a member role in [Docker Hub](/manuals/admin/organization/members.md#update-a-member-role) +- Update an organization's members or company in the [Admin Console](/manuals/admin/company/users.md#update-a-member-role) +- Learn more about [organizations and companies](/manuals/admin/_index.md) ## Permissions +> [!NOTE] +> +> Company owners have the same access as organization owners for all associated organizations. For more information, see [Company overview](/admin/company/). + The following sections describe the permissions for each role. ### Content and registry permissions -The following outlines content and registry permissions for member, editor, and organization owner roles. These permissions and roles apply to the entire organization, including all the repositories in the namespace for the organization. - -Company owners have the same access as organization owners for all associated organizations. See [Company overview](/admin/company/). +The following table outlines content and registry permissions for member, editor, and organization owner roles. These permissions and roles apply to the entire organization, including all the repositories in the namespace for the organization. | Permission | Member | Editor | Organization owner | | :---------------------------------------------------- | :----- | :----- | :----------------- | @@ -53,13 +58,13 @@ Company owners have the same access as organization owners for all associated or When you add members to a team, you can manage their repository permissions. For team repository permissions, see [Create and manage a team permissions reference](/manuals/admin/organization/manage-a-team.md#permissions-reference). -See the following diagram for an example of how permissions may work for a user. In this example, the first permission check is for the role: member or editor. Editors have administrative permissions for repositories across the namespace of the organization. Members may have administrative permissions for a repository if they're a member of a team that grants those permissions. +The following diagram provides an example of how permissions may work for a user. In this example, the first permission check is for the role: member or editor. Editors have administrative permissions for repositories across the namespace of the organization. Members may have administrative permissions for a repository if they're a member of a team that grants those permissions. ![User repository permissions within an organization](../images/roles-and-permissions-member-editor-roles.png) ### Organization management permissions -The following outlines organization management permissions for member, editor, organization owner, and company owner roles. +The following table outlines organization management permissions for member, editor, organization owner, and company owner roles. | Permission | Member | Editor | Organization owner | Company owner | | :---------------------------------------------------------------- | :----- | :----- | :----------------- | :------------ | @@ -76,8 +81,8 @@ The following outlines organization management permissions for member, editor, o | Registry Access Management | ❌ | ❌ | ✅ | ✅ | | Set up Single Sign-On (SSO) and SCIM | ❌ | ❌ | ✅ \* | ✅ | | Require Docker Desktop sign-in | ❌ | ❌ | ✅ \* | ✅ | -| Manage billing information (e.g. billing address) | ❌ | ❌ | ✅ | ✅ | -| Manage payment methods (e.g. credit card or invoice) | ❌ | ❌ | ✅ | ✅ | +| Manage billing information (for example, billing address) | ❌ | ❌ | ✅ | ✅ | +| Manage payment methods (for example, credit card or invoice) | ❌ | ❌ | ✅ | ✅ | | View billing history | ❌ | ❌ | ✅ | ✅ | | Manage subscriptions | ❌ | ❌ | ✅ | ✅ | | Manage seats | ❌ | ❌ | ✅ | ✅ | @@ -85,9 +90,9 @@ The following outlines organization management permissions for member, editor, o _\* If not part of a company_ -### Docker Scout +### Docker Scout permissions -The following outlines Docker Scout management permissions for member, editor, and organization owner roles. +The following table outlines Docker Scout management permissions for member, editor, and organization owner roles. | Permission | Member | Editor | Organization owner | | :---------------------------------------------------- | :----- | :----- | :----------------- | @@ -97,9 +102,9 @@ The following outlines Docker Scout management permissions for member, editor, a | Create environments | ❌ | ❌ | ✅ | | Manage registry integrations | ❌ | ❌ | ✅ | -### Docker Build Cloud +### Docker Build Cloud permissions -The following outlines Docker Build Cloud management permissions for member, editor, and organization owner roles. +The following table outlines Docker Build Cloud management permissions for member, editor, and organization owner roles. | Permission | Member | Editor | Organization owner | | ---------------------------- | :----- | :----- | :----------------- | diff --git a/content/manuals/security/for-admins/single-sign-on/_index.md b/content/manuals/security/for-admins/single-sign-on/_index.md index 51de20f7f2e..7df4a430d33 100644 --- a/content/manuals/security/for-admins/single-sign-on/_index.md +++ b/content/manuals/security/for-admins/single-sign-on/_index.md @@ -14,7 +14,7 @@ Single sign-on (SSO) lets users access Docker by authenticating using their iden ## How SSO works -When you enable SSO, Docker supports a IdP-initiated SSO flow for user login. Instead of users authenticating using their Docker username and password, they are redirected to your identity provider's authentication page to sign in. Users must sign in to Docker Hub or Docker Desktop to initiate the SSO authentication process. +When you enable SSO, Docker supports a non-IdP-initiated SSO flow for user login. Instead of users authenticating using their Docker username and password, they are redirected to your identity provider's authentication page to sign in. Users must sign in to Docker Hub or Docker Desktop to initiate the SSO authentication process. The following diagram shows how SSO operates and is managed in Docker Hub and Docker Desktop. In addition, it provides information on how to authenticate between your IdP. @@ -38,7 +38,7 @@ Once your SSO configuration is complete, a first-time user can sign in to Docker Before configuring SSO, ensure you meet the following prerequisites: * Notify your company about the new SSO sign in procedures. * Verify that all users have Docker Desktop version 4.4.2 or later installed. -* If your organization is planning to [enforce SSO](../enforce-sign-in/_index.md), members using the Docker CLI are required to [create a Personal Access Token (PAT)](/docker-hub/access-tokens/). The PAT will be used instead of their username and password. Docker plans to deprecate signing in to the CLI with a password in the future, so using a PAT will be required to prevent issues with authentication. For more details see the [security announcement](/security/security-announcements/#deprecation-of-password-logins-on-cli-when-sso-enforced). +* If your organization is planning to [enforce SSO](/manuals/security/for-admins/single-sign-on/connect.md#optional-enforce-sso), members using the Docker CLI are required to [create a Personal Access Token (PAT)](/docker-hub/access-tokens/). The PAT will be used instead of their username and password. Docker plans to deprecate signing in to the CLI with a password in the future, so using a PAT will be required to prevent issues with authentication. For more details see the [security announcement](/security/security-announcements/#deprecation-of-password-logins-on-cli-when-sso-enforced). * Ensure all your Docker users have a valid user on your IdP with the same email address as their Unique Primary Identifier (UPN). * Confirm that all CI/CD pipelines have replaced their passwords with PATs. * For your service accounts, add your additional domains or enable it in your IdP. diff --git a/content/manuals/security/for-admins/single-sign-on/configure.md b/content/manuals/security/for-admins/single-sign-on/configure.md index a5bda5c29b5..ee2905fbc06 100644 --- a/content/manuals/security/for-admins/single-sign-on/configure.md +++ b/content/manuals/security/for-admins/single-sign-on/configure.md @@ -22,7 +22,7 @@ Get started creating a single sign-on (SSO) connection for your organization or {{< include "admin-early-access.md" >}} 1. Sign in to the [Admin Console](https://admin.docker.com/). -2. Select your organization or company from the left-hand drop-down menu. Note that when an organization is part of a company, you must select the company and configure the domain for the organization at the company level. +2. Select your organization or company from the **Choose profile** page. Note that when an organization is part of a company, you must select the company and configure the domain for the organization at the company level. 3. Under **Security and access**, select **Domain management**. 4. Select **Add a domain**. 5. Enter your domain in the text box and select **Add domain**. diff --git a/content/manuals/security/for-admins/single-sign-on/connect.md b/content/manuals/security/for-admins/single-sign-on/connect.md index 1c95c487975..0a698b9653a 100644 --- a/content/manuals/security/for-admins/single-sign-on/connect.md +++ b/content/manuals/security/for-admins/single-sign-on/connect.md @@ -31,7 +31,7 @@ Make sure you have completed the following before you begin: {{< include "admin-early-access.md" >}} 1. Sign in to the [Admin Console](https://admin.docker.com/). -2. Select your organization or company from the left-hand drop-down menu. Note that when an organization is part of a company, you must select the company and configure the domain for the organization at the company level. +2. Select your organization or company from the **Choose profile** page. Note that when an organization is part of a company, you must select the company and configure the domain for the organization at the company level. 3. Under Security and access, select **SSO and SCIM**. 4. Select **Create Connection** and provide a name for the connection. 5. Select an authentication method, **SAML** or **Azure AD (OIDC)**. @@ -201,7 +201,7 @@ You can also test your SSO connection through the command-line interface (CLI). Enforcing SSO requires users to use SSO when signing into Docker. This centralizes authentication and enforces policies set by the IdP. 1. Sign in to the [Admin Console](https://admin.docker.com/). -2. Select your organization or company from the left-hand drop-down menu. Note that when an organization is part of a company, you must select the company and configure the domain for the organization at the company level. +2. Select your organization or company from the **Choose profile** page. Note that when an organization is part of a company, you must select the company and configure the domain for the organization at the company level. 3. Under Security and access, select **SSO and SCIM**. 4. In the SSO connections table, select the **Action** icon and then **Enable enforcement**. When SSO is enforced, your users are unable to modify their email address and password, convert a user account to an organization, or set up 2FA through Docker Hub. If you want to use 2FA, you must enable 2FA through your IdP. 5. Continue with the on-screen instructions and verify you've completed all tasks. diff --git a/content/manuals/security/for-admins/single-sign-on/manage.md b/content/manuals/security/for-admins/single-sign-on/manage.md index ddc54606846..70b4af79abe 100644 --- a/content/manuals/security/for-admins/single-sign-on/manage.md +++ b/content/manuals/security/for-admins/single-sign-on/manage.md @@ -54,24 +54,39 @@ aliases: ## Manage users -{{< tabs >}} -{{< tab name="Admin Console" >}} +> [!IMPORTANT] +> +> SSO has Just-In-Time (JIT) Provisioning enabled by default unless you have [disabled it](/security/for-admins/provisioning/just-in-time/#sso-authentication-with-jit-provisioning-disabled). This means your users are auto-provisioned to your organization. +> +> You can change this on a per-app basis. To prevent auto-provisioning users, you can create a security group in your IdP and configure the SSO app to authenticate and authorize only those users that are in the security group. Follow the instructions provided by your IdP: +> +> - [Okta](https://help.okta.com/en-us/Content/Topics/Security/policies/configure-app-signon-policies.htm) +> - [Entra ID (formerly Azure AD)](https://learn.microsoft.com/en-us/azure/active-directory/develop/howto-restrict-your-app-to-a-set-of-users) +> +> Alternatively, see the [Provisioning overview](/manuals/security/for-admins/provisioning/_index.md) guide. -{{< include "admin-early-access.md" >}} -{{% admin-sso-management-users product="admin" %}} +### Add guest users when SSO is enabled -{{< /tab >}} -{{< tab name="Docker Hub" >}} +To add a guest that isn't verified through your IdP: -{{% admin-sso-management-users product="hub" %}} +1. Sign in to the [Admin Console](https://app.docker.com/admin). +2. Select your organization or company from the **Choose profile** page, then select **Members**. +3. Select **Invite**. +4. Follow the on-screen instructions to invite the user. -{{< /tab >}} -{{< /tabs >}} +### Remove users from the SSO company + +To remove a user: + +1. Sign in to [Admin Console](https://app.docker.com/admin). +2. Select your organization or company from the **Choose profile** page, then select **Members**. +3. Select the action icon next to a user’s name, and then select **Remove member**, if you're an organization, or **Remove user**, if you're a company. +4. Follow the on-screen instructions to remove the user. ## Manage provisioning -Users are provisioned with Just-in-Time (JIT) provisioning by default. If you enable SCIM, you can disable JIT. For more information, see the [Provisioning overview](/manuals/security/for-admins/provisioning/_index.md) [Just-in-Time](/manuals/security/for-admins/provisioning/just-in-time.md) guides. +Users are provisioned with Just-in-Time (JIT) provisioning by default. If you enable SCIM, you can disable JIT. For more information, see the [Provisioning overview](/manuals/security/for-admins/provisioning/_index.md) guide. ## What's next? diff --git a/content/manuals/security/for-admins/single-sign-on/troubleshoot.md b/content/manuals/security/for-admins/single-sign-on/troubleshoot.md index 630da9fe3d3..e5585e36a8a 100644 --- a/content/manuals/security/for-admins/single-sign-on/troubleshoot.md +++ b/content/manuals/security/for-admins/single-sign-on/troubleshoot.md @@ -16,8 +16,7 @@ their service. ## View SSO and SCIM error logs 1. Sign in to the [Admin Console](https://app.docker.com/admin/). -2. Select your organization or company in the left navigation drop-down menu, - and then select **SSO and SCIM**. +2. Select your organization or company from the **Choose profile** page, and then select **SSO and SCIM**. > [!NOTE] > @@ -73,8 +72,7 @@ seats for the user. Possible solutions: * Add more Docker Business subscription seats to the organization. For details, - see [Add seats to your - subscription](/subscription/core-subscription/add-seats/). + see [Add seats to your subscription](../../../subscription/manage-seats.md). * Remove some users or pending invitations from your organization to make more seats available. For more details, see [Manage organization members](/admin/organization/members/). diff --git a/content/manuals/security/for-developers/2fa/_index.md b/content/manuals/security/for-developers/2fa/_index.md index d38a2894fa5..70c17401f3b 100644 --- a/content/manuals/security/for-developers/2fa/_index.md +++ b/content/manuals/security/for-developers/2fa/_index.md @@ -17,7 +17,6 @@ code. Each recovery code is unique and specific to your account. You can use this code to recover your account in case you lose access to your authenticator app. See [Recover your Docker account](recover-hub-account/). - ## Prerequisites You need a mobile phone with a time-based one-time password (TOTP) authenticator @@ -27,11 +26,11 @@ Authenticator with a registered YubiKey. ## Enable two-factor authentication 1. Sign in to your [Docker account](https://app.docker.com/login). -2. Select your avatar and then from the drop-down menu, select **Account settings**. +2. Select your avatar and then from the drop-down menu, select **Account settings**. 3. Navigate to the **Security** section, then select **Two-factor authentication**. 4. Enter your account password, then select **Confirm**. 5. Save your recovery code and store it somewhere safe. You can use your recovery code to recover your account in the event you lose access to your authenticator app. -6. Use a TOTP mobile app to scan the QR code or enter the text code. +6. Use a Time-based One-time password (TOTP) mobile app to scan the QR code or enter the text code. 7. Once you've linked your authenticator app, enter the six-digit code in the text-field. 8. Select **Enable 2FA**. diff --git a/content/manuals/security/for-developers/2fa/disable-2fa.md b/content/manuals/security/for-developers/2fa/disable-2fa.md index 4ee56984341..a0fbb74027a 100644 --- a/content/manuals/security/for-developers/2fa/disable-2fa.md +++ b/content/manuals/security/for-developers/2fa/disable-2fa.md @@ -4,7 +4,7 @@ keywords: Docker, docker, registry, security, Docker Hub, authentication, two-fa authentication, account security, title: Disable two-factor authentication on your Docker account linkTitle: Disable two-factor authentication -aliases: +aliases: - /docker-hub/2fa/disable-2fa/ weight: 30 --- diff --git a/content/manuals/security/for-developers/2fa/new-recovery-code.md b/content/manuals/security/for-developers/2fa/new-recovery-code.md index 3f5b2b22efe..e608ff55147 100644 --- a/content/manuals/security/for-developers/2fa/new-recovery-code.md +++ b/content/manuals/security/for-developers/2fa/new-recovery-code.md @@ -18,4 +18,4 @@ access to your Docker Hub account, you can generate a new recovery code. 5. Select **Generate new code**. This generates a new code. Select the visibility icon to view the code. Remember to save your recovery code -and store it somewhere safe. +and store it somewhere safe. \ No newline at end of file diff --git a/content/manuals/security/for-developers/2fa/recover-hub-account.md b/content/manuals/security/for-developers/2fa/recover-hub-account.md index e331c6b744a..e8424ccd43a 100644 --- a/content/manuals/security/for-developers/2fa/recover-hub-account.md +++ b/content/manuals/security/for-developers/2fa/recover-hub-account.md @@ -12,5 +12,5 @@ If you have lost access to both your two-factor authentication application and y 1. Sign in to your [Docker account](https://app.docker.com/login) with your username and password. 2. Select **I've lost my authentication device** and **I've lost my recovery code**. -3. Complete the [Contact Support form](https://hub.docker.com/support/contact/?category=2fa-lockout). +3. Complete the [Contact Support form](https://hub.docker.com/support/contact/?category=2fa-lockout). You must enter the primary email address associated with your Docker ID in the **Contact Support** form for recovery instructions. diff --git a/content/manuals/security/for-developers/access-tokens.md b/content/manuals/security/for-developers/access-tokens.md index 7054d345f8f..bda7607ba60 100644 --- a/content/manuals/security/for-developers/access-tokens.md +++ b/content/manuals/security/for-developers/access-tokens.md @@ -4,7 +4,7 @@ linkTitle: Access tokens description: Learn how to create and manage your personal Docker access tokens to securely push and pull images programmatically. keywords: docker hub, hub, security, PAT, personal access token -aliases: +aliases: - /docker-hub/access-tokens/ --- @@ -13,9 +13,8 @@ You can create a personal access token (PAT) to use as an alternative to your pa Compared to passwords, PATs provide the following advantages: - You can investigate when the PAT was last used and then disable or delete it if you find any suspicious activity. -- When using an access token, you can't perform any admin activity on the account, including changing the password. It protects your account if your computer is compromised. - -Access tokens are also valuable for building integrations, as you can issue multiple tokens, one for each integration, and revoke them at +- When using an access token, you can't perform any administrative activity on the account, including changing the password. It protects your account if your computer is compromised. +- Access tokens are valuable for building integrations, as you can issue multiple tokens, one for each integration, and revoke them at any time. ## Create an access token @@ -24,6 +23,8 @@ any time. > > Treat access tokens like your password and keep them secret. Store your tokens securely in a credential manager for example. +Use the Docker Admin Console to create an access token. + 1. Sign in to your [Docker account](https://app.docker.com/login). 2. Select your avatar in the top-right corner and from the drop-down menu select **Account settings**. @@ -33,15 +34,16 @@ any time. 4. Select **Generate new token**. 5. Add a description for your token. Use something that indicates the use case or purpose of the token. - -6. Set the access permissions. + +6. Select the expiration date for the token. + +7. Set the access permissions. The access permissions are scopes that set restrictions in your repositories. For example, for Read & Write permissions, an automation pipeline can build an image and then push it to a repository. However, it can't delete the repository. -7. Select **Generate** and then copy the token that appears on the screen and save it. You won't be able - to retrieve the token once you close this prompt. +8. Select **Generate** and then copy the token that appears on the screen and save it. You won't be able to retrieve the token once you close this prompt. ## Use an access token @@ -61,8 +63,16 @@ When prompted for a password, enter your personal access token instead of a pass > use a personal access token when logging in from the Docker CLI. 2FA is an > optional, but more secure method of authentication. +### Fair use + +When utilizing PATs, users should be aware that excessive creation of PATs could lead to throttling, or additional charges. To ensure fair resource usage and maintain service quality, Docker reserves the right to impose restrictions or apply additional charges to accounts exhibiting excessive use of PATs. + ## Modify existing tokens +> [!NOTE] +> +> You can't edit the expiration date on an existing token. You must create a new PAT if you need to set a new expiration date. + You can rename, activate, deactivate, or delete a token as needed. You can manage your tokens in your account settings. 1. Sign in to your [Docker account](https://app.docker.com/login). @@ -81,4 +91,4 @@ You can rename, activate, deactivate, or delete a token as needed. You can manag When you sign in to your Docker account with Docker Desktop, Docker Desktop generates an authentication token on your behalf. When you interact with Docker Hub using the Docker CLI, the CLI uses this token for authentication. The token scope has Read, Write, and Delete access. If your Docker Desktop session expires, the token is automatically removed locally. -You can have up to 5 auto-generated tokens associated with your account. These are deleted and created automatically based on usage and creation dates. You can also delete your auto-generated tokens as needed. See [Modify existing tokens](#modify-existing-tokens). +You can have up to 5 auto-generated tokens associated with your account. These are deleted and created automatically based on usage and creation dates. You can also delete your auto-generated tokens as needed. For more information, see [Modify existing tokens](#modify-existing-tokens). diff --git a/content/manuals/security/security-announcements.md b/content/manuals/security/security-announcements.md index ddabcc75081..bc1bb163d82 100644 --- a/content/manuals/security/security-announcements.md +++ b/content/manuals/security/security-announcements.md @@ -59,7 +59,7 @@ If you are using affected versions of runc, BuildKit, Moby, or Docker Desktop, m If you are unable to update to an unaffected version promptly, follow these best practices to mitigate risk: -* Only use trusted Docker images (such as [Docker Official Images](../trusted-content/official-images/_index.md)). +* Only use trusted Docker images (such as [Docker Official Images](../docker-hub/image-library/trusted-content.md#docker-official-images)). * Don’t build Docker images from untrusted sources or untrusted Dockerfiles. * If you are a Docker Business customer using Docker Desktop and unable to update to v4.27.1, make sure to enable [Hardened Docker Desktop](/manuals/security/for-admins/hardened-desktop/_index.md) features such as: * [Enhanced Container Isolation](/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/_index.md), which mitigates the impact of CVE-2024-21626 in the case of running containers from malicious images. @@ -111,7 +111,7 @@ _The issue has been fixed in Moby >= v25.0.2 and >= v24.0.9._ Docker Desktop v4.27.0 and earlier are affected. Docker Desktop v4.27.1 was released on February 1 and includes runc, BuildKit, and dockerd binaries patches. In addition to updating to this new version, we encourage all Docker users to diligently use Docker images and Dockerfiles and ensure you only use trusted content in your builds. -As always, you should check Docker Desktop system requirements for your operating system ([Windows](/manuals/desktop/install/windows-install.md#system-requirements), [Linux](/manuals/desktop/install/linux/_index.md#general-system-requirements), [Mac](/manuals/desktop/install/mac-install.md#system-requirements)) before updating to ensure full compatibility. +As always, you should check Docker Desktop system requirements for your operating system ([Windows](/manuals/desktop/setup/install/windows-install.md#system-requirements), [Linux](/manuals/desktop/setup/install/linux/_index.md#general-system-requirements), [Mac](/manuals/desktop/setup/install/mac-install.md#system-requirements)) before updating to ensure full compatibility. #### Docker Build Cloud @@ -145,11 +145,11 @@ Docker Hub security scans triggered after 1200 UTC 21 October 2021 are now correctly identifying the Text4Shell CVE. Scans before this date do not currently reflect the status of this vulnerability. Therefore, we recommend that you trigger scans by pushing new images to Docker Hub to view the status of -the Text4Shell CVE in the vulnerability report. For detailed instructions, see [Scan images on Docker Hub](../docker-hub/vulnerability-scanning.md). +the Text4Shell CVE in the vulnerability report. For detailed instructions, see [Scan images on Docker Hub](../docker-hub/repos/manage/vulnerability-scanning.md). ### Docker Official Images impacted by CVE-2022-42889 -A number of [Docker Official Images](../trusted-content/official-images/_index.md) contain the vulnerable versions of +A number of [Docker Official Images](../docker-hub/image-library/trusted-content.md#docker-official-images) contain the vulnerable versions of Apache Commons Text. The following lists Docker Official Images that may contain the vulnerable versions of Apache Commons Text: @@ -195,13 +195,13 @@ Docker Hub security scans triggered after 1700 UTC 13 December 2021 are now correctly identifying the Log4j 2 CVEs. Scans before this date do not currently reflect the status of this vulnerability. Therefore, we recommend that you trigger scans by pushing new images to Docker Hub to view the status of -Log4j 2 CVE in the vulnerability report. For detailed instructions, see [Scan images on Docker Hub](../docker-hub/vulnerability-scanning.md). +Log4j 2 CVE in the vulnerability report. For detailed instructions, see [Scan images on Docker Hub](../docker-hub/repos/manage/vulnerability-scanning.md). ## Docker Official Images impacted by Log4j 2 CVE _Last updated December 2021_ -A number of [Docker Official Images](../trusted-content/official-images/_index.md) contain the vulnerable versions of +A number of [Docker Official Images](../docker-hub/image-library/trusted-content.md#docker-official-images) contain the vulnerable versions of Log4j 2 CVE-2021-44228. The following table lists Docker Official Images that may contained the vulnerable versions of Log4j 2. We updated Log4j 2 in these images to the latest version. Some of these images may not be vulnerable for other reasons. We recommend that you also review the guidelines published on the upstream websites. diff --git a/content/manuals/subscription/_index.md b/content/manuals/subscription/_index.md index 6a6d05718cb..b33d9766572 100644 --- a/content/manuals/subscription/_index.md +++ b/content/manuals/subscription/_index.md @@ -1,32 +1,31 @@ --- -title: Docker subscription overview -linkTitle: Subscription -weight: 200 +title: Subscription description: Learn about subscription features and how to manage your subscription keywords: Docker, pricing, billing, Pro, Team, business, subscription, tier, plan +params: + sidebar: + group: Platform grid_subscriptions: -- title: Docker Core subscriptions and features +- title: Docker subscriptions and features description: Explore what you can do with your Docker subscription. link: /subscription/details/ icon: feature_search -- title: Docker Scout subscriptions and features - description: Discover how a Docker Scout subscription can help you create a more secure supply chain. - link: /subscription/scout-details/ - icon: query_stats -- title: Docker Build Cloud subscriptions and features - description: Learn how a Docker Build Cloud subscription can accelerate your builds. - link: /subscription/build-cloud/build-details/ - icon: build -grid_core: -- title: Upgrade your subscription - description: Learn how to upgrade your plan to the next level. - link: /subscription/upgrade/ +- title: Set up your subscription + description: Get started setting up a personal or organization subscription. + link: /subscription/setup/ + icon: shopping_cart +- title: Scale your subscription + description: Scale your subscription to fit your needs. + link: /subscription/scale/ + icon: leaderboard +- title: Change your subscription + description: Learn how to upgrade or downgrade your plan. + link: /subscription/change/ icon: upgrade -- title: Add more seats to your subscription - description: Do more with Docker and add seats to your subscription. - link: /subscription/add-seats/ +- title: Manage seats + description: Learn how to add or remove seats from your subscription. + link: /subscription/manage-seats/ icon: group_add -grid_resources: - title: Docker Desktop license agreement description: Review the terms of the Docker Subscription Service Agreement. link: /subscription/desktop-license/ @@ -40,18 +39,10 @@ aliases: - /docker-hub/billing/faq/ --- -A Docker Core subscription includes licensing for commercial use of Docker components including Docker Desktop and Docker Hub. +A Docker subscription includes licensing for commercial use of Docker products +including Docker Desktop, Docker Hub, Docker Build Cloud, Docker Scout, and +Testcontainers Cloud. -Use the resources here to decide what subscription you need, manage an existing subscription, or explore additional products like Docker Scout or Docker Build Cloud. - -## Docker subscriptions and features +Use the resources here to decide what subscription you need, or manage an existing subscription. {{< grid items="grid_subscriptions" >}} - -## Manage your Docker Core subscription - -{{< grid items="grid_core" >}} - -## Resources - -{{< grid items="grid_resources" >}} diff --git a/content/manuals/subscription/build-cloud/_index.md b/content/manuals/subscription/build-cloud/_index.md deleted file mode 100644 index 672f4d17c0f..00000000000 --- a/content/manuals/subscription/build-cloud/_index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -build: - render: never -title: Docker Build Cloud -weight: 20 ---- diff --git a/content/manuals/subscription/build-cloud/build-details.md b/content/manuals/subscription/build-cloud/build-details.md deleted file mode 100644 index 697066f821a..00000000000 --- a/content/manuals/subscription/build-cloud/build-details.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: Subscriptions and features -description: Learn about the Docker Build Cloud subscriptions plans and features -keywords: subscription, pro, team, business, features, build, cloud, Build Cloud, remote builder -aliases: -- /subscription/build-details/ ---- - -{{< include "new-plans.md" >}} - -You can enhance your teams' builds with a Build Cloud subscription. This page describes the features available for the different subscription tiers. To compare features available for each tier, see [Docker Build Cloud pricing](https://www.docker.com/products/build-cloud/#pricing). - -## Docker Build Cloud Starter - -If you have an existing [Docker Core subscription](/subscription/core-subscription/details/), a base level of Build Cloud minutes and cache are included. The features available vary depending on your Docker Core subscription tier. - -### Docker Personal - -- 50 build minutes every month -- Available for one user -- 1 parallel build - -### Docker Pro - -- 100 build minutes every month -- Available for one user -- 4 parallel builds - -### Docker Team - -- 400 build minutes every month shared across your organization -- Option to onboard up to 100 members -- Can buy additional seats to add more minutes - -### Docker Business - -- All the features listed for Docker Team -- 800 build minutes every month shared across your organization - -## Docker Build Cloud Team - -You can buy Docker Build Cloud Team if you don’t have a Docker Core subscription, or upgrade any Docker Core tier to enhance your developers' experience with the following features: - -- 200 additional build minutes per seat -- Option to buy reserve minutes -- Increased shared cache - -The Docker Build Cloud Team subscription is tied to a Docker -[organization](/admin/organization/). To use the build minutes or -shared cache of a Docker Build Cloud Team subscription, users must be a part of -the organization associated with the subscription. See Manage seats and invites. - -To learn how to buy this subscription for your Docker organization, see [Buy your subscription - existing account or organization](/billing/build-billing#existing-account-or-organization). - -If you haven’t created a Docker organization yet and don’t have an existing Docker Core subscription, see [Buy your subscription - new organization](/billing/build-billing#new-organization). For organizations without a Docker Core subscription, this plan also includes 50 shared minutes in addition to the Docker Build Cloud Team minutes. - -## Docker Build Cloud Enterprise - -For enterprise features such as paying via invoice and additional build minutes, [contact sales](https://www.docker.com/products/build-cloud/#contact_sales). diff --git a/content/manuals/subscription/build-cloud/manage-seats.md b/content/manuals/subscription/build-cloud/manage-seats.md deleted file mode 100644 index de3599c277d..00000000000 --- a/content/manuals/subscription/build-cloud/manage-seats.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: Manage seats and invites -description: Learn how to add and remove seats for your Docker Build Cloud subscription, and invite members to your team. -keywords: subscription, team, business, features, build, cloud, Build Cloud, remote builder, manage users, add seats, remove seats ---- - -You can add seats and manage invitations to your Docker Build Cloud Team in the Docker Build Cloud dashboard. - -> [!NOTE] -> ->If you have a Docker Build Cloud Business subscription, you can add and remove seats by working with your account executive, then assign your purchased seats in the Docker Build Cloud dashboard. - -## Add seats - -1. Sign in to [Docker Build Cloud](https://build.docker.com/). -2. Select **Settings & billing**. -3. Under your current plan, select **Add seats**. -4. Select the number of seats you want to add, then select **Add seats**. - -The number of seats will be charged to your payment information on file, and are added immediately. - -## Remove seats - -1. Sign in to [Docker Build Cloud](https://build.docker.com/). -2. Select **Settings & billing**. -3. Under your current plan, select **Remove seats**. -4. Enter the total number of seats you want to keep on your plan, then select **Remove seats**. - -The charge for the reduced seat count will be reflected on the next billing cycle. Optionally, you can cancel the seat downgrade any time before the next billing cycle. - -## Invite users - -As an owner of the Docker Build Cloud team, you can invite members to access cloud builders. To invite team members to your team in Docker Build Cloud: - -1. Sign in to [Docker Build Cloud](https://build.docker.com/). -2. Select **User management**. -3. Select **Invite**. -4. Enter the email address or Docker ID of the member you want to invite. If the invitee doesn’t have a Docker ID yet, enter their email address so they can create an account when they accept the invite. -5. Select **Add**. - -Invitees receive an email with instructions on how they can accept the invite. After they accept, the seat will be marked as **Allocated** in the **User management** section in the Docker Build Cloud dashboard. - -For more information on the permissions granted to members, see [Roles and permissions](/security/for-admins/roles-and-permissions#docker-build-cloud). diff --git a/content/manuals/subscription/change.md b/content/manuals/subscription/change.md new file mode 100644 index 00000000000..6328ab3f6c6 --- /dev/null +++ b/content/manuals/subscription/change.md @@ -0,0 +1,115 @@ +--- +description: Learn how to change your Docker subscription +keywords: Docker Hub, upgrade, downgrade, subscription, Pro, Team, business, pricing plan +title: Change your subscription +aliases: +- /docker-hub/upgrade/ +- /docker-hub/billing/upgrade/ +- /subscription/upgrade/ +- /subscription/downgrade/ +- /subscription/core-subscription/upgrade/ +- /subscription/core-subscription/downgrade/ +- /docker-hub/cancel-downgrade/ +- /docker-hub/billing/downgrade/ +- /billing/scout-billing/ +weight: 30 +--- + +{{< include "tax-compliance.md" >}} + +The following sections describe how to change plans when you have a Docker +subscription plan or legacy Docker subscription plan. + +> [!NOTE] +> +> Legacy Docker plans apply to Docker subscribers who last purchased or renewed +> their subscription before December 10, 2024. These subscribers will keep +> their current plan and pricing until their next renewal date that falls on or +> after December 10, 2024. To see purchase or renewal history, view your +> [billing history](../billing/history.md). For more details about legacy +> subscriptions, see [Announcing Upgraded Docker +> Plans](https://www.docker.com/blog/november-2024-updated-plans-announcement/). + +## Upgrade your subscription + +When you upgrade a Docker plan, you immediately have access to all the features and entitlements available in your Docker subscription plan. For detailed information on features available in each subscription, see [Docker Pricing](https://www.docker.com/pricing). + +{{< tabs >}} +{{< tab name="Docker plan" >}} + +To upgrade your Docker subscription: + +1. Sign in to [Docker Home](https://app.docker.com/). +2. Under Settings and administration, select **Billing**. +3. Optional. If you're upgrading from a free Personal plan to a Team plan and want to keep your username, [convert your user account into an organization](../admin/organization/convert-account.md). +4. Select the account you want to upgrade in the drop-down at the top-left of the page. +5. Select **Upgrade**. +6. Follow the on-screen instructions to complete your upgrade. + +{{< /tab >}} +{{< tab name="Legacy Docker plan" >}} + +You can upgrade a legacy Docker Core, Docker Build Cloud, or Docker Scout subscription plan to a Docker subscription plan that includes access to all tools. + +Contact [Docker sales](https://www.docker.com/pricing/contact-sales/) to upgrade your legacy Docker plan. + +{{< /tab >}} +{{< /tabs >}} + +## Downgrade your subscription + +You can downgrade your Docker subscription at anytime before the renewal date. The unused portion of the subscription isn't refundable or creditable. + +When you downgrade your subscription, access to paid features is available until the next billing cycle. The downgrade takes effect on the next billing cycle. + +> [!IMPORTANT] +> +> If you downgrade your personal account from a Pro subscription to a Personal subscription, note that [Personal subscriptions](details.md#docker-personal) don't include collaborators for private repositories. Only one private repository is included with a Personal subscription. When you downgrade, all collaborators will be removed and additional private repositories are locked. +> Before you downgrade, consider the following: +> - Team size: You may need to reduce the number of team members and convert any private repositories to public repositories or delete them. For information on features available in each tier, see [Docker Pricing](https://www.docker.com/pricing). +> - SSO and SCIM: If you want to downgrade a Docker Business subscription and your organization uses single sign-on (SSO) for user authentication, you need to remove your SSO connection and verified domains before downgrading. After removing the SSO connection, any organization members that were auto-provisioned (for example, with SCIM) need to set up a password to sign in without SSO. To do this, users can [reset their password at sign in](/accounts/create-account/#reset-your-password-at-sign-in). + +{{< tabs >}} +{{< tab name="Docker plan" >}} + +If you have a [sales-assisted Docker Business subscription](details.md#sales-assisted), contact your account manager to downgrade your subscription. + +To downgrade your Docker subscription: + +1. Sign in to [Docker Home](https://app.docker.com/). +2. Under Settings and administration, select **Billing**. +3. Select the account you want to downgrade in the drop-down at the top-left of the page. +4. Select the action icon and then **Cancel subscription**. +5. Review the cancellation warnings, then select **Confirm cancellation**. +6. Optional. Fill out the feedback survey, or select **Skip**. + +{{< /tab >}} +{{< tab name="Legacy Docker plan" >}} + +If you have a [sales-assisted Docker Business subscription](details.md#sales-assisted), contact your account manager to downgrade your subscription. + +### Downgrade Legacy Docker plan + +To downgrade your legacy Docker subscription: + +1. Sign in to [Docker Hub Billing](https://hub.docker.com/billing). +2. Select the account you want to downgrade in the drop-down at the top-left of the page. +3. Select the link to **Manage this account on Docker Hub**. +4. In the plan section, select **Change plan**. +5. Follow the on-screen instructions to complete your downgrade. + +### Downgrade Docker Build Cloud subscription + +To downgrade your Docker Build Cloud subscription: + +1. Sign in to [Docker Home](https://app.docker.com) and open **Docker Build Cloud**. +2. Select **Account settings**, then **Downgrade**. +3. To confirm your downgrade, type **DOWNGRADE** in the text field and select **Yes, continue**. +4. The account settings page will update with a notification bar notifying you of your downgrade date (start of next billing cycle). + +{{< /tab >}} +{{< /tabs >}} + +## Pause a subscription + +You can't pause or delay a subscription. If a subscription invoice hasn't been paid on the due date, there's a 15 day grace period, including the due date. \ No newline at end of file diff --git a/content/manuals/subscription/core-subscription/_index.md b/content/manuals/subscription/core-subscription/_index.md deleted file mode 100644 index 3aead0e35cd..00000000000 --- a/content/manuals/subscription/core-subscription/_index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -build: - render: never -title: Docker Core -weight: 10 ---- diff --git a/content/manuals/subscription/core-subscription/add-seats.md b/content/manuals/subscription/core-subscription/add-seats.md deleted file mode 100644 index c8ecde5a15b..00000000000 --- a/content/manuals/subscription/core-subscription/add-seats.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -description: Learn how to add seats to an existing subscription -keywords: Docker, Docker Hub, subscription, update, add, seats, pricing, docker core -title: Add seats to your subscription -linkTitle: Add seats -aliases: -- /docker-hub/billing/add-seats/ -- /subscription/add-seats/ -weight: 20 ---- - -{{< include "tax-compliance.md" >}} - -You can add seats at anytime to your existing subscription. - -When you add seats to your subscription in the middle of your billing cycle, you are charged a prorated amount for the additional seats. - -> [!IMPORTANT] -> -> If you have a [sales-assisted Docker Business subscription](details.md#sales-assisted), contact your account manager to add seats to your subscription. - -1. Sign in to [Docker Home](https://app.docker.com). - -2. Select your **avatar** to open the drop-down menu. - -3. Select **Billing** from the drop-down menu and then **Add seats**. - -4. Specify the number of seats you want to add. - Your prorated fee is automatically calculated. - -5. Select **Purchase** to confirm. - The **Billing** tab displays the new number of seats. - -6. Navigate to the **Members** tab to add new members. For more information, see [Manage organization members](../../admin/organization/members.md). - -## Volume pricing - -Docker offers volume pricing for Docker Business subscriptions starting at 25 seats. Contact the [Docker Sales Team](https://www.docker.com/pricing/contact-sales/) for more information. diff --git a/content/manuals/subscription/core-subscription/details.md b/content/manuals/subscription/core-subscription/details.md deleted file mode 100644 index 021f7b2dc12..00000000000 --- a/content/manuals/subscription/core-subscription/details.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -title: Docker Core subscriptions and features -linkTitle: Subscriptions and features -description: Learn about Docker Core subscription tiers and their features -keywords: subscription, personal, pro, team, business, features, docker core subscription, docker core -aliases: -- /subscription/details/ -weight: 10 ---- - -{{< include "new-plans.md" >}} - -You can do more with Docker with a Docker Core subscription, such as add collaborators, create scoped access tokens, and create private repositories. This page provides an overview of each subscription tier. To compare features available in each tier, see [Docker Pricing](https://www.docker.com/pricing/). - -The following describes some of the key features included with your Docker Core subscription: - -![Docker Core subscription diagram](../images/subscription-diagram.webp) - -3 Docker Scout-enabled repositories for advanced remote image analysis. You can purchase a Docker Scout subscription to enable more repositories. See [Docker Scout subscriptions and features](../scout-details.md). - -Docker Build Cloud minutes are also included. For more information, see [Docker Build Cloud subscriptions and features](../build-cloud/build-details.md). - -Docker maintains a [public roadmap](https://github.com/docker/roadmap) so subscribers can see what new features are in development, as well as request new capabilities. - -## Docker Personal - -**Docker Personal** (formerly Docker Free) is ideal for open-source communities, individual developers, education, and small businesses, and includes the free use of Docker components including Docker Desktop and Docker Hub. -Docker Personal includes: - -- Unlimited public repositories -- Unlimited [Scoped Access Tokens](../../security/for-developers/access-tokens.md) -- Unlimited [collaborators](../../docker-hub/repos/access.md#collaborators-and-their-role) for public repositories at no cost per month. -- Access to [Docker Scout Free](../scout-details.md#docker-scout-free) to get started with software supply chain security. - -Additionally, anonymous users get 100 pulls every 6 hours and users that sign in to Docker get 200 pulls every 6 hours. - -For a list of features available in each tier, see [Docker Pricing](https://www.docker.com/pricing/). - -## Docker Pro - -**Docker Pro** enables individual developers to get more control of their development environment and provides an integrated and reliable developer experience. It reduces the amount of time developers spend on mundane and repetitive tasks and empowers developers to spend more time creating value for their customers. - -Docker Pro includes: -- All the features available in Personal -- Unlimited private repositories -- 5000 image [pulls per day](../../docker-hub/download-rate-limit.md) -- [Auto Builds](../../docker-hub/builds/_index.md) with 5 concurrent builds -- 300 [Vulnerability Scans](../../docker-hub/vulnerability-scanning.md) - -For a list of features available in each tier, see [Docker Pricing](https://www.docker.com/pricing/). - -## Docker Team - -**Docker Team** offers capabilities for collaboration, productivity, and security across organizations. It enables groups of developers to unlock the full power of collaboration and sharing combined with essential security features and team management capabilities. A Docker Team subscription includes licensing for commercial use of Docker components including Docker Desktop and Docker Hub. - -Docker Team includes: -- Everything included in Docker Pro -- Unlimited teams -- [Auto Builds](../../docker-hub/builds/_index.md) with 15 concurrent builds -- Unlimited [Vulnerability Scanning](../../docker-hub/vulnerability-scanning.md) -- 5000 image [pulls per day](../../docker-hub/download-rate-limit.md) for each team member - -There are also advanced collaboration and management tools, including organization and team management with [Role Based Access Control (RBAC)](../../security/for-admins/roles-and-permissions.md), [activity logs](../../admin/organization/activity-logs.md), and more. - -For a list of features available in each tier, see [Docker Pricing](https://www.docker.com/pricing/). - -## Docker Business - -**Docker Business** offers centralized management and advanced security features for enterprises that use Docker at scale. It empowers leaders to manage their Docker development environments and speed up their secure software supply chain initiatives. A Docker Business subscription includes licensing for commercial use of Docker components including Docker Desktop and Docker Hub. - -Docker Business includes: -- Everything included in Docker Team -- [Hardened Docker Desktop](/manuals/security/for-admins/hardened-desktop/_index.md) -- [Image Access Management](/manuals/security/for-admins/hardened-desktop/image-access-management.md) which lets admins control what content developers can access -- [Registry Access Management](/manuals/security/for-admins/hardened-desktop/registry-access-management.md) which lets admins control what registries developers can access -- [Company layer](../../admin/company/_index.md) to manage multiple organizations and settings -- [Single Sign-On](../../security/for-admins/single-sign-on/_index.md) -- [System for Cross-domain Identity Management](../../security/for-admins/provisioning/scim.md) and more. - -For a list of features available in each tier, see [Docker Pricing](https://www.docker.com/pricing/). - -### Self-serve - -A self-serve Docker Business subscription is where everything is set up by you. You can: - -- Manage your own invoices -- Add or remove seats -- Update billing and payment information -- Downgrade your subscription at any time - -### Sales-assisted - -A sales-assisted Docker Business subscription where everything is set up and managed by a dedicated Docker account manager. - -### Support for subscriptions - -All Docker Pro, Team, and Business subscribers receive email support for their subscriptions. Additional premium support is available for Docker Business customers. [Contact sales](https://www.docker.com/pricing/contact-sales/) for more information about premium support programs. diff --git a/content/manuals/subscription/core-subscription/downgrade.md b/content/manuals/subscription/core-subscription/downgrade.md deleted file mode 100644 index f1c65b5fb55..00000000000 --- a/content/manuals/subscription/core-subscription/downgrade.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -description: Learn how to downgrade your Docker subscription -keywords: Docker Hub, downgrade, subscription, Pro, Team, pricing plan, pause subscription, docker core -title: Downgrade your subscription -linkTitle: Downgrade -aliases: -- /docker-hub/cancel-downgrade/ -- /docker-hub/billing/downgrade/ -- /subscription/downgrade/ -weight: 50 ---- - -You can downgrade your Docker subscription at anytime before the renewal date. The unused portion of the subscription isn't refundable or creditable. - -When you downgrade your subscription, access to paid features is available until the next billing cycle. The downgrade takes effect on the next billing cycle. - -> [!IMPORTANT] -> -> If you downgrade your personal account from a Pro subscription to a Personal subscription, note that [Personal subscriptions](details.md#docker-personal) don't include collaborators for private repositories, and only one private repository is included. When you downgrade, all collaborators will be removed and additional private repositories are locked. - -## Before you downgrade - -Consider the following aspects before you downgrade your subscription. - -### Team size - -You may need to reduce the number of team members and convert any private repositories to public repositories or delete them. For information on features available in each tier, see [Docker Pricing](https://www.docker.com/pricing). - -### SSO and SCIM - -If you want to downgrade a Docker Business subscription and your organization uses single sign-on (SSO) for user authentication, you need to remove your SSO connection and verified domains before downgrading. After removing the SSO connection, any organization members that were auto-provisioned (for example, with SCIM) need to set up a password to sign in without SSO. To do this, users can [reset their password at sign in](/accounts/create-account/#reset-your-password-at-sign-in). - -## Downgrade your Docker subscription - ->[!IMPORTANT] -> ->If you have a [sales-assisted Docker Business subscription](details.md#sales-assisted), contact your account manager to downgrade your subscription. - -1. Sign in to [Docker Home](https://app.docker.com). - -2. Select your **avatar** and from the drop-down menu select **Billing**. - -3. Choose either your personal account or an organization to downgrade. - -4. In the plan section, select **Change plan**. - -5. Select the plan you'd like to downgrade to. - -6. Review the downgrade warning and select **Continue**. - -7. Optional. Select a reason for your downgrade from the list and select **Send**. - The **Billing** page displays a confirmation of the downgrade with details on when the downgrade changes take effect. - -If you want to cancel the downgrade, select **Cancel the downgrade** on the **Plan** tab. - -## Pause a subscription - -You can't pause or delay a subscription. If a subscription invoice hasn't been paid on the due date, there's a 15 day grace period, including the due date. diff --git a/content/manuals/subscription/core-subscription/remove-seats.md b/content/manuals/subscription/core-subscription/remove-seats.md deleted file mode 100644 index 87257f3fc3e..00000000000 --- a/content/manuals/subscription/core-subscription/remove-seats.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -description: Learn how to remove seats from your subscription -keywords: Docker, Docker Hub, subscription, update, remove, seats, docker core -title: Remove seats from your subscription -linkTitle: Remove seats -aliases: -- /docker-hub/billing/remove-seats/ -- /subscription/remove-seats/ -weight: 40 ---- - -You can remove seats from your Team or Business subscription at anytime. - -If you remove seats in the middle of the billing cycle, changes apply in the next billing cycle. Any unused portion of the subscription for removed seats isn't refundable or creditable. - -For example, if you receive your billing on the 8th of every month for 10 seats and you want to remove 2 seats on the 15th of the month, the 2 seats will be removed from your subscription the next month. Your payment for 8 seats begins on the next billing cycle. If you're on the annual subscription, the 2 seats are still available until the next year, and your payment for the 8 seats begins on the next billing cycle. - -## Remove seats from a monthly or an annual subscription - ->[!IMPORTANT] -> ->If you have a [sales-assisted Docker Business subscription](details.md#sales-assisted), contact your account manager to remove seats from your subscription. - -1. Sign in to [Docker Home](https://app.docker.com). - -2. Select your **avatar** to expand the drop-down menu. - -3. Select **Billing** from the drop-down menu and then **Remove seats**. - -4. Specify how many seats you’d like to remove and then select **Remove** to confirm. - -5. The **Billing** tab confirms the seat removal and the details on when the changes take effect. - -You can cancel the removal of seats before your next billing cycle. To do so, select **Cancel change** in the bottom-right corner. diff --git a/content/manuals/subscription/core-subscription/upgrade.md b/content/manuals/subscription/core-subscription/upgrade.md deleted file mode 100644 index 0897f87a392..00000000000 --- a/content/manuals/subscription/core-subscription/upgrade.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -description: Learn how to upgrade your Docker subscription -keywords: Docker Hub, upgrade, subscription, Pro, Team, business, pricing plan, docker core -title: Upgrade your subscription -linkTitle: Upgrade -aliases: -- /docker-hub/upgrade/ -- /docker-hub/billing/upgrade/ -- /subscription/upgrade/ -weight: 30 ---- - -When you upgrade to a paid subscription, you immediately have access to all the features and entitlements available in your new chosen subscription. For detailed information on features available in each subscription, see [Docker Pricing](https://www.docker.com/pricing). - -{{< include "tax-compliance.md" >}} - -## Upgrade your subscription - -1. Sign in to [Docker Home](https://app.docker.com). - -2. Optional. If you're upgrading from a free user account to a Team subscription and want to keep your account name, [convert your user account into an organization](../../admin/convert-account.md). - -3. Select your **avatar** to expand the drop-down menu. - -4. From the drop-down menu, select **Billing** and then the account you want to upgrade. - -5. On the **Billing Details** tab, select **Change plan** and then choose the plan you'd like to upgrade to. - - > [!TIP] - > - > If your current plan is a free plan, select **Buy now**. - -6. Follow the on-screen instructions. - - If you have a coupon to use, you can enter it during this step. diff --git a/content/manuals/subscription/desktop-license.md b/content/manuals/subscription/desktop-license.md index da4a17fea9a..a0c129a2ab9 100644 --- a/content/manuals/subscription/desktop-license.md +++ b/content/manuals/subscription/desktop-license.md @@ -27,4 +27,4 @@ GNU General Public License. Select [here](https://download.docker.com/opensource > [!TIP] > -> Explore [Docker subscriptions](https://www.docker.com/pricing/) to see what else Docker can offer you. +> Explore [Docker subscriptions](https://www.docker.com/pricing/) to see what else Docker can offer you. diff --git a/content/manuals/subscription/details.md b/content/manuals/subscription/details.md new file mode 100644 index 00000000000..27952d45c13 --- /dev/null +++ b/content/manuals/subscription/details.md @@ -0,0 +1,403 @@ +--- +title: Docker subscriptions and features +linkTitle: Subscriptions and features +description: Learn about Docker subscription tiers and their features +keywords: subscription, personal, pro, team, business, features, docker subscription +aliases: +- /subscription/core-subscription/details/ +weight: 10 +--- + +Docker subscription plans empower development teams by providing the tools they need to ship secure, high-quality apps — fast. These plans include access to Docker's suite of products: + +- [Docker Desktop](../desktop/_index.md): The industry-leading container-first + development solution that includes, Docker Engine, Docker CLI, Docker Compose, + Docker Build/BuildKit, and Kubernetes. +- [Docker Hub](../docker-hub/_index.md): The world's largest cloud-based + container registry. +- [Docker Build Cloud](../build-cloud/_index.md): Powerful cloud-based builders that accelerate build times by up to 39x. +- [Docker Scout](../scout/_index.md): Tooling for software supply chain security + that lets you quickly assess image health and accelerate security improvements. +- [Testcontainers Cloud](https://testcontainers.com/cloud/docs): Container-based + testing automation that provides faster tests, a unified developer experience, + and more. + +The following sections describe some of the key features included with your +Docker subscription plan or Legacy Docker plan. + +> [!NOTE] +> +> Legacy Docker plans apply to Docker subscribers who last purchased or renewed their subscription before December 10, 2024. These subscribers will keep their current plan and pricing until their next renewal date that falls on or after December 10, 2024. To see purchase or renewal history, view your [billing history](../billing/history.md). For more details about Docker legacy plans, see [Announcing Upgraded Docker Plans](https://www.docker.com/blog/november-2024-updated-plans-announcement/). In addition to current features, Docker maintains a [public roadmap](https://github.com/docker/roadmap) so subscribers can see what new +features are in development, as well as request new capabilities. + +{{< tabs >}} +{{< tab name="Docker plan" >}} + +## Docker Personal + +**Docker Personal** is ideal for open source communities, individual developers, +education, and small businesses. It includes the free use of essential Docker +tools as well as trials for powerful tools that'll level up your development loops. + +Docker Personal includes: + +- 1 included repository with continuous vulnerability analysis in Docker Scout +- Unlimited public Docker Hub repositories +- 1 private Docker Hub repository with 2GB storage +- 40 pulls per hour Docker Hub image pull rate limit +- 7-day Docker Build Cloud trial +- 7-day Testcontainers Cloud trial + +Docker Personal users who want to continue using Docker Build Cloud or Docker +Testcontainers Cloud after their trial can upgrade to a Docker Pro plan at any +time. + +All unauthenticated user, including unauthenticated Docker Personal users, get +10 pulls per hour per IP address. + +For a list of features available in each tier, see [Docker Pricing](https://www.docker.com/pricing/). + +## Docker Pro + +**Docker Pro** enables individual developers to get more control of their +development environment and provides an integrated and reliable developer +experience. It reduces the amount of time developers spend on mundane and +repetitive tasks and empowers developers to spend more time creating value for +their customers. A Docker Pro subscription includes access to all tools, +including Docker Desktop, Docker Hub, Docker Scout, Docker Build Cloud, and +Testcontainers Cloud. + +Docker Pro includes: + +- 200 Docker Build Cloud minutes per month. +- 2 included repositories with continuous vulnerability analysis in Docker Scout. +- 100 Testcontainers Cloud runtime minutes per month for use either in Docker Desktop or for CI. +- No Docker Hub image pull rate limits. +- 25K Docker Hub pulls per month are included. + +For a list of features available in each tier, see [Docker +Pricing](https://www.docker.com/pricing/). + +## Docker Team + +**Docker Team** offers capabilities for collaboration, productivity, and +security across organizations. It enables groups of developers to unlock the +full power of collaboration and sharing combined with essential security +features and team management capabilities. A Docker Team subscription includes +licensing for commercial use of Docker components including Docker Desktop, +Docker Hub, Docker Scout, Docker Build Cloud, and Testcontainers Cloud. + +Docker Team includes: + +- 500 Docker Build Cloud minutes per month. +- Unlimited Docker Scout repositories with continuous vulnerability analysis. +- 500 Testcontainers Cloud runtime minutes per month for use either in Docker Desktop or for CI. +- No Docker Hub image pull rate limits. +- 100K Docker Hub pulls per month. + +There are also advanced collaboration and management tools, including +organization and team management with [Role Based Access Control +(RBAC)](/security/for-admins/roles-and-permissions/), [activity logs](/admin/organization/activity-logs/), and more. + +For a list of features available in each tier, see [Docker +Pricing](https://www.docker.com/pricing/). + +## Docker Business + +**Docker Business** offers centralized management and advanced security features +for enterprises that use Docker at scale. It empowers leaders to manage their +Docker development environments and speed up their secure software supply chain +initiatives. A Docker Business subscription includes licensing for commercial use of +Docker components including Docker Desktop, Docker Hub, Docker Scout, Docker +Build Cloud, and Testcontainers Cloud. + +Docker Business includes: + +- 1500 Docker Build Cloud minutes per month. +- Unlimited Docker Scout repositories with continuous vulnerability analysis. +- 1500 Testcontainers Cloud runtime minutes per month for use either in Docker Desktop or + for CI. +- No Docker Hub image pull rate limits. +- 1M Docker Hub pulls per month. + +In addition, you gain access to enterprise-grade features, such as: +- [Hardened Docker Desktop](../security/for-admins/hardened-desktop/_index.md) +- [Image Access + Management](../security/for-admins/hardened-desktop/image-access-management.md) + which lets admins control what content developers can access +- [Registry Access + Management](../security/for-admins/hardened-desktop/registry-access-management.md) + which lets admins control what registries developers can access +- [Company layer](/admin/company/) to manage multiple organizations and settings +- [Single sign-on](/security/for-admins/single-sign-on/) +- [System for Cross-domain Identity + Management](/security/for-admins/provisioning/scim/) + +For a list of features available in each tier, see [Docker +Pricing](https://www.docker.com/pricing/). + +## Self-serve + +A self-serve Docker subscription is where everything is set up by you. +You can: + +- Manage your own invoices +- Add or remove seats +- Update billing and payment information +- Downgrade your subscription at any time + +## Sales-assisted + +A sales-assisted plan refers to a Docker Business or Team subscription where everything is set up and +managed by a dedicated Docker account manager. + +{{< /tab >}} +{{< tab name="Legacy Docker plans" >}} + +> [!IMPORTANT] +> +> As of December 10, 2024, Docker Core, Docker Build Cloud, and Docker Scout +> subscription plans are no longer available and have been replaced by Docker subscription +> plans that provide access to all tools. If you subscribed or renewed +> your subscriptions before December 10, 2024, your legacy Docker +> plans still apply to your account until you renew. For more details, +> see [Announcing Upgraded Docker +> Plans](https://www.docker.com/blog/november-2024-updated-plans-announcement/). +The following describes some of the key features included with your Legacy Docker plans: + +![Docker Core subscription diagram](./images/subscription-diagram.webp) + +## Legacy Docker plans + +### Legacy Docker Pro + +**Legacy Docker Pro** enables individual developers to get more control of their +development environment and provides an integrated and reliable developer +experience. It reduces the amount of time developers spend on mundane and +repetitive tasks and empowers developers to spend more time creating value for +their customers. + +Legacy Docker Pro includes: +- Unlimited public repositories +- Unlimited [Scoped Access Tokens](/security/for-developers/access-tokens/) +- Unlimited [collaborators](/docker-hub/repos/manage/access/#collaborators) for public repositories at no cost per month. +- Access to [Legacy Docker Scout Free](#legacy-docker-scout-free) to get started with software supply chain security. +- Unlimited private repositories +- 5000 image [pulls per day](/docker-hub/download-rate-limit/) +- [Auto Builds](/docker-hub/builds/) with 5 concurrent builds +- 300 [Vulnerability Scans](/docker-hub/vulnerability-scanning/) + +For a list of features available in each legacy tier, see [Legacy Docker Pricing](https://www.docker.com/legacy-pricing/). + +#### Upgrade your Legacy Docker Pro plan + +When you upgrade your Legacy Docker Pro plan to a Docker Pro subscription plan, your plan includes the following changes: + +- Docker Build Cloud minutes increased from 100/month to 200/month and no monthly fee. +- 2 included repositories with continuous vulnerability analysis in Docker Scout. +- 100 Testcontainers Cloud runtime minutes are now included for use either in Docker Desktop or for CI. +- Docker Hub image pull rate limits are removed. +- 25K Docker Hub pulls per month are included. + +For a list of features available in each tier, see [Docker Pricing](https://www.docker.com/pricing/). + +### Legacy Docker Team + +**Legacy Docker Team** offers capabilities for collaboration, productivity, and +security across organizations. It enables groups of developers to unlock the +full power of collaboration and sharing combined with essential security +features and team management capabilities. A Docker Team subscription includes +licensing for commercial use of Docker components including Docker Desktop and +Docker Hub. + +Legacy Docker Team includes: +- Everything included in legacy Docker Pro +- Unlimited teams +- [Auto Builds](/docker-hub/builds/) with 15 concurrent builds +- Unlimited [Vulnerability Scanning](/docker-hub/vulnerability-scanning/) +- 5000 image [pulls per day](/docker-hub/download-rate-limit/) for each team member + +There are also advanced collaboration and management tools, including organization and team management with [Role Based Access Control (RBAC)](/security/for-admins/roles-and-permissions/), [activity logs](/admin/organization/activity-logs/), and more. + +For a list of features available in each legacy tier, see [Legacy Docker Pricing](https://www.docker.com/legacy-pricing/). + +#### Upgrade your Legacy Docker Team plan + +When you upgrade your Legacy Docker Team plan to a Docker Team subscription plan, your plan includes the following changes: + +- Instead of paying an additional per-seat fee, Docker Build Cloud is now available to all users in your Docker plan. +- Docker Build Cloud minutes increase from 400/mo to 500/mo. +- Docker Scout now includes unlimited repositories with continuous vulnerability analysis, an increase from 3. +- 500 Testcontainers Cloud runtime minutes are now included for use either in Docker Desktop or for CI. +- Docker Hub image pull rate limits are removed. +- 100K Docker Hub pulls per month are included. +- The minimum number of users is 1 (lowered from 5). + +For a list of features available in each tier, see [Docker Pricing](https://www.docker.com/pricing/). + +### Legacy Docker Business + +**Legacy Docker Business** offers centralized management and advanced security features +for enterprises that use Docker at scale. It empowers leaders to manage their +Docker development environments and speed up their secure software supply chain +initiatives. A Docker Business subscription includes licensing for commercial +use of Docker components including Docker Desktop and Docker Hub. + +Legacy Docker Business includes: +- Everything included in legacy Docker Team +- [Hardened Docker Desktop](../security/for-admins/hardened-desktop/_index.md) +- [Image Access Management](../security/for-admins/hardened-desktop/image-access-management.md) which lets admins control what content developers can access +- [Registry Access Management](../security/for-admins/hardened-desktop/registry-access-management.md) which lets admins control what registries developers can access +- [Company layer](/admin/company/) to manage multiple organizations and settings +- [Single Sign-On](/security/for-admins/single-sign-on/) +- [System for Cross-domain Identity Management](/security/for-admins/provisioning/scim/) and more. + +For a list of features available in each tier, see [Legacy Docker Pricing](https://www.docker.com/legacy-pricing/). + +#### Upgrade your Legacy Docker Business plan + +When you upgrade your Legacy Docker Business plan to a Docker Business subscription plan, your plan includes the following changes: + +- Instead of paying an additional per-seat fee, Docker Build Cloud is now available to all users in your Docker plan. +- Docker Build Cloud included minutes increase from 800/mo to 1500/mo. +- Docker Scout now includes unlimited repositories with continuous vulnerability analysis, an increase from 3. +- 1500 Testcontainers Cloud runtime minutes are now included for use either in Docker Desktop or for CI. +- Docker Hub image pull rate limits are removed. +- 1M Docker Hub pulls per month are included. + +For a list of features available in each tier, see [Docker Pricing](https://www.docker.com/pricing/). + +#### Self-serve + +A self-serve Docker Business subscription is where everything is set up by you. You can: + +- Manage your own invoices +- Add or remove seats +- Update billing and payment information +- Downgrade your subscription at any time + +#### Sales-assisted + +A sales-assisted Docker Business subscription where everything is set up and managed by a dedicated Docker account manager. + +## Legacy Docker Scout subscriptions + +This section provides an overview of the legacy subscription plans for Docker +Scout. + +> [!IMPORTANT] +> +> As of December 10, 2024, Docker Scout subscriptions are no longer available +> and have been replaced by Docker subscription plans that provide access to +> all tools. If you subscribed or renewed your subscriptions before December 10, 2024, your legacy Docker subscriptions still apply to your account until +> you renew. For more details, see [Announcing Upgraded Docker +> Plans](https://www.docker.com/blog/november-2024-updated-plans-announcement/). + +### Legacy Docker Scout Free + +Legacy Docker Scout Free is available for organizations. If you have a Legacy Docker plan, you automatically have access to legacy Docker Scout Free. + +Legacy Docker Scout Free includes: + +- Unlimited local image analysis +- Up to 3 Docker Scout-enabled repositories +- SDLC integration, including policy evaluation and workload integration +- On-prem and cloud container registry integrations +- Security posture reporting + +### Legacy Docker Scout Team + +Legacy Docker Scout Team includes: + +- All the features available in legacy Docker Scout Free +- In addition to 3 Docker Scout-enabled repositories, add up to 100 repositories when you buy your subscription + +### Legacy Docker Scout Business + +Legacy Docker Scout Business includes: + +- All the features available in legacy Docker Scout Team +- Unlimited Docker Scout-enabled repositories + +### Upgrade your Legacy Docker Scout plan + +When you upgrade your Legacy Docker Scout plan to a Docker subscription plan, your +plan includes the following changes: + +- Docker Business: Unlimited repositories with continuous vulnerability analysis, an increase from 3. +- Docker Team: Unlimited repositories with continuous vulnerability analysis, an increase from 3 +- Docker Pro: 2 included repositories with continuous vulnerability analysis. +- Docker Personal: 1 included repository with continuous vulnerability analysis. + +For a list of features available in each tier, see [Docker Pricing](https://www.docker.com/pricing/). + +## Legacy Docker Build Cloud subscriptions + + This section describes the features available for the different legacy Docker + Build Cloud subscription tiers. + +> [!IMPORTANT] +> +> As of December 10, 2024, Docker Build Cloud is only available with the +> new Docker Pro, Team, and Business plans. When your plan renews on or after +> December 10, 2024, you will see an increase in your included Build Cloud +> minutes each month. For more details, see [Announcing Upgraded Docker +> Plans](https://www.docker.com/blog/november-2024-updated-plans-announcement/). + +### Legacy Docker Build Cloud Starter + +If you have a Legacy Docker plan, a base level of Build Cloud +minutes and cache are included. The features available vary depending on your +Legacy Docker plan subscription tier. + +#### Legacy Docker Pro + +- 100 build minutes every month +- Available for one user +- 4 parallel builds + +#### Legacy Docker Team + +- 400 build minutes every month shared across your organization +- Option to onboard up to 100 members +- Can buy additional seats to add more minutes + +#### Legacy Docker Business + +- All the features listed for Docker Team +- 800 build minutes every month shared across your organization + +### Legacy Docker Build Cloud Team + +Legacy Docker Build Cloud Team offers the following features: + +- 200 additional build minutes per seat +- Option to buy reserve minutes +- Increased shared cache + +The legacy Docker Build Cloud Team subscription is tied to a Docker +[organization](/admin/organization/). To use the build minutes or +shared cache of a legacy Docker Build Cloud Team subscription, users must be a part of +the organization associated with the subscription. See Manage seats and invites. + +### Legacy Docker Build Cloud Enterprise + +For more details about your enterprise subscription, [contact sales](https://www.docker.com/products/build-cloud/#contact_sales). + +### Upgrade your Legacy Docker Build Cloud plan + +You no longer need to subscribe to a separate Docker Build Cloud plan to access +Docker Build Cloud or to scale your minutes. When you upgrade your Legacy Docker plan to +a Docker subscription plan, your plan includes the following changes: + +- Docker Business: Included minutes are increased from 800/mo to 1500/mo with the option to scale more minutes. +- Docker Team: Included minutes are increased from 400/mo to 500/mo with the option to scale more minutes. +- Docker Pro: Included minutes are increased from 100/mo to 200/mo with the option to scale more minutes. +- Docker Personal: You receive a 7-day trial. + +{{< /tab >}} +{{< /tabs >}} + +## Support for subscriptions + +All Docker Pro, Team, and Business subscribers receive email support for their subscriptions. \ No newline at end of file diff --git a/content/manuals/subscription/faq.md b/content/manuals/subscription/faq.md index d3aff73d09a..b4713d9b632 100644 --- a/content/manuals/subscription/faq.md +++ b/content/manuals/subscription/faq.md @@ -15,7 +15,7 @@ Subscriptions are non-transferable. ### Can I pause or delay my Docker subscription? -You can't pause or delay a subscription, but you can [downgrade](downgrade.md). If a subscription invoice hasn't been paid on the due date, there's a 15 day grace period, including the due date. +You can't pause or delay a subscription, but you can [downgrade](change.md). If a subscription invoice hasn't been paid on the due date, there's a 15 day grace period, including the due date. ### Does Docker offer academic pricing? @@ -24,7 +24,7 @@ Contact the [Docker Sales Team](https://www.docker.com/company/contact). ### What ways can I contribute to Docker content? Docker offers two programs: -- [Docker-Sponsored Open Source Program (DSOS)](../trusted-content/dsos-program.md) -- [Docker Verified Publisher (DVP)](../trusted-content/dvp-program.md) +- [Docker-Sponsored Open Source Program (DSOS)](../docker-hub/repos/manage/trusted-content/dsos-program.md) +- [Docker Verified Publisher (DVP)](../docker-hub/repos/manage/trusted-content/dvp-program.md) You can also join the [Developer Preview Program](https://www.docker.com/community/get-involved/developer-preview/) or sign up for early access programs for specific products to participate in research and try out new features. diff --git a/content/manuals/subscription/manage-seats.md b/content/manuals/subscription/manage-seats.md new file mode 100644 index 00000000000..5cadecf411a --- /dev/null +++ b/content/manuals/subscription/manage-seats.md @@ -0,0 +1,114 @@ +--- +description: Learn how to add or remove seats for an existing subscription +keywords: Docker, Docker Hub, subscription, update, add, seats, pricing +title: Manage subscription seats +linkTitle: Manage seats +aliases: +- /docker-hub/billing/add-seats/ +- /subscription/add-seats/ +- /docker-hub/billing/remove-seats/ +- /subscription/remove-seats/ +- /subscription/core-subscription/add-seats/ +- /subscription/core-subscription/remove-seats/ +weight: 20 +--- + +You can add seats at anytime to your existing subscription. + +When you add seats to your subscription in the middle of your billing cycle, you are charged a prorated amount for the additional seats. + +{{< include "tax-compliance.md" >}} + +## Add seats + +{{< tabs >}} +{{< tab name="Docker plan" >}} + +> [!IMPORTANT] +> +> If you have a [sales-assisted Docker Business subscription](details.md#sales-assisted), contact your account manager to add seats to your subscription. + +To add seats to your subscription: + +1. Sign in to [Docker Home](https://app.docker.com/). +2. Under Settings and administration, select **Billing**. +3. Select your account from the drop-down menu in the top-left. +4. Select **Add seats**. +5. Follow the on-screen instructions to complete adding seats. + +You can now add more members to your organization. For more information, see [Manage organization members](../admin/organization/members.md). + +{{< /tab >}} +{{< tab name="Legacy Docker plan" >}} + +> [!IMPORTANT] +> +> If you have a [sales-assisted Docker Business subscription](details.md#sales-assisted), contact your account manager to add seats to your subscription. + +### Add seats to Legacy Docker plan + +1. Sign in to [Docker Hub](https://hub.docker.com). +2. Select your avatar in the top-left, and select **Billing** from the drop-down menu. +3. On the Billing page, select **Add seats**. +4. Select the number of seats you want to add, then select **Purchase**. + +### Add seats to Docker Build Cloud + +1. Sign in to Docker Build Cloud. +2. Select **Account settings**, then **Add seats**. +3. Select the number of seats you want to add, then select **Add seats**. + +{{< /tab >}} +{{< /tabs >}} + +### Volume pricing + +Docker offers volume pricing for Docker Business subscriptions starting at 25 seats. Contact the [Docker Sales Team](https://www.docker.com/pricing/contact-sales/) for more information. + +## Remove seats + +You can remove seats from your Team or Business subscription at anytime. + +If you remove seats in the middle of the billing cycle, changes apply in the next billing cycle. Any unused portion of the subscription for removed seats isn't refundable or creditable. + +For example, if you receive your billing on the 8th of every month for 10 seats and you want to remove 2 seats on the 15th of the month, the 2 seats will be removed from your subscription the next month. Your payment for 8 seats begins on the next billing cycle. If you're on the annual subscription, the 2 seats are still available until the next year, and your payment for the 8 seats begins on the next billing cycle. + +{{< tabs >}} +{{< tab name="Docker plan" >}} + +> [!IMPORTANT] +> +> If you have a [sales-assisted Docker Business subscription](details.md#sales-assisted), contact your account manager to remove seats from your subscription. + +To remove seats: + +1. Sign in to [Docker Home](https://app.docker.com/). +2. Under Settings and administration, select **Billing**. +3. Select your account from the drop-down menu in the top-left. +4. Select the action icon and then select **Remove seats**. +5. Follow the on-screen instructions to complete removing seats. + +You can cancel the removal of seats before your next billing cycle. To do so, select **Cancel change**. + +{{< /tab >}} +{{< tab name="Legacy Docker plan" >}} + +> [!IMPORTANT] +> +> If you have a [sales-assisted Docker Business subscription](details.md#sales-assisted), contact your account manager to remove seats from your subscription. + +### Remove seats from Legacy Docker plan + +1. Sign in to [Docker Hub](https://hub.docker.com). +2. Select your avatar in the top-left, and select **Billing** from the drop-down menu. +3. On the Billing page, select **Remove seats**. +4. Follow the on-screen instructions to complete removing seats. + +### Remove seats from Docker Build Cloud + +1. Sign in to [Docker Build Cloud](https://app.docker.com/build). +2. Select **Account settings**, then **Remove seats**. +3. Follow the on-screen instructions to complete removing seats. + +{{< /tab >}} +{{< /tabs >}} \ No newline at end of file diff --git a/content/manuals/subscription/scale.md b/content/manuals/subscription/scale.md new file mode 100644 index 00000000000..9f3f51f2e7f --- /dev/null +++ b/content/manuals/subscription/scale.md @@ -0,0 +1,75 @@ +--- +description: Learn how to scale your Docker subscription +keywords: subscription, Pro, Team, business, pricing plan, build minutes, test container minutes, pull limit +title: Scale your subscription +weight: 17 +--- + +> [!NOTE] +> +> Owners of legacy Docker subscription plans must upgrade their subscription to a new +> Docker subscription plan in order to scale their subscription. +> +> Legacy Docker plans apply to Docker subscribers who last purchased or renewed +> their subscription before December 10, 2024. These subscribers will keep +> their current plan and pricing until their next renewal date that falls on or +> after December 10, 2024. To see purchase or renewal history, view your +> [billing history](../billing/history.md). For more details about legacy +> after December 10, 2024. For more details about legacy +> subscriptions, see [Announcing Upgraded Docker +> Plans](https://www.docker.com/blog/november-2024-updated-plans-announcement/). + +Docker subscriptions let you scale your consumption as your needs evolve. Except +for legacy Docker subscription plans, all paid Docker subscriptions come with +access to Docker Hub, Docker Build Cloud, and Testcontainers Cloud with a base +amount of consumption. See [Docker subscriptions and features](./details.md) to +learn how much base consumption comes with each subscription. You can scale your +consumption at any time during your subscription period. All purchased +consumption expires at the end of your subscription term. +amount of consumption. You can scale your consumption at any time during your subscription period. All purchased consumption expires at the end of your subscription term. + +You can scale consumption for the following: + +- Docker Build Cloud minutes +- Docker Testcontainers Cloud runtime minutes +- Docker Hub storage and image pulls + +To better understand your needs, you can view your consumption at any time. For +more details, see [View Docker product +usage](../admin/organization/manage-products.md#view-docker-product-usage). + +## Add Docker Build Cloud minutes + +You can pre-purchase Docker Build Cloud minutes in the Docker Build Cloud Dashboard: + +1. Sign in to [Docker Home](https://app.docker.com/). +2. Under Settings and administration, select **Billing**. +3. On the plans and usage page, select **View build minutes**. + This will launch the Docker Build Cloud settings page. +4. Select **Add minutes**. +5. Select your additional minute amount, then **Continue to payment**. +6. Enter your payment details and billing address. +7. Review your order and select **Pay**. + +Your additional minutes will now display on the Build minutes page. + +## Add Docker Testcontainers Cloud runtime minutes + +You can pre-purchase Testcontainers Cloud runtime minutes by [contacting + sales](https://www.docker.com/pricing/contact-sales/). In addition to +pre-purchase, you are able to use as many minutes as you need on-demand. The +usage will be billed at the end of each monthly billing cycle. On-demand usage +is billed at a higher rate than pre-purchased capacity. To avoid on-demand +charges, pre-purchase additional minutes. + +## Add Docker Hub storage or image pulls + +{{< include "hub-limits.md" >}} + +You can pre-purchase images pulls and storage by [contacting +sales](https://www.docker.com/pricing/contact-sales/). + +In addition to pre-purchase, you are able to use as much resources as you need +on-demand. On-demand usage is billed at a higher rate than pre-purchased +capacity. To avoid on-demand charges, pre-purchase additional storage or image +pulls. \ No newline at end of file diff --git a/content/manuals/subscription/scout-details.md b/content/manuals/subscription/scout-details.md deleted file mode 100644 index 690deb2e483..00000000000 --- a/content/manuals/subscription/scout-details.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: Docker Scout subscriptions and features -description: Learn about the Docker Scout subscriptions plans and features -keywords: subscription, free, team, business, features -weight: 30 ---- - -{{< include "new-plans.md" >}} - -This page provides an overview of the subscription plans for Docker Scout. To compare features available for each plan, see [Docker Scout Pricing](https://docker.com/products/docker-scout). - -## Docker Scout Free - -Docker Scout Free is available for both personal accounts and organizations. If you have a [Docker subscription](./core-subscription/details.md), you automatically have access to Docker Scout Free. This plan is ideal for individual developers getting started with software supply chain security. - -Docker Scout Free includes: - -- Unlimited local image analysis -- Up to 3 Docker Scout-enabled repositories -- SDLC integration, including policy evaluation and workload integration -- On-prem and cloud container registry integrations -- Security posture reporting - -## Docker Scout Team - -Docker Scout Team is available for both personal accounts and organizations. This plan is ideal for development teams developing and maintaining multiple container images. - -Docker Scout Team includes: - -- All the features available in Docker Scout Free -- In addition to 3 Docker Scout-enabled repositories, add up to 100 repositories when you buy your subscription - -You can buy Docker Scout Team in Docker Hub. See [Docker Scout billing](../billing/scout-billing.md). To learn more about pricing per repository, see [Docker Scout Pricing](https://www.docker.com/products/docker-scout/). - -## Docker Scout Business - -Docker Scout Business is ideal for commercial organizations managing multiple teams. - -Docker Scout Business includes: - -- All the features available in Docker Scout Team -- Unlimited Docker Scout-enabled repositories - -You can [contact sales](https://www.docker.com/products/docker-scout/) to buy Docker Scout Business. diff --git a/content/manuals/subscription/setup.md b/content/manuals/subscription/setup.md new file mode 100644 index 00000000000..b87bb574db9 --- /dev/null +++ b/content/manuals/subscription/setup.md @@ -0,0 +1,26 @@ +--- +description: Learn how to set up your Docker subscription +keywords: subscription, Pro, Team, Business, pricing plan +title: Set up your subscription +weight: 15 +--- + +Docker subscriptions offer features and benefits to support both new and professional developers, as well as plans for individuals, teams, and enterprise businesses. To learn more about what's included with each tier, see [Docker subscriptions and features](./details.md) and [Docker Pricing](https://www.docker.com/pricing/). + +In this section, learn how to get started with a Docker subscription for individuals or for organizations. Before you begin, make sure you have a [Docker ID](../accounts/create-account.md). + +{{< include "tax-compliance.md" >}} + +## Set up a Docker subscription for a personal account + +After you [create your Docker ID](../accounts/create-account.md), you have a Docker Personal subscription. To continue using this plan, no further action is necessary. For additional features, you can upgrade to a Docker Pro plan. + +To upgrade from Docker Personal to Docker Pro, see [Upgrade your subscription](./change.md#upgrade-your-subscription). + +## Set up a Docker subscription for an organization + +You can subscribe a new or existing organization to a Docker plan. Only organization owners can manage billing for the organization. + +After you [create your Docker ID](../accounts/create-account.md), you have a Docker Personal plan. You must then create an organization and choose a subscription for it. For more details, see [Create your organization](../admin/organization/orgs.md). + +To learn how to upgrade a Docker subscription for an existing organization, see [Upgrade your subscription](./change.md#upgrade-your-subscription). \ No newline at end of file diff --git a/content/manuals/tcc.md b/content/manuals/tcc.md index a89e26d1252..242eb05bf6e 100644 --- a/content/manuals/tcc.md +++ b/content/manuals/tcc.md @@ -1,7 +1,8 @@ --- title: Testcontainers Cloud -weight: 200 +weight: 70 params: sidebar: + group: Products goto: "https://testcontainers.com/cloud/docs/" --- diff --git a/content/manuals/trusted-content/_index.md b/content/manuals/trusted-content/_index.md deleted file mode 100644 index cf8ffc177cd..00000000000 --- a/content/manuals/trusted-content/_index.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Trusted content -weight: 200 -description: Optimize your development workflow with secure base images from our selection of trusted content -keywords: doi, dvp, dsos, open source, security, base images -grid: -- title: Docker Official Images - description: A curated set of Docker repositories hosted on Docker Hub. - icon: /trusted-content/images/doi-icon.svg - link: /trusted-content/official-images/ -- title: Docker Verified Publisher - description: High-quality images from verified vendors. - icon: /trusted-content/images/dvp-icon.svg - link: /trusted-content/dvp-program/ -- title: Docker-Sponsored Open Source - description: High-quality images from non-commercial open source projects. - icon: /trusted-content/images/dsos-icon.svg - link: /trusted-content/dsos-program/ ---- - -Trusted content is a selection of high-quality, secure images, curated by -Docker and verified publishing partners. These images are stable, up-to-date, -and follow industry best-practices. They provide a strong foundation for -developing applications. - -{{< grid >}} diff --git a/content/manuals/trusted-content/images/doi-icon.svg b/content/manuals/trusted-content/images/doi-icon.svg deleted file mode 100644 index ccba28f803b..00000000000 --- a/content/manuals/trusted-content/images/doi-icon.svg +++ /dev/null @@ -1,2 +0,0 @@ - - \ No newline at end of file diff --git a/content/manuals/trusted-content/images/dsos-icon.svg b/content/manuals/trusted-content/images/dsos-icon.svg deleted file mode 100644 index f62ff75981a..00000000000 --- a/content/manuals/trusted-content/images/dsos-icon.svg +++ /dev/null @@ -1,2 +0,0 @@ - - \ No newline at end of file diff --git a/content/manuals/trusted-content/images/dvp-icon.svg b/content/manuals/trusted-content/images/dvp-icon.svg deleted file mode 100644 index 17acbd49976..00000000000 --- a/content/manuals/trusted-content/images/dvp-icon.svg +++ /dev/null @@ -1,2 +0,0 @@ - - \ No newline at end of file diff --git a/content/manuals/trusted-content/images/insights-and-analytics-tab.png b/content/manuals/trusted-content/images/insights-and-analytics-tab.png deleted file mode 100644 index a1f52fc832e..00000000000 Binary files a/content/manuals/trusted-content/images/insights-and-analytics-tab.png and /dev/null differ diff --git a/content/manuals/trusted-content/official-images/_index.md b/content/manuals/trusted-content/official-images/_index.md deleted file mode 100644 index c9b05edf0d2..00000000000 --- a/content/manuals/trusted-content/official-images/_index.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -description: Get an overview on Docker Official Images, what they are, and how they differ from other images available on Docker Hub -keywords: Docker, docker, registry, accounts, plans, Dockerfile, Docker Hub, docs, - official,image, documentation -title: Docker Official Images -aliases: -- /docker-hub/official_repos/ -- /docker-hub/official_images/ ---- - -The [Docker Official Images](https://hub.docker.com/search?q=&type=image&image_filter=official) -are a curated set of Docker repositories hosted on Docker Hub. - -> [!NOTE] -> -> Use of Docker Official Images is subject to [Docker's Terms of Service](https://www.docker.com/legal/docker-terms-service/). - -These images provide essential base repositories that serve as the starting -point for the majority of users. - -These include operating systems such as -[Ubuntu](https://hub.docker.com/_/ubuntu/) and -[Alpine](https://hub.docker.com/_/alpine/), programming language runtimes such as -[Python](https://hub.docker.com/_/python) and -[Node](https://hub.docker.com/_/node), and other essential tools such as -[memcached](https://hub.docker.com/_/memcached) and -[MySQL](https://hub.docker.com/_/mysql). - -The images are some of the [most secure images](https://www.docker.com/blog/enhancing-security-and-transparency-with-docker-official-images/) -on Docker Hub. This is particularly important as Docker Official Images are -some of the most popular on Docker Hub. Typically, Docker Official images have -few or no packages containing CVEs. - -The images exemplify [`Dockerfile` best practices](/manuals/build/building/best-practices.md) -and provide clear documentation to serve as a reference for other `Dockerfile` authors. - -Images that are part of this program have a special badge on Docker Hub making -it easier for you to identify projects that are part of Docker Official Images. - -![Docker official image badge](../images/official-image-badge-iso.png) - -## In this section - -{{% sectionlinks %}} diff --git a/content/reference/api/engine/_index.md b/content/reference/api/engine/_index.md index 674924a3ea2..2511ce1ba3c 100644 --- a/content/reference/api/engine/_index.md +++ b/content/reference/api/engine/_index.md @@ -40,7 +40,7 @@ The Docker Engine API is a RESTful API accessed by an HTTP client such as `wget` ## View the API reference You can -[view the reference for the latest version of the API](latest/index.html) +[view the reference for the latest version of the API](/reference/api/engine/version/v{{% param latest_engine_api_version %}}.md) or [choose a specific version](/reference/api/engine/version-history/). ## Versioned API and SDK @@ -73,21 +73,21 @@ To see the highest version of the API your Docker daemon and client support, use ```console $ docker version Client: Docker Engine - Community - Version: 27.1.2 - API version: 1.46 - Go version: go1.21.13 - Git commit: d01f264 - Built: Mon Aug 12 11:51:13 2024 + Version: 27.4.0 + API version: 1.47 + Go version: go1.22.10 + Git commit: bde2b89 + Built: Sat Dec 7 10:38:33 2024 OS/Arch: linux/amd64 Context: default Server: Docker Engine - Community Engine: - Version: 27.1.2 - API version: 1.46 (minimum version 1.24) - Go version: go1.21.13 - Git commit: f9522e5 - Built: Mon Aug 12 11:51:13 2024 + Version: 27.4.0 + API version: 1.47 (minimum version 1.24) + Go version: go1.22.10 + Git commit: 92a8393 + Built: Sat Dec 7 10:38:33 2024 OS/Arch: linux/amd64 Experimental: false ... @@ -99,15 +99,21 @@ You can specify the API version to use in any of the following ways: that incorporates the API version with the features you need. - When using `curl` directly, specify the version as the first part of the URL. For instance, if the endpoint is `/containers/` you can use - `/v1.46/containers/`. + `/v{{% param "latest_engine_api_version" %}}/containers/`. - To force the Docker CLI or the Docker Engine SDKs to use an older version of the API than the version reported by `docker version`, set the environment variable `DOCKER_API_VERSION` to the correct version. This works on Linux, Windows, or macOS clients. + {{% apiVersionPrevious.inline %}} + {{- $version := site.Params.latest_engine_api_version }} + {{- $parts := strings.Split $version "." }} + {{- $major := cast.ToInt (index $parts 0) }} + {{- $minor := cast.ToInt (index $parts 1) }} ```console - $ DOCKER_API_VERSION='1.44' + $ DOCKER_API_VERSION={{ $major }}.{{ math.Sub $minor 1 }} ``` + {{% /apiVersionPrevious.inline %}} While the environment variable is set, that version of the API is used, even if the Docker daemon supports a newer version. This environment variable @@ -127,6 +133,8 @@ You can specify the API version to use in any of the following ways: | Docker version | Maximum API version | Change log | |:---------------|:---------------------------|:-----------------------------------------------------------------------------| +| 27.4 | [1.47](/reference/api/engine/version/v1.47/) | [changes](/reference/api/engine/version-history/#v147-api-changes) | +| 27.3 | [1.47](/reference/api/engine/version/v1.47/) | [changes](/reference/api/engine/version-history/#v147-api-changes) | | 27.2 | [1.47](/reference/api/engine/version/v1.47/) | [changes](/reference/api/engine/version-history/#v147-api-changes) | | 27.1 | [1.46](/reference/api/engine/version/v1.46/) | [changes](/reference/api/engine/version-history/#v146-api-changes) | | 27.0 | [1.46](/reference/api/engine/version/v1.46/) | [changes](/reference/api/engine/version-history/#v146-api-changes) | diff --git a/content/reference/api/extensions-sdk/DockerDesktopClient.md b/content/reference/api/extensions-sdk/DockerDesktopClient.md index e263710fdbd..9ab538f8f2f 100644 --- a/content/reference/api/extensions-sdk/DockerDesktopClient.md +++ b/content/reference/api/extensions-sdk/DockerDesktopClient.md @@ -21,7 +21,7 @@ The `window.ddClient.backend` object can be used to communicate with the backend the extension metadata. The client is already connected to the backend. ->**Warning** +> [!WARNING] > > It will be removed in a future version. Use [extension](DockerDesktopClient.md#extension) instead. @@ -88,7 +88,7 @@ You can use the option `{"all": true}` to list all the running and stopped conta const containers = await window.ddClient.listContainers(); ``` ->**Warning** +> [!WARNING] > > It will be removed in a future version. Use [listContainers](Docker.md#listcontainers) instead. @@ -121,7 +121,7 @@ const images = await window.ddClient.listImages(); ``` > [!WARNING] -> +> > It will be removed in a future version. Use [listImages](Docker.md#listimages) instead. #### Parameters @@ -152,7 +152,7 @@ window.ddClient.navigateToContainers(); ``` > [!WARNING] -> +> > It will be removed in a future version. Use [viewContainers](NavigationIntents.md#viewcontainers) instead. #### Returns @@ -269,7 +269,7 @@ await window.ddClient.navigateToContainerStats(id); ``` > [!WARNING] -> +> > It will be removed in a future version. #### Parameters @@ -412,7 +412,7 @@ window.ddClient.navigateToDevEnvironments(); ``` > [!WARNING] -> +> > It will be removed in a future version. Use [viewDevEnvironments](NavigationIntents.md#viewdevenvironments) instead. #### Returns @@ -440,7 +440,7 @@ window.ddClient.execHostCmd(`cliShippedOnHost xxx`).then((cmdResult: any) => { ``` > [!WARNING] -> +> > It will be removed in a future version. Use [exec](ExtensionCli.md#exec) instead. #### Parameters @@ -590,7 +590,7 @@ Opens an external URL with the system default browser. window.ddClient.openExternal("https://docker.com"); ``` -**Warning** +> [!WARNING] > > It will be removed in a future version. Use [openExternal](Host.md#openexternal) instead. @@ -682,7 +682,7 @@ Display a toast message of type error. window.ddClient.toastError("message"); ``` ->**Warning** +> [!WARNING] > > It will be removed in a future version. Use [error](Toast.md#error) instead. diff --git a/content/reference/api/hub/dvp.yaml b/content/reference/api/hub/dvp.yaml index 3b9becb0418..8ff2030acab 100644 --- a/content/reference/api/hub/dvp.yaml +++ b/content/reference/api/hub/dvp.yaml @@ -561,6 +561,8 @@ components: properties: data: type: array + description: | + List of urls to download the data. When the data is large, the data will be split into multiple files. items: $ref: '#/components/schemas/ResponseDataFile' ResponseDataFile: diff --git a/content/reference/api/hub/latest.yaml b/content/reference/api/hub/latest.yaml index 702a7f2532f..7d0099ab8a6 100644 --- a/content/reference/api/hub/latest.yaml +++ b/content/reference/api/hub/latest.yaml @@ -6,112 +6,104 @@ info: url: https://docs.docker.com/assets/images/logo-docker-main.png href: /reference description: | - Docker Hub is a service provided by Docker for finding and sharing container - images with your team. + Docker Hub is a service provided by Docker for finding and sharing container images with your team. It is the world's largest library and community for container images. - In addition to the [Docker Hub UI](https://docs.docker.com/docker-hub/) and [Docker Hub CLI tool](https://github.com/docker/hub-tool#readme) (currently experimental), - - Docker provides an API that allows you to interact with Docker Hub. + In addition to the [Docker Hub UI](https://docs.docker.com/docker-hub/) and [Docker Hub CLI tool](https://github.com/docker/hub-tool#readme) (currently experimental), Docker provides an API that allows you to interact with Docker Hub. Browse through the Docker Hub API documentation to explore the supported endpoints. - +servers: + - description: Docker HUB API + x-audience: public + url: https://hub.docker.com tags: - name: resources x-displayName: Resources description: | The following resources are available to interact with the documented API: - - - Docker Hub CLI tool (currently experimental) + - [Docker Hub CLI tool](https://github.com/docker/hub-tool#readme) (currently experimental) - name: rate-limiting x-displayName: Rate Limiting description: | The Docker Hub API is limited on the amount of requests you can perform per minute against it. - If you haven't hit the limit, each request to the API will return the - - following headers in the response. + If you haven't hit the limit, each request to the API will return the following headers in the response. - `X-RateLimit-Limit` - The limit of requests per minute. - `X-RateLimit-Remaining` - The remaining amount of calls within the limit period. - `X-RateLimit-Reset` - The unix timestamp of when the remaining resets. - If you have hit the limit, you will receive a response status of `429` and the `X-Retry-After` - header in the response. + If you have hit the limit, you will receive a response status of `429` and the `X-Retry-After` header in the response. The `X-Retry-After` header is a unix timestamp of when you can call the API again. - **Note**: These rate limits are separate from anti-abuse and Docker Hub - - download, or pull rate limiting. To learn more about Docker Hub pull rate - - limiting, see [Docker Hub download rate limit](https://docs.docker.com/docker-hub/download-rate-limit/). + **Note**: These rate limits are separate from anti-abuse and Docker Hub download, or pull rate limiting. + To learn more about Docker Hub pull rate limiting, see [Docker Hub download rate limit](https://docs.docker.com/docker-hub/download-rate-limit/). - name: authentication x-displayName: Authentication description: | - Most Docker Hub API endpoints require you to authenticate using your - Docker credentials before using them. + Most Docker Hub API endpoints require you to authenticate using your Docker credentials before using them. - Additionally, similar to the Docker Hub UI features, API endpoint responses may vary depending - on your plan (Personal, Pro, or Team) and your account's permissions. + Additionally, similar to the Docker Hub UI features, API endpoint responses may vary depending on your plan (Personal, Pro, or Team) and your account's permissions. To learn more about the features available in each plan and to upgrade your existing plan, see [Docker Pricing](https://www.docker.com/pricing). - name: access-tokens x-displayName: Personal Access Tokens description: | - The Personal Access Token endpoints lets you manage personal access tokens. For more - information, see [Access Tokens](https://docs.docker.com/security/for-developers/access-tokens/). + The Personal Access Token endpoints lets you manage personal access tokens. For more information, see [Access Tokens](https://docs.docker.com/security/for-developers/access-tokens/). - You can use a personal access token instead of a password in the [Docker CLI](https://docs.docker.com/engine/reference/commandline/cli/) - or in the [Create an authentication token](#operation/PostUsersLogin) route to obtain a bearer - token. + You can use a personal access token instead of a password in the [Docker CLI](https://docs.docker.com/engine/reference/commandline/cli/) or in the [Create an authentication token](#operation/PostUsersLogin) route to obtain a bearer token. ### Scopes - For each scope grouping (in this case "repo"), you only need to define 1 scope as any lower - scopes are assumed. For example: If you define `repo:write`, the API assumes the scope of both - `repo:read` *and* `repo:public_read` as well. If you were to define both `repo:write` *and* - `repo:read`, then `repo:read` is assumed by `repo:write` and ignored. + For each scope grouping (in this case "repo"), you only need to define 1 scope as any lower scopes are assumed. + For example: If you define `repo:write`, the API assumes the scope of both `repo:read` *and* `repo:public_read` as well. + If you were to define both `repo:write` *and* `repo:read`, then `repo:read` is assumed by `repo:write` and ignored. - ***Treat your personal access token like your password and keep it secret. You cannot retrieve - your token after it is generated.*** + ***Treat your personal access token like your password and keep it secret. You cannot retrieve your token after it is generated.*** - name: audit-logs x-displayName: Audit Logs description: | - The Audit Logs API endpoints allow you to query audit log events across a - namespace. + The Audit Logs API endpoints allow you to query audit log events across a namespace. For more information, see [Audit Log](https://docs.docker.com/admin/organization/activity-logs/). - name: org-settings x-displayName: Org Settings description: | - The Org Settings API endpoints allow you to manage your organization's - settings. + The Org Settings API endpoints allow you to manage your organization's settings. - name: repositories x-displayName: Repositories description: | - The repository endpoints allow you to access your repository's - tags. + The repository endpoints allow you to access your repository's tags. + - name: orgs + x-displayName: Organizations + x-audience: public + description: | + The organization endpoints allow you to interact with and manage your organizations. + + For more information, see [Organization administration overview](https://docs.docker.com/admin/organization/). + - name: groups + x-displayName: Groups (Teams) + x-audience: public + description: | + The groups endpoints allow you to manage your organization's teams and their members. + + For more information, seee [Create and manage a team](https://docs.docker.com/admin/organization/manage-a-team/). + - name: invites + x-displayName: Invites + x-audience: public + description: | + The invites endpoints allow you to manage invites for users to join your Docker organization. + + For more information, see [Invite members](https://docs.docker.com/admin/organization/members/#invite-members). - name: scim x-displayName: SCIM + x-audience: public description: | SCIM is a provisioning system that lets you manage users within your identity provider (IdP). + For more information, see [System for Cross-domain Identity management](https://docs.docker.com/security/for-admins/provisioning/scim/). -x-tagGroups: - - name: General - tags: - - resources - - rate-limiting - - name: API - tags: - - authentication - - access-tokens - - images - - audit-logs - - org-settings - - repositories - - scim paths: /v2/users/login: post: @@ -120,36 +112,33 @@ paths: summary: Create an authentication token operationId: PostUsersLogin description: | - Creates and returns a bearer token in JWT format that you can use to - authenticate with Docker Hub APIs. + Creates and returns a bearer token in JWT format that you can use to authenticate with Docker Hub APIs. The returned token is used in the HTTP Authorization header like `Authorization: Bearer {TOKEN}`. - Most Docker Hub APIs require this token either to consume or to get detailed information. For example, to list - images in a private repository. - - _**As of Monday, September 16, 2024, this route requires a PAT instead of a password if your organization has - SSO enforced.**_ + Most Docker Hub APIs require this token either to consume or to get detailed information. For example, to list images in a private repository. + + _**As of September 16, 2024, this route requires a PAT instead of a password if your organization has SSO enforced.**_ requestBody: content: application/json: schema: - $ref: "#/components/schemas/UsersLoginRequest" + $ref: '#/components/schemas/UsersLoginRequest' description: Login details. required: true responses: - 200: + '200': description: Authentication successful content: application/json: schema: - $ref: "#/components/schemas/PostUsersLoginSuccessResponse" - 401: + $ref: '#/components/schemas/PostUsersLoginSuccessResponse' + '401': description: Authentication failed or second factor required content: application/json: schema: - $ref: "#/components/schemas/PostUsersLoginErrorResponse" + $ref: '#/components/schemas/PostUsersLoginErrorResponse' /v2/users/2fa-login: post: tags: @@ -157,8 +146,7 @@ paths: summary: Second factor authentication operationId: PostUsers2FALogin description: | - When a user has two-factor authentication (2FA) enabled, this is the second call to perform after - `/v2/users/login` call. + When a user has two-factor authentication (2FA) enabled, this is the second call to perform after `/v2/users/login` call. Creates and returns a bearer token in JWT format that you can use to authenticate with Docker Hub APIs. @@ -169,22 +157,22 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/Users2FALoginRequest" + $ref: '#/components/schemas/Users2FALoginRequest' description: Login details. required: true responses: - 200: + '200': description: Authentication successful content: application/json: schema: - $ref: "#/components/schemas/PostUsersLoginSuccessResponse" - 401: + $ref: '#/components/schemas/PostUsersLoginSuccessResponse' + '401': description: Authentication failed or second factor required content: application/json: schema: - $ref: "#/components/schemas/PostUsers2FALoginErrorResponse" + $ref: '#/components/schemas/PostUsers2FALoginErrorResponse' /v2/access-tokens: post: summary: Create a personal access token @@ -195,19 +183,19 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/createAccessTokenRequest" + $ref: '#/components/schemas/createAccessTokenRequest' required: true responses: - 201: + '201': description: Created content: application/json: schema: - $ref: "#/components/schemas/createAccessTokensResponse" - 400: - $ref: "#/components/responses/BadRequest" - 401: - $ref: "#/components/responses/Unauthorized" + $ref: '#/components/schemas/createAccessTokensResponse' + '400': + $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/Unauthorized' get: summary: Get a list of personal access tokens description: Returns a paginated list of personal access tokens. @@ -225,16 +213,16 @@ paths: type: number default: 10 responses: - 200: + '200': description: OK content: application/json: schema: - $ref: "#/components/schemas/getAccessTokensResponse" - 400: - $ref: "#/components/responses/BadRequest" - 401: - $ref: "#/components/responses/Unauthorized" + $ref: '#/components/schemas/getAccessTokensResponse' + '400': + $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/Unauthorized' /v2/access-tokens/{uuid}: parameters: - in: path @@ -245,49 +233,48 @@ paths: patch: summary: Update a personal access token description: | - Updates a personal access token partially. You can either update the - token's label or enable/disable it. + Updates a personal access token partially. You can either update the token's label or enable/disable it. tags: - access-tokens requestBody: content: application/json: schema: - $ref: "#/components/schemas/patchAccessTokenRequest" + $ref: '#/components/schemas/patchAccessTokenRequest' required: true responses: - 200: + '200': description: OK content: application/json: schema: - $ref: "#/components/schemas/patchAccessTokenResponse" - 400: - $ref: "#/components/responses/BadRequest" - 401: - $ref: "#/components/responses/Unauthorized" + $ref: '#/components/schemas/patchAccessTokenResponse' + '400': + $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/Unauthorized' get: summary: Get a personal access token description: Returns a personal access token by UUID. tags: - access-tokens responses: - 200: + '200': description: OK content: application/json: schema: allOf: - - $ref: "#/components/schemas/accessToken" + - $ref: '#/components/schemas/accessToken' - type: object properties: token: type: string - example: "" - 401: - $ref: "#/components/responses/Unauthorized" - 404: - $ref: "#/components/responses/NotFound" + example: '' + '401': + $ref: '#/components/responses/Unauthorized' + '404': + $ref: '#/components/responses/NotFound' delete: summary: Delete a personal access token description: | @@ -295,24 +282,24 @@ paths: tags: - access-tokens responses: - 204: + '204': description: A successful response. - 401: - $ref: "#/components/responses/Unauthorized" - 404: - $ref: "#/components/responses/NotFound" + '401': + $ref: '#/components/responses/Unauthorized' + '404': + $ref: '#/components/responses/NotFound' /v2/auditlogs/{account}: get: summary: Returns list of audit log events description: Get audit log events for a given namespace. operationId: AuditLogs_GetAuditLogs responses: - 200: + '200': description: A successful response. content: application/json: schema: - $ref: "#/components/schemas/GetAuditLogsResponse" + $ref: '#/components/schemas/GetAuditLogsResponse' examples: response: value: @@ -324,12 +311,11 @@ paths: data: digest: sha256:c1ae9c435032a276f80220c7d9b40f76266bbe79243d34f9cda30b76fe114dfa tag: latest - timestamp: 2021-02-19T01:34:35Z - action_description: - pushed the tag latest with the digest - sha256:c1ae9c435032a to the repository docker/example - 429: - description: "" + timestamp: '2021-02-19T01:34:35Z' + action_description: | + pushed the tag latest with the digest sha256:c1ae9c435032a to the repository docker/example + '429': + description: '' content: application/json: schema: {} @@ -338,8 +324,8 @@ paths: value: detail: Rate limit exceeded error: false - 500: - description: "" + '500': + description: '' content: application/json: schema: {} @@ -348,7 +334,7 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/rpcStatus" + $ref: '#/components/schemas/rpcStatus' parameters: - name: account description: Namespace to query audit logs for. @@ -357,27 +343,22 @@ paths: schema: type: string - name: action - description: - action name one of ["repo.tag.push", ...]. Optional parameter to - filter specific audit log actions. + description: | + action name one of ["repo.tag.push", ...]. Optional parameter to filter specific audit log actions. in: query required: false schema: type: string - name: name - description: - name. Optional parameter to filter audit log events to a specific - name. For repository events, this is the name of the repository. For - organization events, this is the name of the organization. For team - member events, this is the username of the team member. + description: | + name. Optional parameter to filter audit log events to a specific name. For repository events, this is the name of the repository. For organization events, this is the name of the organization. For team member events, this is the username of the team member. in: query required: false schema: type: string - name: actor - description: - actor name. Optional parameter to filter audit log events to the - specific user who triggered the event. + description: | + actor name. Optional parameter to filter audit log events to the specific user who triggered the event. in: query required: false schema: @@ -417,17 +398,16 @@ paths: /v2/auditlogs/{account}/actions: get: summary: Returns list of audit log actions - description: - Get audit log actions for a namespace to be used as a filter for - querying audit events. + description: | + Get audit log actions for a namespace to be used as a filter for querying audit events. operationId: AuditLogs_GetAuditActions responses: - 200: + '200': description: A successful response. content: application/json: schema: - $ref: "#/components/schemas/GetAuditActionsResponse" + $ref: '#/components/schemas/GetAuditActionsResponse' examples: response: value: @@ -474,8 +454,8 @@ paths: description: contains image tag delete events label: Tag Deleted label: Repository - 429: - description: "" + '429': + description: '' content: application/json: schema: {} @@ -484,8 +464,8 @@ paths: value: detail: Rate limit exceeded error: false - 500: - description: "" + '500': + description: '' content: application/json: schema: {} @@ -494,7 +474,7 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/rpcStatus" + $ref: '#/components/schemas/rpcStatus' parameters: - name: account description: Namespace to query audit log actions for. @@ -519,23 +499,22 @@ paths: tags: - org-settings responses: - 200: + '200': description: OK content: application/json: schema: - $ref: "#/components/schemas/orgSettings" - 401: - $ref: "#/components/responses/Unauthorized" - 403: - $ref: "#/components/responses/Forbidden" - 404: - $ref: "#/components/responses/NotFound" + $ref: '#/components/schemas/orgSettings' + '401': + $ref: '#/components/responses/Unauthorized' + '403': + $ref: '#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/NotFound' put: summary: Update organization settings description: | - Updates an organization's settings. Some settings are only used when the - organization is on a business plan. + Updates an organization's settings. Some settings are only used when the organization is on a business plan. ***Only users with administrative privileges for the organization (owner role) can modify these settings.*** @@ -552,7 +531,7 @@ paths: properties: restricted_images: allOf: - - $ref: "#/components/schemas/restricted_images" + - $ref: '#/components/schemas/restricted_images' - type: object required: - enabled @@ -560,194 +539,713 @@ paths: - allow_verified_publishers required: true responses: - 200: + '200': description: OK content: application/json: schema: - $ref: "#/components/schemas/orgSettings" - 401: - $ref: "#/components/responses/Unauthorized" - 403: - $ref: "#/components/responses/Forbidden" - 404: - $ref: "#/components/responses/NotFound" - - + $ref: '#/components/schemas/orgSettings' + '401': + $ref: '#/components/responses/Unauthorized' + '403': + $ref: '#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/NotFound' /v2/namespaces/{namespace}/repositories/{repository}/tags: parameters: - - $ref: "#/components/parameters/namespace" - - $ref: "#/components/parameters/repository" + - $ref: '#/components/parameters/namespace' + - $ref: '#/components/parameters/repository' get: - summary: "List repository tags" - tags: [ repositories ] + summary: List repository tags + tags: + - repositories parameters: - - $ref: "#/components/parameters/page" - - $ref: "#/components/parameters/page_size" + - in: query + name: page + required: false + schema: + type: integer + description: Page number to get. Defaults to 1. + - in: query + name: page_size + required: false + schema: + type: integer + description: Number of items to get per page. Defaults to 10. Max of 100. responses: - 200: - $ref: "#/components/responses/list_tags" - 403: - $ref: "#/components/responses/Forbidden" - 404: - $ref: "#/components/responses/NotFound" + '200': + $ref: '#/components/responses/list_tags' + '403': + $ref: '#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/NotFound' head: - summary: "Check repository tags" - tags: [ repositories ] + summary: Check repository tags + tags: + - repositories responses: - 200: - description: "Repository contains tags" - 403: - $ref: "#/components/responses/Forbidden" - 404: - $ref: "#/components/responses/NotFound" - + '200': + description: Repository contains tags + '403': + $ref: '#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/NotFound' /v2/namespaces/{namespace}/repositories/{repository}/tags/{tag}: parameters: - - $ref: "#/components/parameters/namespace" - - $ref: "#/components/parameters/repository" - - $ref: "#/components/parameters/tag" + - $ref: '#/components/parameters/namespace' + - $ref: '#/components/parameters/repository' + - $ref: '#/components/parameters/tag' get: - summary: "Read repository tag" - tags: [ repositories ] + summary: Read repository tag + tags: + - repositories responses: - 200: - $ref: "#/components/responses/get_tag" - 403: - $ref: "#/components/responses/Forbidden" - 404: - $ref: "#/components/responses/NotFound" + '200': + $ref: '#/components/responses/get_tag' + '403': + $ref: '#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/NotFound' head: - summary: "Check repository tag" - tags: [ repositories ] + summary: Check repository tag + tags: + - repositories responses: - 200: - description: "Repository tag exists" - 403: - $ref: "#/components/responses/Forbidden" - 404: - $ref: "#/components/responses/NotFound" - - + '200': + description: Repository tag exists + '403': + $ref: '#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/NotFound' + /v2/orgs/{org_name}/members: + x-audience: public + parameters: + - $ref: '#/components/parameters/org_name' + - $ref: '#/components/parameters/search' + - $ref: '#/components/parameters/page' + - $ref: '#/components/parameters/page_size' + - $ref: '#/components/parameters/invites' + - $ref: '#/components/parameters/type' + - $ref: '#/components/parameters/role' + get: + summary: List org members + description: | + Returns a list of members for an organization" + tags: + - orgs + responses: + '200': + description: List of members + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/org_member_paginated' + '400': + $ref: '#/components/responses/bad_request' + '401': + $ref: '#/components/responses/unauthorized' + '403': + $ref: '#/components/responses/forbidden' + '404': + $ref: '#/components/responses/not_found' + /v2/orgs/{org_name}/members/export: + x-audience: public + parameters: + - $ref: '#/components/parameters/org_name' + get: + summary: Export org members CSV + description: | + Export members of an organization as a CSV + tags: + - orgs + responses: + '200': + description: Exported members + content: + text/csv: + schema: + type: array + items: + type: object + required: + - Name + - Username + - Email + - Type + - Role + - Date Joined + properties: + Name: + type: string + description: First and last name of the member + Username: + type: string + description: Username of the member + Email: + type: string + description: Email address of the member + Type: + type: string + description: Type of the member + enum: + - Invitee + - User + Permission: + type: string + description: Permission of the member + enum: + - Owner + - Member + Teams: + type: string + description: Comma-separated list of teams the member is part of + example: team-1, team-2 + Date Joined: + type: string + description: Date the member joined the organization + example: 2020-01-01 15:00:51.193355 +0000 UTC + headers: + Content-Disposition: + schema: + type: string + example: attachment;filename="{org_name}-members-{timestamp}.csv" + '400': + $ref: '#/components/responses/bad_request' + '401': + $ref: '#/components/responses/unauthorized' + '403': + $ref: '#/components/responses/forbidden' + '404': + $ref: '#/components/responses/not_found' + /v2/orgs/{org_name}/members/{username}: + x-audience: public + parameters: + - $ref: '#/components/parameters/org_name' + - $ref: '#/components/parameters/username' + put: + summary: Update org member (role) + description: | + Updates the role of a member in the organization. + ***Only users in the "owners" group of the organization can use this endpoint.*** + tags: + - orgs + requestBody: + required: true + content: + application/json: + schema: + required: + - role + properties: + role: + type: string + description: Role of the member + enum: + - owner + - editor + - member + responses: + '200': + description: Member role updated + content: + application/json: + schema: + $ref: '#/components/schemas/org_member' + '400': + $ref: '#/components/responses/bad_request' + '401': + $ref: '#/components/responses/unauthorized' + '403': + $ref: '#/components/responses/forbidden' + '404': + $ref: '#/components/responses/not_found' + delete: + summary: Remove member from org + description: | + Removes the member from the org, ie. all groups in the org, unless they're the last owner + tags: + - orgs + responses: + '204': + description: Member removed successfully + '400': + $ref: '#/components/responses/bad_request' + '401': + $ref: '#/components/responses/unauthorized' + '403': + $ref: '#/components/responses/forbidden' + '404': + $ref: '#/components/responses/not_found' + /v2/orgs/{org_name}/invites: + x-audience: public + parameters: + - $ref: '#/components/parameters/org_name' + get: + summary: List org invites + description: | + Return all pending invites for a given org, only team owners can call this endpoint + tags: + - invites + responses: + '200': + description: '' + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/invite' + '401': + $ref: '#/components/responses/unauthorized' + '403': + $ref: '#/components/responses/forbidden' + '404': + $ref: '#/components/responses/not_found' + /v2/orgs/{org_name}/groups: + x-audience: public + parameters: + - $ref: '#/components/parameters/org_name' + get: + summary: Get groups of an organization + tags: + - groups + parameters: + - $ref: '#/components/parameters/page' + - $ref: '#/components/parameters/page_size' + - in: query + name: username + schema: + type: string + description: Get groups for the specified username in the organization. + - in: query + name: search + schema: + type: string + description: Get groups for the specified group in the organization. + responses: + '200': + description: '' + content: + application/json: + schema: + properties: + count: + type: number + example: 1 + next: + type: string + example: null + previous: + type: string + example: null + results: + type: array + items: + $ref: '#/components/schemas/org_group' + '401': + $ref: '#/components/responses/unauthorized' + '403': + $ref: '#/components/responses/forbidden' + '404': + $ref: '#/components/responses/not_found' + post: + summary: Create a new group + description: Create a new group within an organization. + tags: + - groups + requestBody: + content: + application/json: + schema: + required: + - name + properties: + name: + type: string + description: + type: string + responses: + '201': + description: Group created successfully + content: + application/json: + schema: + $ref: '#/components/schemas/org_group' + '400': + $ref: '#/components/responses/bad_request' + '401': + $ref: '#/components/responses/unauthorized' + '403': + $ref: '#/components/responses/forbidden' + /v2/orgs/{org_name}/groups/{group_name}: + x-audience: public + parameters: + - $ref: '#/components/parameters/org_name' + - $ref: '#/components/parameters/group_name' + get: + summary: Get a group of an organization + tags: + - groups + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/org_group' + '401': + $ref: '#/components/responses/unauthorized' + '403': + $ref: '#/components/responses/forbidden' + '404': + $ref: '#/components/responses/not_found' + put: + summary: Update the details for an organization group + tags: + - groups + requestBody: + content: + application/json: + schema: + required: + - name + properties: + name: + type: string + description: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/org_group' + '401': + $ref: '#/components/responses/unauthorized' + '403': + $ref: '#/components/responses/forbidden' + '404': + $ref: '#/components/responses/not_found' + patch: + summary: Update some details for an organization group + tags: + - groups + requestBody: + content: + application/json: + schema: + properties: + name: + type: string + description: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/org_group' + '401': + $ref: '#/components/responses/unauthorized' + '403': + $ref: '#/components/responses/forbidden' + '404': + $ref: '#/components/responses/not_found' + delete: + summary: Delete an organization group + tags: + - groups + responses: + '204': + description: Group deleted successfully + '401': + $ref: '#/components/responses/unauthorized' + '403': + $ref: '#/components/responses/forbidden' + '404': + $ref: '#/components/responses/not_found' + /v2/orgs/{org_name}/groups/{group_name}/members: + x-audience: public + get: + parameters: + - $ref: '#/components/parameters/org_name' + - $ref: '#/components/parameters/group_name' + - $ref: '#/components/parameters/page' + - $ref: '#/components/parameters/page_size' + - in: query + name: search + schema: + type: string + description: Search members by username, full_name or email. + summary: List members of a group + description: | + List the members (users) that are in a group. + If user is owner of the org or has otherwise elevated permissions, they can search by email and the result will also contain emails. + tags: + - groups + responses: + '200': + description: '' + content: + application/json: + schema: + properties: + count: + type: number + example: 1 + next: + type: string + example: null + previous: + type: string + example: null + results: + type: array + items: + $ref: '#/components/schemas/group_member' + '401': + $ref: '#/components/responses/unauthorized' + '403': + $ref: '#/components/responses/forbidden' + '404': + $ref: '#/components/responses/not_found' + post: + parameters: + - $ref: '#/components/parameters/org_name' + - $ref: '#/components/parameters/group_name' + summary: Adds a member to a group + tags: + - groups + requestBody: + $ref: '#/components/requestBodies/add_member_to_org_group' + responses: + '200': + description: OK + '401': + $ref: '#/components/responses/unauthorized' + '403': + $ref: '#/components/responses/forbidden' + '404': + $ref: '#/components/responses/not_found' + '500': + $ref: '#/components/responses/internal_error' + /v2/orgs/{org_name}/groups/{group_name}/members/{username}: + x-audience: public + parameters: + - $ref: '#/components/parameters/org_name' + - $ref: '#/components/parameters/group_name' + - $ref: '#/components/parameters/username' + delete: + summary: Removes a user from a group + tags: + - groups + responses: + '204': + description: User removed successfully + '401': + $ref: '#/components/responses/unauthorized' + '403': + $ref: '#/components/responses/forbidden' + '404': + $ref: '#/components/responses/not_found' + /v2/invites/{id}: + x-audience: public + parameters: + - in: path + name: id + required: true + schema: + type: string + delete: + summary: Cancel an invite + description: | + Mark the invite as cancelled so it doesn't show up on the list of pending invites + tags: + - invites + responses: + '204': + description: '' + '401': + $ref: '#/components/responses/unauthorized' + '403': + $ref: '#/components/responses/forbidden' + '404': + $ref: '#/components/responses/not_found' + /v2/invites/{id}/resend: + x-audience: public + parameters: + - in: path + name: id + schema: + type: string + required: true + patch: + summary: Resend an invite + description: | + Resend a pending invite to the user, any org owner can resend an invite + tags: + - invites + responses: + '204': + description: '' + '401': + $ref: '#/components/responses/unauthorized' + '403': + $ref: '#/components/responses/forbidden' + '404': + $ref: '#/components/responses/not_found' + /v2/invites/bulk: + x-audience: public + parameters: + - $ref: '#/components/parameters/bulk_invite' + post: + summary: Bulk create invites + description: | + Create multiple invites by emails or DockerIDs. Only a team owner can create invites. + tags: + - invites + requestBody: + $ref: '#/components/requestBodies/bulk_invite_request' + responses: + '202': + description: Accepted + content: + application/json: + schema: + type: object + properties: + invitees: + $ref: '#/components/schemas/bulk_invite' + '400': + $ref: '#/components/responses/bad_request' + '409': + $ref: '#/components/responses/conflict' /v2/scim/2.0/ServiceProviderConfig: + x-audience: public get: summary: Get service provider config description: | Returns a service provider config for Docker's configuration. - tags: [ scim ] + tags: + - scim security: - - bearerSCIMAuth: [ ] + - bearerSCIMAuth: [] responses: - 200: + '200': $ref: '#/components/responses/scim_get_service_provider_config_resp' - 401: - $ref: "#/components/responses/scim_unauthorized" - 500: - $ref: "#/components/responses/scim_error" - + '401': + $ref: '#/components/responses/scim_unauthorized' + '500': + $ref: '#/components/responses/scim_error' /v2/scim/2.0/ResourceTypes: + x-audience: public get: summary: List resource types description: | Returns all resource types supported for the SCIM configuration. - tags: [ scim ] + tags: + - scim security: - - bearerSCIMAuth: [ ] + - bearerSCIMAuth: [] responses: - 200: - $ref: "#/components/responses/scim_get_resource_types_resp" - 401: - $ref: "#/components/responses/scim_unauthorized" - 500: - $ref: "#/components/responses/scim_error" - + '200': + $ref: '#/components/responses/scim_get_resource_types_resp' + '401': + $ref: '#/components/responses/scim_unauthorized' + '500': + $ref: '#/components/responses/scim_error' /v2/scim/2.0/ResourceTypes/{name}: + x-audience: public get: summary: Get a resource type description: | Returns a resource type by name. - tags: [ scim ] + tags: + - scim parameters: - name: name in: path schema: type: string example: User + required: true security: - - bearerSCIMAuth: [ ] + - bearerSCIMAuth: [] responses: - 200: - $ref: "#/components/responses/scim_get_resource_type_resp" - 401: - $ref: "#/components/responses/scim_unauthorized" - 404: - $ref: "#/components/responses/scim_not_found" - 500: - $ref: "#/components/responses/scim_error" - + '200': + $ref: '#/components/responses/scim_get_resource_type_resp' + '401': + $ref: '#/components/responses/scim_unauthorized' + '404': + $ref: '#/components/responses/scim_not_found' + '500': + $ref: '#/components/responses/scim_error' /v2/scim/2.0/Schemas: + x-audience: public get: summary: List schemas description: | Returns all schemas supported for the SCIM configuration. - tags: [ scim ] + tags: + - scim security: - - bearerSCIMAuth: [ ] + - bearerSCIMAuth: [] responses: - 200: - $ref: "#/components/responses/scim_get_schemas_resp" - 401: - $ref: "#/components/responses/scim_unauthorized" - 500: - $ref: "#/components/responses/scim_error" - + '200': + $ref: '#/components/responses/scim_get_schemas_resp' + '401': + $ref: '#/components/responses/scim_unauthorized' + '500': + $ref: '#/components/responses/scim_error' /v2/scim/2.0/Schemas/{id}: + x-audience: public get: summary: Get a schema description: | Returns a schema by ID. - tags: [ scim ] + tags: + - scim parameters: - name: id in: path schema: type: string example: urn:ietf:params:scim:schemas:core:2.0:User + required: true security: - - bearerSCIMAuth: [ ] + - bearerSCIMAuth: [] responses: - 200: - $ref: "#/components/responses/scim_get_schema_resp" - 401: - $ref: "#/components/responses/scim_unauthorized" - 404: - $ref: "#/components/responses/scim_not_found" - 500: - $ref: "#/components/responses/scim_error" - + '200': + $ref: '#/components/responses/scim_get_schema_resp' + '401': + $ref: '#/components/responses/scim_unauthorized' + '404': + $ref: '#/components/responses/scim_not_found' + '500': + $ref: '#/components/responses/scim_error' /v2/scim/2.0/Users: + x-audience: public get: summary: List users description: | - List users, returns paginated users for an organization. Use `startIndex` - and `count` query parameters to receive paginated results. + Returns paginated users for an organization. Use `startIndex` and `count` query parameters to receive paginated results. + + **Sorting:** - **Sorting:**
- Sorting lets you specify the order of returned resources by specifying - a combination of `sortBy` and `sortOrder` query parameters. + Sorting allows you to specify the order in which resources are returned by specifying a combination of `sortBy` and `sortOrder` query parameters. - The `sortBy` parameter specifies the attribute whose value will be used - to order the returned responses. The `sortOrder` parameter defines the - order in which the `sortBy` parameter is applied. Allowed values are - "ascending" and "descending". + The `sortBy` parameter specifies the attribute whose value will be used to order the returned responses. The `sortOrder` parameter defines the order in which the `sortBy` parameter is applied. Allowed values are "ascending" and "descending". - **Filtering:**
- You can request a subset of resources by specifying the `filter` query - parameter containing a filter expression. Attribute names and attribute - operators used in filters are case insensitive. The filter parameter - must contain at least one valid expression. Each expression must contain - an attribute name followed by an attribute operator and an optional - value. + **Filtering:** + + You can request a subset of resources by specifying the `filter` query parameter containing a filter expression. Attribute names and attribute operators used in filters are case insensitive. The filter parameter must contain at least one valid expression. Each expression must contain an attribute name followed by an attribute operator and an optional value. Supported operators are listed below. @@ -759,16 +1257,17 @@ paths: - `or` Logical "or" - `not` "Not" function - `()` Precedence grouping - tags: [ scim ] + tags: + - scim security: - - bearerSCIMAuth: [ ] + - bearerSCIMAuth: [] parameters: - name: startIndex in: query schema: type: integer minimum: 1 - description: "" + description: '' example: 1 - name: count in: query @@ -776,15 +1275,15 @@ paths: type: integer minimum: 1 maximum: 200 - description: "" + description: '' example: 10 - name: filter in: query schema: type: string - description: "" + description: '' example: userName eq "jon.snow@docker.com" - - $ref: "#/components/parameters/scim_attributes" + - $ref: '#/components/parameters/scim_attributes' - name: sortOrder in: query schema: @@ -796,100 +1295,96 @@ paths: in: query schema: type: string - description: "User attribute to sort by." + description: User attribute to sort by. example: userName responses: - 200: - $ref: "#/components/responses/scim_get_users_resp" - 400: - $ref: "#/components/responses/scim_bad_request" - 401: - $ref: "#/components/responses/scim_unauthorized" - 403: - $ref: "#/components/responses/scim_forbidden" - 404: - $ref: "#/components/responses/scim_not_found" - 500: - $ref: "#/components/responses/scim_error" - + '200': + $ref: '#/components/responses/scim_get_users_resp' + '400': + $ref: '#/components/responses/scim_bad_request' + '401': + $ref: '#/components/responses/scim_unauthorized' + '403': + $ref: '#/components/responses/scim_forbidden' + '404': + $ref: '#/components/responses/scim_not_found' + '500': + $ref: '#/components/responses/scim_error' post: summary: Create user description: | - Creates a user. If the user already exists by email, they are assigned - to the organization on the "company" team. - tags: [ scim ] + Creates a user. If the user already exists by email, they are assigned to the organization on the "company" team. + tags: + - scim security: - - bearerSCIMAuth: [ ] + - bearerSCIMAuth: [] requestBody: - $ref: "#/components/requestBodies/scim_create_user_request" + $ref: '#/components/requestBodies/scim_create_user_request' responses: - 201: - $ref: "#/components/responses/scim_create_user_resp" - 400: - $ref: "#/components/responses/scim_bad_request" - 401: - $ref: "#/components/responses/scim_unauthorized" - 403: - $ref: "#/components/responses/scim_forbidden" - 404: - $ref: "#/components/responses/scim_not_found" - 409: - $ref: "#/components/responses/scim_conflict" - 500: - $ref: "#/components/responses/scim_error" - + '201': + $ref: '#/components/responses/scim_create_user_resp' + '400': + $ref: '#/components/responses/scim_bad_request' + '401': + $ref: '#/components/responses/scim_unauthorized' + '403': + $ref: '#/components/responses/scim_forbidden' + '404': + $ref: '#/components/responses/scim_not_found' + '409': + $ref: '#/components/responses/scim_conflict' + '500': + $ref: '#/components/responses/scim_error' /v2/scim/2.0/Users/{id}: + x-audience: public parameters: - - $ref: "#/components/parameters/scim_user_id" + - $ref: '#/components/parameters/scim_user_id' get: summary: Get a user description: | Returns a user by ID. - tags: [ scim ] + tags: + - scim security: - - bearerSCIMAuth: [ ] + - bearerSCIMAuth: [] responses: - 200: - $ref: "#/components/responses/scim_get_user_resp" - 400: - $ref: "#/components/responses/scim_bad_request" - 401: - $ref: "#/components/responses/scim_unauthorized" - 403: - $ref: "#/components/responses/scim_forbidden" - 404: - $ref: "#/components/responses/scim_not_found" - 500: - $ref: "#/components/responses/scim_error" + '200': + $ref: '#/components/responses/scim_get_user_resp' + '400': + $ref: '#/components/responses/scim_bad_request' + '401': + $ref: '#/components/responses/scim_unauthorized' + '403': + $ref: '#/components/responses/scim_forbidden' + '404': + $ref: '#/components/responses/scim_not_found' + '500': + $ref: '#/components/responses/scim_error' put: summary: Update a user description: | - Updates a user. Use this route to change the user's name, activate, - and deactivate the user. - tags: [ scim ] + Updates a user. This route is used to change the user's name, activate, and deactivate the user. + tags: + - scim security: - - bearerSCIMAuth: [ ] + - bearerSCIMAuth: [] requestBody: - $ref: "#/components/requestBodies/scim_update_user_request" + $ref: '#/components/requestBodies/scim_update_user_request' responses: - 200: - $ref: "#/components/responses/scim_update_user_resp" - 400: - $ref: "#/components/responses/scim_bad_request" - 401: - $ref: "#/components/responses/scim_unauthorized" - 403: - $ref: "#/components/responses/scim_forbidden" - 404: - $ref: "#/components/responses/scim_not_found" - 409: - $ref: "#/components/responses/scim_conflict" - 500: - $ref: "#/components/responses/scim_error" - - -servers: - - url: https://hub.docker.com/ + '200': + $ref: '#/components/responses/scim_update_user_resp' + '400': + $ref: '#/components/responses/scim_bad_request' + '401': + $ref: '#/components/responses/scim_unauthorized' + '403': + $ref: '#/components/responses/scim_forbidden' + '404': + $ref: '#/components/responses/scim_not_found' + '409': + $ref: '#/components/responses/scim_conflict' + '500': + $ref: '#/components/responses/scim_error' components: responses: BadRequest: @@ -897,100 +1392,144 @@ components: content: application/json: schema: - $ref: "#/components/schemas/ValueError" + $ref: '#/components/schemas/ValueError' Unauthorized: description: Unauthorized content: application/json: schema: - $ref: "#/components/schemas/Error" + $ref: '#/components/schemas/Error' Forbidden: description: Forbidden content: application/json: schema: - $ref: "#/components/schemas/Error" + $ref: '#/components/schemas/Error' NotFound: description: Not Found content: application/json: schema: - $ref: "#/components/schemas/Error" - + $ref: '#/components/schemas/Error' + list_tags: + description: list repository tags + content: + application/json: + schema: + $ref: '#/components/schemas/paginated_tags' + get_tag: + description: repository tag + content: + application/json: + schema: + $ref: '#/components/schemas/tag' + bad_request: + description: Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/error' + unauthorized: + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/error' + forbidden: + description: Forbidden + content: + application/json: + schema: + $ref: '#/components/schemas/error' + not_found: + description: Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/error' + conflict: + description: Conflict + content: + application/json: + schema: + $ref: '#/components/schemas/error' + internal_error: + description: Internal + content: + application/json: + schema: + $ref: '#/components/schemas/error' scim_bad_request: description: Bad Request content: application/scim+json: schema: allOf: - - $ref: "#/components/schemas/scim_error" + - $ref: '#/components/schemas/scim_error' - properties: status: - example: "400" + example: '400' scimType: type: string - description: Some types of errors will return this per the - specification. + description: Some types of errors will return this per the specification. scim_unauthorized: description: Unauthorized content: application/scim+json: schema: allOf: - - $ref: "#/components/schemas/scim_error" + - $ref: '#/components/schemas/scim_error' - properties: status: - example: "401" + example: '401' scim_forbidden: description: Forbidden content: application/scim+json: schema: allOf: - - $ref: "#/components/schemas/scim_error" + - $ref: '#/components/schemas/scim_error' - properties: status: - example: "403" + example: '403' scim_not_found: description: Not Found content: application/scim+json: schema: allOf: - - $ref: "#/components/schemas/scim_error" + - $ref: '#/components/schemas/scim_error' - properties: status: - example: "404" + example: '404' scim_conflict: description: Conflict content: application/scim+json: schema: allOf: - - $ref: "#/components/schemas/scim_error" + - $ref: '#/components/schemas/scim_error' - properties: status: - example: "409" + example: '409' scim_error: description: Internal Error content: application/scim+json: schema: allOf: - - $ref: "#/components/schemas/scim_error" + - $ref: '#/components/schemas/scim_error' - properties: status: - example: "500" - + example: '500' scim_get_service_provider_config_resp: - description: "" + description: '' content: application/scim+json: schema: - $ref: "#/components/schemas/scim_service_provider_config" - + $ref: '#/components/schemas/scim_service_provider_config' scim_get_resource_types_resp: - description: "" + description: '' content: application/scim+json: schema: @@ -1000,24 +1539,22 @@ components: type: array items: type: string - example: [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ] + example: urn:ietf:params:scim:api:messages:2.0:ListResponse totalResults: type: integer example: 1 resources: type: array items: - $ref: "#/components/schemas/scim_resource_type" - + $ref: '#/components/schemas/scim_resource_type' scim_get_resource_type_resp: - description: "" + description: '' content: application/scim+json: schema: - $ref: "#/components/schemas/scim_resource_type" - + $ref: '#/components/schemas/scim_resource_type' scim_get_schemas_resp: - description: "" + description: '' content: application/scim+json: schema: @@ -1027,24 +1564,22 @@ components: type: array items: type: string - example: [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ] + example: urn:ietf:params:scim:api:messages:2.0:ListResponse totalResults: type: integer example: 1 resources: type: array items: - $ref: "#/components/schemas/scim_schema" - + $ref: '#/components/schemas/scim_schema' scim_get_schema_resp: - description: "" + description: '' content: application/scim+json: schema: - $ref: "#/components/schemas/scim_schema" - + $ref: '#/components/schemas/scim_schema' scim_get_users_resp: - description: "" + description: '' content: application/scim+json: schema: @@ -1054,7 +1589,8 @@ components: type: array items: type: string - example: [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ] + example: + - urn:ietf:params:scim:api:messages:2.0:ListResponse totalResults: type: integer example: 1 @@ -1067,43 +1603,25 @@ components: resources: type: array items: - $ref: "#/components/schemas/scim_user" - + $ref: '#/components/schemas/scim_user' scim_create_user_resp: - description: "" + description: '' content: application/scim+json: schema: - $ref: "#/components/schemas/scim_user" - + $ref: '#/components/schemas/scim_user' scim_get_user_resp: - description: "" + description: '' content: application/scim+json: schema: - $ref: "#/components/schemas/scim_user" - + $ref: '#/components/schemas/scim_user' scim_update_user_resp: - description: "" + description: '' content: application/scim+json: schema: - $ref: "#/components/schemas/scim_user" - - list_tags: - description: "list repository tags" - content: - application/json: - schema: - $ref: "#/components/schemas/paginated_tags" - - get_tag: - description: "repository tag" - content: - application/json: - schema: - $ref: "#/components/schemas/tag" - + $ref: '#/components/schemas/scim_user' schemas: UsersLoginRequest: description: User login details @@ -1117,11 +1635,10 @@ components: type: string example: myusername password: - description: - The password or personal access token (PAT) of the Docker Hub - account to authenticate with. + description: | + The password or personal access token (PAT) of the Docker Hub account to authenticate with. type: string - example: hunter2 + example: p@ssw0rd PostUsersLoginSuccessResponse: description: successful user login response type: object @@ -1129,7 +1646,6 @@ components: token: description: | Created authentication token. - This token can be used in the HTTP Authorization header as a JWT to authenticate with the Docker Hub APIs. type: string example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c @@ -1146,10 +1662,8 @@ components: example: Incorrect authentication credentials nullable: false login_2fa_token: - description: - Short time lived token to be used on `/v2/users/2fa-login` to - complete the authentication. This field is present only if 2FA is - enabled. + description: | + Short time lived token to be used on `/v2/users/2fa-login` to complete the authentication. This field is present only if 2FA is enabled. type: string example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c nullable: true @@ -1165,9 +1679,8 @@ components: type: string example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c code: - description: - The Time-based One-Time Password of the Docker Hub account to - authenticate with. + description: | + The Time-based One-Time Password of the Docker Hub account to authenticate with. type: string example: 123456 PostUsers2FALoginErrorResponse: @@ -1179,369 +1692,6 @@ components: type: string example: Incorrect authentication credentials nullable: false - ErrorInfo: - description: Context information for an error used for diagnostics. - type: object - properties: - api_call_docker_id: - description: ID of docker user. - type: string - api_call_name: - description: Name of the API operation called. - type: string - api_call_start: - description: Date/time of call start. - type: string - api_call_txnid: - description: Unique ID for this call. - type: string - ErrorResponse: - description: Represents an error. - type: object - properties: - txnid: - description: Unique ID for this call. - type: string - message: - description: The error message. - type: string - errinfo: - $ref: "#/components/schemas/ErrorInfo" - ErrorDetail: - description: Error with a detail field. - type: object - properties: - detail: - description: The error message. - type: string - GetNamespaceRepositoryImagesSummaryResponse: - description: Summary information for images in a repository. - type: object - properties: - active_from: - description: - Time from which an image must have been pushed or pulled to be - counted as active. - type: string - example: 2021-01-25T14:25:37.076343059Z - statistics: - type: object - properties: - total: - description: Number of images in this repository. - type: integer - example: 3 - active: - description: Number of images counted as active in this repository. - type: integer - example: 2 - inactive: - description: Number of images counted as inactive in this repository. - type: integer - example: 1 - GetNamespaceRepositoryImagesResponse: - description: Paginated list of images in a repository. - type: object - properties: - count: - description: Total count of images in the repository. - type: integer - example: 100 - next: - description: - Link to the next page with the same query parameters if there are - more images. - type: string - example: https://hub.docker.com/v2/namespaces/mynamespace/repositories/myrepo/images?&page=4&page_size=20 - nullable: true - previous: - description: - Link to the previous page with the same query parameters if not on - first page. - type: string - example: https://hub.docker.com/v2/namespaces/mynamespace/repositories/myrepo/images?&page=2&page_size=20 - nullable: true - results: - type: array - description: Image details. - items: - type: object - properties: - namespace: - description: The repository namespace. - type: string - example: mynamespace - repository: - description: The repository name. - type: string - example: myrepo - digest: - description: The image's digest. - type: string - example: sha256:1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr - tags: - description: The current and historical tags for this image. - type: array - items: - type: object - properties: - tag: - description: The tag. - type: string - example: latest - is_current: - description: | - `true` if the tag currently points to this image. - - `false` if it has been overwritten to point at a different image. - type: boolean - example: true - last_pushed: - description: Time when this image was last pushed. - type: string - example: 2021-02-24T22:05:27.526308Z - nullable: true - last_pulled: - description: - Time when this image was last pulled. Note this is updated at - most once per hour. - type: string - example: 2021-02-24T23:16:10.200008Z - nullable: true - status: - description: - The status of the image based on its last activity against the - `active_from` time. - type: string - enum: - - active - - inactive - example: active - GetNamespaceRepositoryImagesTagsResponse: - description: Paginated list of tags for this repository. - type: object - properties: - count: - description: Total count of tags for this image. - type: integer - example: 100 - next: - description: Link to the next page if there are more tags. - type: string - example: https://hub.docker.com/v2/namespaces/mynamespace/repositories/myrepo/images/sha256:mydigest/tags?&page=4&page_size=20 - nullable: true - previous: - description: Link to the previous page if not on first page. - type: string - example: https://hub.docker.com/v2/namespaces/mynamespace/repositories/myrepo/images/sha256:mydigest/tags?&page=2&page_size=20 - nullable: true - results: - description: The current and historical tags for this image. - type: array - items: - type: object - properties: - tag: - description: The tag. - type: string - example: latest - is_current: - description: | - `true` if the tag currently points to this image. - - `false` if it has been overwritten to point at a different image. - type: boolean - example: true - PostNamespacesDeleteImagesRequest: - description: Delete images request. - type: object - properties: - dry_run: - description: - If `true` then will check and return errors and unignored warnings - for the deletion request but will not delete any images. - type: boolean - example: false - active_from: - description: | - Sets the time from which an image must have been pushed or pulled to - be counted as active. - - Defaults to 1 month before the current time. - type: string - example: 2020-12-01T12:00:00Z - manifests: - description: Image manifests to delete. - type: array - items: - type: object - required: - - repository - - digest - properties: - repository: - description: Name of the repository to delete the image from. - type: string - example: myrepo - digest: - description: Digest of the image to delete. - type: string - example: sha256:1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr - ignore_warnings: - description: | - Warnings to ignore. If a warning is not ignored then no deletions will happen and the - warning is returned in the response. - - These warnings include: - - - is_active: warning when attempting to delete an image that is marked as active. - - current_tag: warning when attempting to delete an image that has one or more current - tags in the repository. - - Warnings can be copied from the response to the request. - type: array - items: - type: object - required: - - repository - - digest - - warning - properties: - repository: - description: Name of the repository of the image to ignore the warning for. - type: string - example: myrepo - digest: - description: Digest of the image to ignore the warning for. - type: string - example: sha256:1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr - warning: - description: Warning to ignore. - type: string - enum: - - is_active - - current_tag - example: current_tag - tags: - description: Current tags to ignore. - type: array - items: - type: string - example: latest - PostNamespacesDeleteImagesResponseSuccess: - description: Successful delete images response. - type: object - properties: - dry_run: - description: Whether the request was a dry run or not. - type: boolean - example: false - metrics: - type: object - properties: - manifest_deletes: - description: Number of manifests deleted. - type: integer - example: 3 - manifest_errors: - description: Number of manifests that failed to delete. - type: integer - example: 0 - tag_deletes: - description: Number of tags deleted. - type: integer - example: 1 - tag_errors: - description: Number of tags that failed to delete. - type: integer - example: 0 - PostNamespacesDeleteImagesResponseError: - description: Deletion not possible. - type: object - properties: - txnid: - description: Unique ID for this call. - type: string - message: - description: The error message. - type: string - errinfo: - allOf: - - $ref: "#/components/schemas/ErrorInfo" - - type: object - properties: - type: - description: Type of error. - type: string - example: validation - details: - type: object - properties: - errors: - description: - Errors from validating delete request. These cannot be - ignored. - type: array - items: - type: object - properties: - repository: - description: - Name of the repository of the image that caused - the error. - type: string - example: myrepo - digest: - description: Digest of the image that caused the error. - type: string - example: sha256:1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr - error: - description: Error type. - type: string - enum: - - not_found - - unauthorized - - child_manifest - example: not_found - warnings: - description: | - Warnings that can be ignored. - - These warnings include: - - - is_active: warning when attempting to delete an image that is marked as - active. - - current_tag: warning when attempting to delete an image that has one or - more current tags in the repository. - - Warnings can be copied from the response to the request. - type: array - items: - type: object - properties: - repository: - description: - Name of the repository of the image that caused - the warning. - type: string - example: myrepo - digest: - description: Digest of the image that caused the warning. - type: string - example: sha256:1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr - warning: - description: Warning type. - type: string - enum: - - is_active - - current_tag - example: current_tag - tags: - description: Current tags if warning is `current_tag`. - type: array - items: - type: string - example: latest protobufAny: type: object properties: @@ -1561,7 +1711,7 @@ components: details: type: array items: - $ref: "#/components/schemas/protobufAny" + $ref: '#/components/schemas/protobufAny' AuditLogAction: type: object properties: @@ -1581,7 +1731,7 @@ components: actions: type: array items: - $ref: "#/components/schemas/AuditLogAction" + $ref: '#/components/schemas/AuditLogAction' description: List of audit log actions. label: type: string @@ -1592,7 +1742,7 @@ components: actions: type: object additionalProperties: - $ref: "#/components/schemas/AuditLogActions" + $ref: '#/components/schemas/AuditLogActions' description: Map of audit log actions. description: GetAuditActions response. GetAuditLogsResponse: @@ -1601,7 +1751,7 @@ components: logs: type: array items: - $ref: "#/components/schemas/AuditLog" + $ref: '#/components/schemas/AuditLog' description: List of audit log events. description: GetAuditLogs response. AuditLog: @@ -1659,7 +1809,7 @@ components: example: some user agent created_at: type: string - example: 2021-07-20T12:00:00.000000Z + example: '2021-07-20T12:00:00.000000Z' last_used: type: string example: null @@ -1703,7 +1853,7 @@ components: items: type: string createAccessTokensResponse: - $ref: "#/components/schemas/accessToken" + $ref: '#/components/schemas/accessToken' getAccessTokensResponse: type: object properties: @@ -1723,12 +1873,12 @@ components: type: array items: allOf: - - $ref: "#/components/schemas/accessToken" + - $ref: '#/components/schemas/accessToken' - type: object properties: token: type: string - example: "" + example: '' patchAccessTokenRequest: type: object properties: @@ -1741,12 +1891,12 @@ components: type: boolean example: false patchAccessTokenResponse: - $ref: "#/components/schemas/accessToken" + $ref: '#/components/schemas/accessToken' orgSettings: type: object properties: restricted_images: - $ref: "#/components/schemas/restricted_images" + $ref: '#/components/schemas/restricted_images' restricted_images: type: object properties: @@ -1767,29 +1917,29 @@ components: properties: digest: type: string - description: "image layer digest" + description: image layer digest nullable: true size: type: integer - description: "size of the layer" + description: size of the layer instruction: type: string - description: "Dockerfile instruction" + description: Dockerfile instruction image: type: object properties: architecture: type: string - description: "CPU architecture" + description: CPU architecture features: type: string - description: "CPU features" + description: CPU features variant: type: string - description: "CPU variant" + description: CPU variant digest: type: string - description: "image digest" + description: image digest nullable: true layers: type: array @@ -1797,80 +1947,83 @@ components: $ref: '#/components/schemas/layer' os: type: string - description: "operating system" + description: operating system os_features: type: string - description: "OS features" + description: OS features os_version: type: string - description: "OS version" + description: OS version size: type: integer - description: "size of the image" + description: size of the image status: type: string - enum: ["active", "inactive"] - description: "Status of the image" + enum: + - active + - inactive + description: Status of the image last_pulled: type: string - example: "2021-01-05T21:06:53.506400Z" - description: "datetime of last pull" + example: '2021-01-05T21:06:53.506400Z' + description: datetime of last pull nullable: true last_pushed: type: string - example: "2021-01-05T21:06:53.506400Z" - description: "datetime of last push" + example: '2021-01-05T21:06:53.506400Z' + description: datetime of last push nullable: true tag: type: object properties: id: type: integer - description: "tag ID" + description: tag ID images: type: object $ref: '#/components/schemas/image' creator: type: integer - description: "ID of the user that pushed the tag" + description: ID of the user that pushed the tag last_updated: type: string - example: "2021-01-05T21:06:53.506400Z" - description: "datetime of last update" + example: '2021-01-05T21:06:53.506400Z' + description: datetime of last update nullable: true last_updater: type: integer - description: "ID of the last user that updated the tag" + description: ID of the last user that updated the tag last_updater_username: type: string - description: "Hub username of the user that updated the tag" + description: Hub username of the user that updated the tag name: type: string - description: "name of the tag" + description: name of the tag repository: type: integer - description: "repository ID" + description: repository ID full_size: type: integer - description: "compressed size (sum of all layers) of the tagged image" + description: compressed size (sum of all layers) of the tagged image v2: type: string - description: "repository API version" + description: repository API version status: type: string - enum: ["active", "inactive"] - description: "whether a tag has been pushed to or pulled in the past month" + enum: + - active + - inactive + description: whether a tag has been pushed to or pulled in the past month tag_last_pulled: type: string - example: "2021-01-05T21:06:53.506400Z" - description: "datetime of last pull" + example: '2021-01-05T21:06:53.506400Z' + description: datetime of last pull nullable: true tag_last_pushed: type: string - example: "2021-01-05T21:06:53.506400Z" - description: "datetime of last push" + example: '2021-01-05T21:06:53.506400Z' + description: datetime of last push nullable: true - paginated_tags: allOf: - $ref: '#/components/schemas/page' @@ -1894,7 +2047,118 @@ components: type: string description: link to previous page of results if any nullable: true - + scim_schema_attribute: + type: object + properties: + name: + type: string + example: userName + type: + enum: + - string + - boolean + - complex + type: string + example: string + multiValued: + type: boolean + example: false + description: + type: string + example: Unique identifier for the User, typically used by the user to directly authenticate to the service provider. Each User MUST include a non-empty userName value. This identifier MUST be unique across the service provider's entire set of Users. + required: + type: boolean + example: true + caseExact: + type: boolean + example: false + mutability: + type: string + example: readWrite + returned: + type: string + example: default + uniqueness: + type: string + example: server + scim_schema_parent_attribute: + allOf: + - $ref: '#/components/schemas/scim_schema_attribute' + - type: object + properties: + subAttributes: + type: array + items: + $ref: '#/components/schemas/scim_schema_attribute' + invite: + type: object + properties: + id: + type: string + description: uuid representing the invite id + example: e36eca69-4cc8-4f17-9845-ae8c2b832691 + inviter_username: + type: string + example: moby + invitee: + type: string + description: can either be a dockerID for registred users or an email for non-registred users + example: invitee@docker.com + org: + type: string + description: name of the org to join + example: docker + team: + type: string + description: name of the team (user group) to join + example: owners + created_at: + type: string + example: '2021-10-28T18:30:19.520861Z' + bulk_invite: + type: object + properties: + invitees: + type: array + description: A list of invitees + items: + type: object + properties: + invitee: + type: string + description: invitee email or Docker ID + status: + type: string + description: status of the invite or validation error + invite: + description: Invite data if successfully invited + $ref: '#/components/schemas/invite' + example: + invitees: + - invitee: invitee@docker.com + status: invited + invite: + id: e36eca69-4cc8-4f17-9845-ae8c2b832691 + inviter_username: moby + invitee: invitee@docker.com + org: docker + team: owners + created_at: '2021-10-28T18:30:19.520861Z' + - invitee: invitee2@docker.com + status: existing_org_member + - invitee: invitee3@docker.com + status: invalid_email_or_docker_id + error: + type: object + properties: + errinfo: + type: object + items: + type: string + detail: + type: string + message: + type: string scim_error: type: object properties: @@ -1909,7 +2173,180 @@ components: detail: type: string description: Details about why the request failed. - + user: + type: object + properties: + id: + type: string + example: 0ab70deb065a43fcacd55d48caa945d8 + description: The UUID trimmed + company: + type: string + example: Docker Inc + date_joined: + type: string + example: '2021-01-05T21:06:53.506400Z' + full_name: + type: string + example: Jon Snow + gravatar_email: + type: string + gravatar_url: + type: string + location: + type: string + profile_url: + type: string + type: + type: string + enum: + - User + - Org + example: User + username: + type: string + example: dockeruser + org_member: + allOf: + - $ref: '#/components/schemas/user' + properties: + email: + type: string + description: User's email address + example: example@docker.com + role: + type: string + description: User's role in the Organization + enum: + - Owner + - Member + - Invitee + example: Owner + groups: + type: array + description: Groups (Teams) that the user is member of + items: + type: string + example: + - developers + - owners + is_guest: + type: boolean + description: If the organization has verfied domains, members that have email addresses outside of those domains will be flagged as Guest member + example: false + primary_email: + type: string + description: User's email primary address + example: example@docker.com + deprecated: true + org_member_paginated: + type: object + properties: + count: + type: number + description: The total number of items that match with the search. + example: 120 + previous: + type: string + description: The URL or link for the previous page of items. + example: https://hub.docker.com/v2/some/resources/items?page=1&page_size=20 + next: + type: string + description: The URL or link for the next page of items. + example: https://hub.docker.com/v2/some/resources/items?page=3&page_size=20 + results: + type: array + description: List of accounts. + items: + $ref: '#/components/schemas/org_member' + org_group: + type: object + properties: + id: + type: number + example: 10 + description: Group ID + uuid: + type: string + description: UUID for the group + name: + type: string + example: mygroup + description: Name of the group + description: + type: string + example: Groups description + description: Description of the group + member_count: + type: number + example: 10 + description: Member count of the group + group_member: + type: object + properties: + id: + type: string + example: 0ab70deb065a43fcacd55d48caa945d8 + description: The UUID trimmed + company: + type: string + example: Docker Inc + date_joined: + type: string + example: '2021-01-05T21:06:53.506400Z' + full_name: + type: string + example: John Snow + gravatar_email: + type: string + gravatar_url: + type: string + location: + type: string + profile_url: + type: string + type: + type: string + enum: + - User + - Org + example: User + username: + type: string + example: dockeruser + email: + type: string + example: dockeruser@docker.com + email_address: + type: object + properties: + id: + type: number + user_id: + type: number + email: + type: string + example: dockeruser@docker.com + verified: + type: boolean + primary: + type: boolean + legacy_email_address: + allOf: + - $ref: '#/components/schemas/email_address' + - type: object + properties: + user: + type: string + example: dockeruser + email_with_username: + allOf: + - $ref: '#/components/schemas/email_address' + - type: object + properties: + username: + type: string + example: dockeruser scim_service_provider_config: type: object properties: @@ -1917,10 +2354,11 @@ components: type: array items: type: string - example: [ "urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig" ] + example: + - urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig documentationUri: type: string - example: "" + example: '' patch: properties: supported: @@ -1974,11 +2412,10 @@ components: example: The OAuth 2.0 Bearer Token Authentication scheme. OAuth enables clients to access protected resources by obtaining an access token, which is defined in RFC 6750 as "a string representing an access authorization issued to the client", rather than using the resource owner's credentials directly. specUri: type: string - example: "http://tools.ietf.org/html/rfc6750" + example: http://tools.ietf.org/html/rfc6750 type: type: string example: oauthbearertoken - scim_resource_type: type: object properties: @@ -1986,7 +2423,8 @@ components: type: array items: type: string - example: "urn:ietf:params:scim:schemas:core:2.0:ResourceType" + example: + - urn:ietf:params:scim:schemas:core:2.0:ResourceType id: type: string example: User @@ -1998,57 +2436,10 @@ components: example: User endpoint: type: string - example: "/Users" + example: /Users schema: type: string - example: "urn:ietf:params:scim:schemas:core:2.0:User" - - scim_schema_attribute: - type: object - properties: - name: - type: string - example: userName - type: - enum: - - string - - boolean - - complex - type: string - example: string - multiValued: - type: boolean - example: false - description: - type: string - example: Unique identifier for the User, typically used by the user to directly authenticate to the service provider. Each User MUST include a non-empty userName value. This identifier MUST be unique across the service provider's entire set of Users. - required: - type: boolean - example: true - caseExact: - type: boolean - example: false - mutability: - type: string - example: readWrite - returned: - type: string - example: default - uniqueness: - type: string - example: server - - - scim_schema_parent_attribute: - allOf: - - $ref: "#/components/schemas/scim_schema_attribute" - - type: object - properties: - subAttributes: - type: array - items: - $ref: "#/components/schemas/scim_schema_attribute" - + example: urn:ietf:params:scim:schemas:core:2.0:User scim_schema: type: object properties: @@ -2056,7 +2447,8 @@ components: type: array items: type: string - example: [ "urn:ietf:params:scim:schemas:core:2.0:Schema" ] + example: + - urn:ietf:params:scim:schemas:core:2.0:Schema id: type: string example: urn:ietf:params:scim:schemas:core:2.0:User @@ -2068,10 +2460,9 @@ components: example: User Account attributes: type: array - example: [ ] + example: [] items: - $ref: "#/components/schemas/scim_schema_parent_attribute" - + $ref: '#/components/schemas/scim_schema_parent_attribute' scim_email: type: object properties: @@ -2084,22 +2475,19 @@ components: primary: type: boolean example: true - scim_group: type: object properties: value: type: string - example: "nightswatch" + example: nightswatch display: type: string - example: "nightswatch" - + example: nightswatch scim_user_username: type: string description: The user's email address. This must be reachable via email. example: jon.snow@docker.com - scim_user_name: type: object properties: @@ -2109,48 +2497,44 @@ components: familyName: type: string example: Snow - scim_user_display_name: type: string description: The username in Docker. Also known as the "Docker ID". example: jonsnow - scim_user_schemas: type: array items: type: string - example: "urn:ietf:params:scim:schemas:core:2.0:User" + example: urn:ietf:params:scim:schemas:core:2.0:User minItems: 1 - scim_user_id: type: string example: d80f7c79-7730-49d8-9a41-7c42fb622d9c description: The unique identifier for the user. A v4 UUID. - scim_user: type: object properties: schemas: - $ref: "#/components/schemas/scim_user_schemas" + $ref: '#/components/schemas/scim_user_schemas' id: - $ref: "#/components/schemas/scim_user_id" + $ref: '#/components/schemas/scim_user_id' userName: - $ref: "#/components/schemas/scim_user_username" + $ref: '#/components/schemas/scim_user_username' name: - $ref: "#/components/schemas/scim_user_name" + $ref: '#/components/schemas/scim_user_name' displayName: - $ref: "#/components/schemas/scim_user_display_name" + $ref: '#/components/schemas/scim_user_display_name' active: type: boolean example: true emails: type: array items: - $ref: "#/components/schemas/scim_email" + $ref: '#/components/schemas/scim_email' groups: type: array items: - $ref: "#/components/schemas/scim_group" + $ref: '#/components/schemas/scim_group' meta: type: object properties: @@ -2162,31 +2546,13 @@ components: example: https://hub.docker.com/v2/scim/2.0/Users/d80f7c79-7730-49d8-9a41-7c42fb622d9c created: type: string - description: The creation date for the user as a RFC3339 formatted - string. - example: 2022-05-20T00:54:18Z + description: The creation date for the user as a RFC3339 formatted string. + example: '2022-05-20T00:54:18Z' lastModified: type: string - description: The date the user was last modified as a RFC3339 - formatted string. - example: 2022-05-20T00:54:18Z - + description: The date the user was last modified as a RFC3339 formatted string. + example: '2022-05-20T00:54:18Z' parameters: - scim_attributes: - in: query - name: attributes - schema: - type: string - description: Comma delimited list of attributes to limit to in the - response. - example: userName,displayName - scim_user_id: - name: id - in: path - schema: - type: string - description: The user ID. - example: "d80f7c79-7730-49d8-9a41-7c42fb622d9c" namespace: in: path name: namespace @@ -2205,22 +2571,132 @@ components: required: true schema: type: string + org_name: + in: path + name: org_name + description: Name of the organization (namespace). + schema: + type: string + example: myorganization + required: true + group_name: + in: path + name: group_name + description: Name of the group (team) in the organization. + schema: + type: string + example: developers + required: true + username: + in: path + name: username + description: Username, identifier for the user (namespace, DockerID). + schema: + type: string + example: jonsnow + required: true page: in: query name: page - required: false + description: Page number (starts on 1). schema: type: integer - description: "Page number to get. Defaults to 1." page_size: in: query name: page_size - required: false + description: Number of items (rows) per page. schema: type: integer - description: "Number of items to get per page. Defaults to 10. Max of 100." - + invites: + in: query + name: invites + description: Include invites in the response. + schema: + type: boolean + search: + in: query + name: search + schema: + type: integer + description: Search term. + scim_attributes: + in: query + name: attributes + schema: + type: string + description: Comma delimited list of attributes to limit to in the response. + example: userName,displayName + scim_user_id: + name: id + in: path + schema: + type: string + description: The user ID. + example: d80f7c79-7730-49d8-9a41-7c42fb622d9c + required: true + type: + in: query + name: type + schema: + type: string + enum: + - all + - invitee + - member + example: all + role: + in: query + name: role + schema: + type: string + enum: + - owner + - editor + - member + example: owner + bulk_invite: + in: header + name: X-Analytics-Client-Feature + description: Optional string that indicates the feature used to submit the bulk invites (e.g.'file', 'web') + schema: + type: string requestBodies: + bulk_invite_request: + required: true + content: + application/json: + schema: + type: object + required: + - org + - invitees + properties: + org: + type: string + description: organization name + example: docker + team: + type: string + description: team name + example: owners + role: + type: string + description: role for invitees + example: member + invitees: + type: array + description: list of invitees emails or Docker Ids + items: + type: string + description: invitee email or Docker ID + example: + - invitee1DockerId + - invitee2@docker.com + - invitee3@docker.com + dry_run: + type: boolean + description: Optional, run through validation but don't actually change data. + example: true scim_create_user_request: required: true content: @@ -2232,12 +2708,11 @@ components: - userName properties: schemas: - $ref: "#/components/schemas/scim_user_schemas" + $ref: '#/components/schemas/scim_user_schemas' userName: - $ref: "#/components/schemas/scim_user_username" + $ref: '#/components/schemas/scim_user_username' name: - $ref: "#/components/schemas/scim_user_name" - + $ref: '#/components/schemas/scim_user_name' scim_update_user_request: required: true content: @@ -2248,15 +2723,41 @@ components: - schemas properties: schemas: - $ref: "#/components/schemas/scim_user_schemas" + $ref: '#/components/schemas/scim_user_schemas' name: allOf: - - $ref: "#/components/schemas/scim_user_name" - - description: If this is omitted from the request, the - update will skip the update on it. We will only ever - change the name, but not clear it. + - $ref: '#/components/schemas/scim_user_name' + - description: If this is omitted from the request, the update will skip the update on it. We will only ever change the name, but not clear it. enabled: type: boolean default: false - description: If this is omitted from the request, it will - default to false resulting in a deactivated user. + description: If this is omitted from the request, it will default to false resulting in a deactivated user. + add_member_to_org_group: + required: true + content: + application/json: + schema: + type: object + required: + - member + properties: + member: + type: string + example: jonsnow +x-tagGroups: + - name: General + tags: + - resources + - rate-limiting + - name: API + tags: + - authentication + - access-tokens + - images + - audit-logs + - org-settings + - repositories + - scim + - orgs + - groups + - invites diff --git a/content/reference/cli/docker/desktop/_index.md b/content/reference/cli/docker/desktop/_index.md new file mode 100644 index 00000000000..be7ff711b12 --- /dev/null +++ b/content/reference/cli/docker/desktop/_index.md @@ -0,0 +1,10 @@ +--- +datafolder: desktop-cli +datafile: docker_desktop +title: docker desktop (Beta) +layout: cli +--- + +{{% experimental title="Beta" %}} +Docker Desktop CLI is currently in [Beta](/manuals/release-lifecycle.md#beta). +{{% /experimental %}} \ No newline at end of file diff --git a/content/reference/cli/docker/desktop/engine/_index.md b/content/reference/cli/docker/desktop/engine/_index.md new file mode 100644 index 00000000000..97950535974 --- /dev/null +++ b/content/reference/cli/docker/desktop/engine/_index.md @@ -0,0 +1,6 @@ +--- +datafolder: desktop-cli +datafile: docker_desktop_engine +title: docker desktop engine +layout: cli +--- \ No newline at end of file diff --git a/content/reference/cli/docker/desktop/engine/ls.md b/content/reference/cli/docker/desktop/engine/ls.md new file mode 100644 index 00000000000..a8499b1385e --- /dev/null +++ b/content/reference/cli/docker/desktop/engine/ls.md @@ -0,0 +1,6 @@ +--- +datafolder: desktop-cli +datafile: docker_desktop_engine_ls +title: docker desktop engine ls +layout: cli +--- \ No newline at end of file diff --git a/content/reference/cli/docker/desktop/engine/use.md b/content/reference/cli/docker/desktop/engine/use.md new file mode 100644 index 00000000000..56f58a96655 --- /dev/null +++ b/content/reference/cli/docker/desktop/engine/use.md @@ -0,0 +1,6 @@ +--- +datafolder: desktop-cli +datafile: docker_desktop_engine_use +title: docker desktop engine use +layout: cli +--- \ No newline at end of file diff --git a/content/reference/cli/docker/desktop/restart.md b/content/reference/cli/docker/desktop/restart.md new file mode 100644 index 00000000000..75ef78eeb49 --- /dev/null +++ b/content/reference/cli/docker/desktop/restart.md @@ -0,0 +1,6 @@ +--- +datafolder: desktop-cli +datafile: docker_desktop_restart +title: docker desktop restart +layout: cli +--- \ No newline at end of file diff --git a/content/reference/cli/docker/desktop/start.md b/content/reference/cli/docker/desktop/start.md new file mode 100644 index 00000000000..e9eccd116e2 --- /dev/null +++ b/content/reference/cli/docker/desktop/start.md @@ -0,0 +1,10 @@ +--- +datafolder: desktop-cli +datafile: docker_desktop_start +title: docker desktop start +layout: cli +--- + +> [!NOTE] +> +> `docker desktop start` doesn't work when executed via SSH on Windows due to a limitation in how WinCred stores credentials securely. diff --git a/content/reference/cli/docker/desktop/status.md b/content/reference/cli/docker/desktop/status.md new file mode 100644 index 00000000000..b0b868c579b --- /dev/null +++ b/content/reference/cli/docker/desktop/status.md @@ -0,0 +1,6 @@ +--- +datafolder: desktop-cli +datafile: docker_desktop_status +title: docker desktop status +layout: cli +--- \ No newline at end of file diff --git a/content/reference/cli/docker/desktop/stop.md b/content/reference/cli/docker/desktop/stop.md new file mode 100644 index 00000000000..203bdef5669 --- /dev/null +++ b/content/reference/cli/docker/desktop/stop.md @@ -0,0 +1,6 @@ +--- +datafolder: desktop-cli +datafile: docker_desktop_stop +title: docker desktop stop +layout: cli +--- \ No newline at end of file diff --git a/content/reference/compose-file/develop.md b/content/reference/compose-file/develop.md index 1e48a00ff29..d08ad90a31d 100644 --- a/content/reference/compose-file/develop.md +++ b/content/reference/compose-file/develop.md @@ -56,10 +56,36 @@ Compose to monitor source code for changes. For more information, see [Use Compo `action` defines the action to take when changes are detected. If `action` is set to: - `rebuild`, Compose rebuilds the service image based on the `build` section and recreates the service with the updated image. +- `restart`, Compose restarts the service container. Available with Docker Compose version 2.32.0 and later. - `sync`, Compose keeps the existing service container(s) running, but synchronizes source files with container content according to the `target` attribute. -- `sync+restart`, Compose synchronizes source files with container content according to the `target` attribute, and then restarts the container. +- `sync+restart`, Compose synchronizes source files with container content according to the `target` attribute, and then restarts the container. Available with Docker Compose version 2.23.0 and later. +- `sync+exec`, Compose synchronizes source files with container content according to the `target` attribute, and then executes a command inside the container. Available with Docker Compose version 2.32.0 and later. -> `sync+restart` attribute is available with Docker Compose version 2.23.0 and later. +#### exec + +{{< introduced compose 2.23.2 "/manuals/compose/releases/release-notes.md#2232" >}} + +`exec` is only relevant when `action` is set to `sync+exec`. Like [service hooks](services.md#post_start), `exec` is used to define the command to be run inside the container once it has started. + +- `command`: Specifies the command to run once the container starts. This attribute is required, and you can choose to use either the shell form or the exec form. +- `user`: The user to run the command. If not set, the command is run with the same user as the main service command. +- `privileged`: Lets the command run with privileged access. +- `working_dir`: The working directory in which to run the command. If not set, it is run in the same working directory as the main service command. +- `environment`: Sets the environment variables to run the command. While the command inherits the environment variables defined for the service’s main command, this section lets you add new variables or override existing ones. + +```yaml +services: + frontend: + image: ... + develop: + watch: + # sync content then run command to reload service without interruption + - path: ./etc/config + action: sync+exec + target: /etc/config/ + exec: + command: app reload +``` #### ignore diff --git a/content/reference/compose-file/interpolation.md b/content/reference/compose-file/interpolation.md index 6db6f88f468..b897bcd8923 100644 --- a/content/reference/compose-file/interpolation.md +++ b/content/reference/compose-file/interpolation.md @@ -31,6 +31,10 @@ Interpolation can also be nested: Other extended shell-style features, such as `${VARIABLE/foo/bar}`, are not supported by Compose. +Compose processes any string following a `$` sign as long as it makes it +a valid variable definition - either an alphanumeric name (`[_a-zA-Z][_a-zA-Z0-9]*`) +or a braced string starting with `${`. In other circumstances, it will be preserved without attempting to interpolate a value. + You can use a `$$` (double-dollar sign) when your configuration needs a literal dollar sign. This also prevents Compose from interpolating a value, so a `$$` allows you to refer to environment variables that you don't want processed by diff --git a/content/reference/compose-file/services.md b/content/reference/compose-file/services.md index 24906a00d3d..64867c483b0 100644 --- a/content/reference/compose-file/services.md +++ b/content/reference/compose-file/services.md @@ -184,7 +184,7 @@ an integer value using microseconds as unit or a [duration](extension.md#specify ```yml cpu_rt_runtime: '400ms' - cpu_rt_runtime: 95000` + cpu_rt_runtime: '95000' ``` ### cpu_rt_period @@ -194,7 +194,7 @@ an integer value using microseconds as unit or a [duration](extension.md#specify ```yml cpu_rt_period: '1400us' - cpu_rt_period: 11000` + cpu_rt_period: '11000' ``` ### cpus @@ -618,6 +618,12 @@ i.e. overridden to be empty. env_file: .env ``` +Relative paths are resolved from the Compose file's parent folder. As absolute paths prevent the Compose +file from being portable, Compose warns you when such a path is used to set `env_file`. + +Environment variables declared in the [environment](#environment) section override these values. This holds true even if those values are +empty or undefined. + `env_file` can also be a list. The files in the list are processed from the top down. For the same variable specified in two env files, the value from the last file in the list stands. @@ -627,9 +633,14 @@ env_file: - ./b.env ``` -List elements can also be declared as a mapping, which then lets you set an additional -attribute `required`. This defaults to `true`. When `required` is set to `false` and the `.env` file is missing, -Compose silently ignores the entry. +List elements can also be declared as a mapping, which then lets you set additional +attributes. + +#### required + +{{< introduced compose 2.24.0 "/manuals/compose/releases/release-notes.md#2240" >}} + +The `required` attribute defaults to `true`. When `required` is set to `false` and the `.env` file is missing, Compose silently ignores the entry. ```yml env_file: @@ -638,13 +649,21 @@ env_file: - path: ./override.env required: false ``` -> `required` attribute is available with Docker Compose version 2.24.0 or later. -Relative path are resolved from the Compose file's parent folder. As absolute paths prevent the Compose -file from being portable, Compose warns you when such a path is used to set `env_file`. +#### format -Environment variables declared in the [environment](#environment) section override these values. This holds true even if those values are -empty or undefined. +{{< introduced compose 2.30.0 "/manuals/compose/releases/release-notes.md#2300" >}} + +The `format` attribute lets you use an alternative file format for the `env_file`. When not set, `env_file` is parsed according to the Compose rules outlined in [Env_file format](#env_file-format). + +`raw` format lets you use an `env_file` with key=value items, but without any attempt from Compose to parse the value for interpolation. +This let you pass values as-is, including quotes and `$` signs. + +```yml +env_file: + - path: ./default.env + format: raw +``` #### Env_file format @@ -894,12 +913,12 @@ services: common: image: busybox security_opt: - - label:role:ROLE + - label=role:ROLE cli: extends: service: common security_opt: - - label:user:USER + - label=user:USER ``` Produces the following configuration for the `cli` service. @@ -907,8 +926,8 @@ Produces the following configuration for the `cli` service. ```yaml image: busybox security_opt: -- label:role:ROLE -- label:user:USER +- label=role:ROLE +- label=user:USER ``` In case list syntax is used, the following keys should also be treated as sequences: @@ -1133,6 +1152,27 @@ Compose creates containers with canonical labels: The `com.docker.compose` label prefix is reserved. Specifying labels with this prefix in the Compose file results in a runtime error. +### label_file + +{{< introduced compose 2.23.2 "/manuals/compose/releases/release-notes.md#2232" >}} + +The `label_file` attribute lets you load labels for a service from an external file or a list of files. This provides a convenient way to manage multiple labels without cluttering the Compose file. + +The file uses a key-value format, similar to `env_file`. You can specify multiple files as a list. When using multiple files, they are processed in the order they appear in the list. If the same label is defined in multiple files, the value from the last file in the list overrides earlier ones. + +```yaml +services: + one: + label_file: ./app.labels + + two: + label_file: + - ./app.labels + - ./additional.labels +``` + +If a label is defined in both the `label_file` and the `labels` attribute, the value in [labels](#labels) takes precedence. + ### links `links` defines a network link to containers in another service. Either specify both the service name and @@ -1505,6 +1545,39 @@ ports: mode: host ``` +### post_start + +{{< introduced compose 2.30.0 "../../manuals/compose/releases/release-notes.md#2300" >}} + +`post_start` defines a sequence of lifecycle hooks to run after a container has started. The exact timing of when the command is run is not guaranteed. + +- `command`: Specifies the command to run once the container starts. This attribute is required, and you can choose to use either the shell form or the exec form. +- `user`: The user to run the command. If not set, the command is run with the same user as the main service command. +- `privileged`: Lets the `post_start` command run with privileged access. +- `working_dir`: The working directory in which to run the command. If not set, it is run in the same working directory as the main service command. +- `environment`: Sets environment variables specifically for the `post_start` command. While the command inherits the environment variables defined for the service’s main command, this section lets you add new variables or override existing ones. + +```yaml +services: + test: + post_start: + - command: ./do_something_on_startup.sh + user: root + privileged: true + environment: + - FOO=BAR +``` + +For more information, see [Use lifecycle hooks](/manuals/compose/how-tos/lifecycle.md). + +### pre_stop + +{{< introduced compose 2.30.0 "../../manuals/compose/releases/release-notes.md#2300" >}} + +`pre_stop` defines a sequence of lifecycle hooks to run before the container is stopped. These hooks won't run if the container stops by itself or is terminated suddenly. + +Configuration is equivalent to [post_start](#post_start). + ### privileged `privileged` configures the service container to run with elevated privileges. Support and actual impacts are platform specific. @@ -1663,8 +1736,8 @@ secrets: ```yml security_opt: - - label:user:USER - - label:role:ROLE + - label=user:USER + - label=role:ROLE ``` For further default labeling schemes you can override, see [Security configuration](/reference/cli/docker/container/run.md#security-opt). @@ -1739,13 +1812,26 @@ parameters (sysctls) at runtime](/reference/cli/docker/container/run.md#sysctl). `tmpfs` mounts a temporary file system inside the container. It can be a single value or a list. ```yml -tmpfs: /run +tmpfs: + - + - : ``` +- `path`: The path inside the container where the tmpfs will be mounted. +- `options`: Comma-separated list of options for the tmpfs mount. + +Available options: + +- `mode`: Sets the file system permissions. +- `uid`: Sets the user ID that owns the mounted tmpfs. +- `gid`: Sets the group ID that owns the mounted tmpfs. + ```yml -tmpfs: - - /run - - /tmp +services: + app: + tmpfs: + - /data:mode=755,uid=1009,gid=1009 + - /run ``` ### tty @@ -1874,7 +1960,7 @@ expressed in the short form. > [!TIP] > > Working with large repositories or monorepos, or with virtual file systems that are no longer scaling with your codebase? -> Compose now takes advantage of [Synchronized file shares](/manuals/desktop/synchronized-file-sharing.md) and automatically creates file shares for bind mounts. +> Compose now takes advantage of [Synchronized file shares](/manuals/desktop/features/synchronized-file-sharing.md) and automatically creates file shares for bind mounts. > Ensure you're signed in to Docker with a paid subscription and have enabled both **Access experimental features** and **Manage Synchronized file shares with Compose** in Docker Desktop's settings. ### volumes_from diff --git a/content/reference/compose-file/volumes.md b/content/reference/compose-file/volumes.md index 6d87ffa19d1..fb026e2669a 100644 --- a/content/reference/compose-file/volumes.md +++ b/content/reference/compose-file/volumes.md @@ -14,7 +14,7 @@ To use a volume across multiple services, you must explicitly grant each service > [!TIP] > > Working with large repositories or monorepos, or with virtual file systems that are no longer scaling with your codebase? -> Compose now takes advantage of [Synchronized file shares](/manuals/desktop/synchronized-file-sharing.md) and automatically creates file shares for bind mounts. +> Compose now takes advantage of [Synchronized file shares](/manuals/desktop/features/synchronized-file-sharing.md) and automatically creates file shares for bind mounts. > Ensure you're signed in to Docker with a paid subscription and have enabled both **Access experimental features** and **Manage Synchronized file shares with Compose** in Docker Desktop's settings. ## Example diff --git a/content/reference/samples/_index.md b/content/reference/samples/_index.md index 60bfae8a621..49c769ba4bc 100644 --- a/content/reference/samples/_index.md +++ b/content/reference/samples/_index.md @@ -12,6 +12,7 @@ aliases: - /examples/ - /samples/runnning_riak_service/ - /samples/apt-cacher-ng/ +- /samples/ --- Learn how to containerize different types of services by walking through Official Docker samples. diff --git a/content/reference/samples/ai-ml.md b/content/reference/samples/ai-ml.md index add07b81e3c..08a1894cea7 100644 --- a/content/reference/samples/ai-ml.md +++ b/content/reference/samples/ai-ml.md @@ -2,4 +2,6 @@ title: AI/ML samples description: Docker samples for AI/ML. service: aiml +aliases: +- /samples/ai-ml/ --- diff --git a/content/reference/samples/angular.md b/content/reference/samples/angular.md index 7f0c0c68d62..f21a2127180 100644 --- a/content/reference/samples/angular.md +++ b/content/reference/samples/angular.md @@ -2,4 +2,6 @@ title: Angular samples description: Docker samples for Angular. service: angular +aliases: +- /samples/angular/ --- diff --git a/content/reference/samples/cloudflared.md b/content/reference/samples/cloudflared.md index 977d543d1ca..25ab8021126 100644 --- a/content/reference/samples/cloudflared.md +++ b/content/reference/samples/cloudflared.md @@ -2,4 +2,6 @@ title: Cloudflared samples description: Docker samples for cloudflared. service: cloudflared +aliases: +- /samples/cloudflared/ --- diff --git a/content/reference/samples/django.md b/content/reference/samples/django.md index fdc2b1e0a6b..80f55389d6c 100644 --- a/content/reference/samples/django.md +++ b/content/reference/samples/django.md @@ -4,4 +4,5 @@ description: Docker samples for Django. service: django aliases: - /compose/django/ +- /samples/django/ --- diff --git a/content/reference/samples/dotnet.md b/content/reference/samples/dotnet.md index 59d1539ba73..5fa11341551 100644 --- a/content/reference/samples/dotnet.md +++ b/content/reference/samples/dotnet.md @@ -6,4 +6,5 @@ aliases: - /samples/dotnetcore/ - /compose/aspnet-mssql-compose/ - /samples/aspnet-mssql-compose/ +- /samples/dotnet/ --- diff --git a/content/reference/samples/elasticsearch.md b/content/reference/samples/elasticsearch.md index ef06e122469..e1da037034a 100644 --- a/content/reference/samples/elasticsearch.md +++ b/content/reference/samples/elasticsearch.md @@ -2,4 +2,6 @@ title: Elasticsearch / Logstash / Kibana samples description: Docker samples for Elasticsearch, Logstash, and Kibana. service: elk +aliases: +- /samples/elasticsearch/ --- diff --git a/content/reference/samples/express.md b/content/reference/samples/express.md index d7704c65835..e2c5475a639 100644 --- a/content/reference/samples/express.md +++ b/content/reference/samples/express.md @@ -2,4 +2,6 @@ title: Express samples description: Docker samples for Express. service: express +aliases: +- /samples/express/ --- diff --git a/content/reference/samples/fastapi.md b/content/reference/samples/fastapi.md index b16f77263b4..6c95971b6fe 100644 --- a/content/reference/samples/fastapi.md +++ b/content/reference/samples/fastapi.md @@ -2,4 +2,6 @@ title: FastAPI samples description: Docker samples for .NET. service: fastapi +aliases: +- /samples/fastapi/ --- diff --git a/content/reference/samples/flask.md b/content/reference/samples/flask.md index 002be64178a..3ea454d98bb 100644 --- a/content/reference/samples/flask.md +++ b/content/reference/samples/flask.md @@ -2,4 +2,6 @@ title: Flask samples description: Docker samples for Flask. service: flask +aliases: +- /samples/flask/ --- diff --git a/content/reference/samples/gitea.md b/content/reference/samples/gitea.md index 6e7cd9b5836..e529afad8b8 100644 --- a/content/reference/samples/gitea.md +++ b/content/reference/samples/gitea.md @@ -2,4 +2,6 @@ title: Gitea samples description: Docker samples for Gitea. service: gitea +aliases: +- /samples/gitea/ --- diff --git a/content/reference/samples/go.md b/content/reference/samples/go.md index dfb8a5c0f9c..d5880b03612 100644 --- a/content/reference/samples/go.md +++ b/content/reference/samples/go.md @@ -2,4 +2,6 @@ title: Go samples description: Docker samples for Go. service: go +aliases: +- /samples/go/ --- diff --git a/content/reference/samples/java.md b/content/reference/samples/java.md index 0d221dcd669..c8a323d5eee 100644 --- a/content/reference/samples/java.md +++ b/content/reference/samples/java.md @@ -2,4 +2,6 @@ title: Java samples description: Docker samples for Java. service: java +aliases: +- /samples/java/ --- diff --git a/content/reference/samples/javascript.md b/content/reference/samples/javascript.md index d93634895c5..37a01851b73 100644 --- a/content/reference/samples/javascript.md +++ b/content/reference/samples/javascript.md @@ -2,4 +2,6 @@ title: JavaScript samples description: Docker samples for JavaScript. service: javascript +aliases: +- /samples/javascript/ --- diff --git a/content/reference/samples/mariadb.md b/content/reference/samples/mariadb.md index 9ff385b9bde..96a6b515637 100644 --- a/content/reference/samples/mariadb.md +++ b/content/reference/samples/mariadb.md @@ -2,4 +2,6 @@ title: MariaDB samples description: Docker samples for MariaDB. service: mariadb +aliases: +- /samples/mariadb/ --- diff --git a/content/reference/samples/minecraft.md b/content/reference/samples/minecraft.md index e8d2fd67d11..fd4603a4a34 100644 --- a/content/reference/samples/minecraft.md +++ b/content/reference/samples/minecraft.md @@ -2,4 +2,6 @@ title: Minecraft samples description: Docker samples for Minecraft. service: minecraft +aliases: +- /samples/minecraft/ --- diff --git a/content/reference/samples/mongodb.md b/content/reference/samples/mongodb.md index c36a4a1aaee..0a7a7d1fc42 100644 --- a/content/reference/samples/mongodb.md +++ b/content/reference/samples/mongodb.md @@ -2,4 +2,6 @@ title: MongoDB samples description: Docker samples for MongoDB. service: mongodb +aliases: +- /samples/mongodb/ --- diff --git a/content/reference/samples/ms-sql.md b/content/reference/samples/ms-sql.md index fc6fb86833d..f1cb76ed40e 100644 --- a/content/reference/samples/ms-sql.md +++ b/content/reference/samples/ms-sql.md @@ -2,4 +2,6 @@ title: MS-SQL samples description: Docker samples for MS-SQL. service: ms-sql +aliases: +- /samples/ms-sql/ --- diff --git a/content/reference/samples/mysql.md b/content/reference/samples/mysql.md index e3449d77669..d607c0924a0 100644 --- a/content/reference/samples/mysql.md +++ b/content/reference/samples/mysql.md @@ -2,4 +2,6 @@ title: MySQL samples description: Docker samples for MySQL. service: mysql +aliases: +- /samples/mysql/ --- diff --git a/content/reference/samples/nextcloud.md b/content/reference/samples/nextcloud.md index 91d7041b04b..480c3c07682 100644 --- a/content/reference/samples/nextcloud.md +++ b/content/reference/samples/nextcloud.md @@ -2,4 +2,6 @@ title: Nextcloud samples description: Docker samples for Nextcloud. service: nextcloud +aliases: +- /samples/nexcloud/ --- diff --git a/content/reference/samples/nginx.md b/content/reference/samples/nginx.md index 29b6b785622..83e7ff347c0 100644 --- a/content/reference/samples/nginx.md +++ b/content/reference/samples/nginx.md @@ -2,4 +2,6 @@ title: NGINX samples description: Docker samples for NGINX. service: nginx +aliases: +- /samples/nginx/ --- diff --git a/content/reference/samples/nodejs.md b/content/reference/samples/nodejs.md index fd238fdd9d9..1ee7d0cba1a 100644 --- a/content/reference/samples/nodejs.md +++ b/content/reference/samples/nodejs.md @@ -2,4 +2,6 @@ title: Node.js samples description: Docker samples for Node.js. service: nodejs +aliases: +- /samples/nodejs/ --- diff --git a/content/reference/samples/php.md b/content/reference/samples/php.md index 4a92e45c3c5..2f1e3d11d26 100644 --- a/content/reference/samples/php.md +++ b/content/reference/samples/php.md @@ -2,4 +2,6 @@ title: PHP samples description: Docker samples for PHP. service: php +aliases: +- /samples/php/ --- diff --git a/content/reference/samples/pi-hole.md b/content/reference/samples/pi-hole.md index 3b89cd8a96d..aeb74933362 100644 --- a/content/reference/samples/pi-hole.md +++ b/content/reference/samples/pi-hole.md @@ -2,4 +2,6 @@ title: Pi-hole samples description: Docker samples for Pi-hole. service: pi-hole +aliases: +- /samples/pi-hole/ --- diff --git a/content/reference/samples/plex.md b/content/reference/samples/plex.md index 913edf57fbb..58553daf3eb 100644 --- a/content/reference/samples/plex.md +++ b/content/reference/samples/plex.md @@ -2,4 +2,6 @@ title: Plex samples description: Docker samples for Plex. service: plex +aliases: +- /samples/plex/ --- diff --git a/content/reference/samples/portainer.md b/content/reference/samples/portainer.md index f57b8563e97..40bde2f9e7f 100644 --- a/content/reference/samples/portainer.md +++ b/content/reference/samples/portainer.md @@ -2,4 +2,6 @@ title: Portainer samples description: Docker samples for Portainer. service: portainer +aliases: +- /samples/portainer/ --- diff --git a/content/reference/samples/postgres.md b/content/reference/samples/postgres.md index ef95f95f6d9..b3dd8d7a6ce 100644 --- a/content/reference/samples/postgres.md +++ b/content/reference/samples/postgres.md @@ -5,4 +5,5 @@ service: postgresql aliases: - /engine/examples/postgresql_service/ - /samples/postgresql_service/ +- /samples/postgres/ --- diff --git a/content/reference/samples/prometheus.md b/content/reference/samples/prometheus.md index addf2245141..6de8d8aba1d 100644 --- a/content/reference/samples/prometheus.md +++ b/content/reference/samples/prometheus.md @@ -2,4 +2,6 @@ title: Prometheus samples description: Docker samples for Prometheus. service: prometheus +aliases: +- /samples/prometheus/ --- diff --git a/content/reference/samples/python.md b/content/reference/samples/python.md index a725d7af3a3..d1619d82aef 100644 --- a/content/reference/samples/python.md +++ b/content/reference/samples/python.md @@ -2,4 +2,6 @@ title: Python samples description: Docker samples for Python. service: python +aliases: +- /samples/python/ --- diff --git a/content/reference/samples/rails.md b/content/reference/samples/rails.md index 166be026edc..267ac65933b 100644 --- a/content/reference/samples/rails.md +++ b/content/reference/samples/rails.md @@ -2,4 +2,6 @@ title: Rails samples description: Docker samples for Rails. service: rails +aliases: +- /samples/rails/ --- diff --git a/content/reference/samples/react.md b/content/reference/samples/react.md index b2b587d500c..7691e383cd7 100644 --- a/content/reference/samples/react.md +++ b/content/reference/samples/react.md @@ -2,4 +2,6 @@ title: React samples description: Docker samples for React. service: react +aliases: +- /samples/react/ --- diff --git a/content/reference/samples/redis.md b/content/reference/samples/redis.md index de51ada3fa7..9ba7c2ba7db 100644 --- a/content/reference/samples/redis.md +++ b/content/reference/samples/redis.md @@ -2,4 +2,6 @@ title: Redis samples description: Docker samples for Redis. service: redis +aliases: +- /samples/redis/ --- diff --git a/content/reference/samples/ruby.md b/content/reference/samples/ruby.md index 62247ca8cc1..4c728c31ca5 100644 --- a/content/reference/samples/ruby.md +++ b/content/reference/samples/ruby.md @@ -2,4 +2,6 @@ title: Ruby samples description: Docker samples for Ruby. service: ruby +aliases: +- /samples/ruby/ --- diff --git a/content/reference/samples/rust.md b/content/reference/samples/rust.md index 75e14b208a6..27784c49905 100644 --- a/content/reference/samples/rust.md +++ b/content/reference/samples/rust.md @@ -2,4 +2,6 @@ title: Rust samples description: Docker samples for Rust. service: rust +aliases: +- /samples/rust/ --- diff --git a/content/reference/samples/spark.md b/content/reference/samples/spark.md index f284328cea6..323f1a6ca7f 100644 --- a/content/reference/samples/spark.md +++ b/content/reference/samples/spark.md @@ -2,4 +2,6 @@ title: Spark samples description: Docker samples for Spark. service: spark +aliases: +- /samples/spark/ --- diff --git a/content/reference/samples/spring.md b/content/reference/samples/spring.md index a463cbfbc43..b774a2b4145 100644 --- a/content/reference/samples/spring.md +++ b/content/reference/samples/spring.md @@ -2,4 +2,6 @@ title: Spring Boot samples description: Docker samples for Spring Boot. service: spring +aliases: +- /samples/spring/ --- diff --git a/content/reference/samples/traefik.md b/content/reference/samples/traefik.md index c47e03683c1..ee7725fbcd3 100644 --- a/content/reference/samples/traefik.md +++ b/content/reference/samples/traefik.md @@ -2,4 +2,6 @@ title: Traefik samples description: Docker samples for Traefik. service: traefik +aliases: +- /samples/traefik/ --- diff --git a/content/reference/samples/typescript.md b/content/reference/samples/typescript.md index 9de3cfe652a..e3d4d04d01f 100644 --- a/content/reference/samples/typescript.md +++ b/content/reference/samples/typescript.md @@ -2,4 +2,6 @@ title: TypeScript samples description: Docker samples for TypeScript. service: typescript +aliases: +- /samples/typescript/ --- diff --git a/content/reference/samples/vuejs.md b/content/reference/samples/vuejs.md index 35e00b71468..73731391542 100644 --- a/content/reference/samples/vuejs.md +++ b/content/reference/samples/vuejs.md @@ -2,4 +2,6 @@ title: Vue.js samples description: Docker samples for Vue.js. service: vuejs +aliases: +- /samples/vuejs/ --- diff --git a/content/reference/samples/wireguard.md b/content/reference/samples/wireguard.md index 4041a96e4fb..2f38336b3ac 100644 --- a/content/reference/samples/wireguard.md +++ b/content/reference/samples/wireguard.md @@ -2,4 +2,6 @@ title: WireGuard samples description: Docker samples for WireGuard. service: wireguard +aliases: +- /samples/wireguard/ --- diff --git a/content/reference/samples/wordpress.md b/content/reference/samples/wordpress.md index dad63d2731d..169ddb569b2 100644 --- a/content/reference/samples/wordpress.md +++ b/content/reference/samples/wordpress.md @@ -4,4 +4,5 @@ description: Docker samples for WordPress. service: wordpress aliases: - /compose/wordpress/ +- /samples/wordpress/ --- diff --git a/data/buildx/docker_buildx.yaml b/data/buildx/docker_buildx.yaml index 27f0d5e754a..c13fe0b3c35 100644 --- a/data/buildx/docker_buildx.yaml +++ b/data/buildx/docker_buildx.yaml @@ -1,6 +1,7 @@ command: docker buildx short: Docker Buildx long: Extended build capabilities with BuildKit +usage: docker buildx pname: docker plink: docker.yaml cname: diff --git a/data/buildx/docker_buildx_build.yaml b/data/buildx/docker_buildx_build.yaml index b2591eb1552..b1dc9c44de0 100644 --- a/data/buildx/docker_buildx_build.yaml +++ b/data/buildx/docker_buildx_build.yaml @@ -1115,7 +1115,7 @@ examples: |- ```dockerfile # syntax=docker/dockerfile:1 - FROM oven/bun:1 as base + FROM oven/bun:1 AS base WORKDIR /app FROM base AS install @@ -1401,17 +1401,39 @@ examples: |- Supported types are: - - [`file`](#file) - - [`env`](#env) + - [`type=file`](#typefile) + - [`type=env`](#typeenv) - Buildx attempts to detect the `type` automatically if unset. + Buildx attempts to detect the `type` automatically if unset. If an environment + variable with the same key as `id` is set, then Buildx uses `type=env` and the + variable value becomes the secret. If no such environment variable is set, and + `type` is not set, then Buildx falls back to `type=file`. - #### `file` + #### `type=file` - Attribute keys: + Source a build secret from a file. + + ##### `type=file` synopsis + + ```console + $ docker buildx build --secret [type=file,]id=[,src=] . + ``` + + ##### `type=file` attributes + + | Key | Description | Default | + | --------------- | ----------------------------------------------------------------------------------------------------- | -------------------------- | + | `id` | ID of the secret. | N/A (this key is required) | + | `src`, `source` | Filepath of the file containing the secret value (absolute or relative to current working directory). | `id` if unset. | + + ###### `type=file` usage - - `id` - ID of the secret. Defaults to base name of the `src` path. - - `src`, `source` - Secret filename. `id` used if unset. + In the following example, `type=file` is automatically detected because no + environment variable mathing `aws` (the ID) is set. + + ```console + $ docker buildx build --secret id=aws,src=$HOME/.aws/credentials . + ``` ```dockerfile # syntax=docker/dockerfile:1 @@ -1421,16 +1443,31 @@ examples: |- aws s3 cp s3://... ... ``` + #### `type=env` + + Source a build secret from an environment variable. + + ##### `type=env` synopsis + ```console - $ docker buildx build --secret id=aws,src=$HOME/.aws/credentials . + $ docker buildx build --secret [type=env,]id=[,env=] . ``` - #### `env` + ##### `type=env` attributes - Attribute keys: + | Key | Description | Default | + | ---------------------- | ----------------------------------------------- | -------------------------- | + | `id` | ID of the secret. | N/A (this key is required) | + | `env`, `src`, `source` | Environment variable to source the secret from. | `id` if unset. | + + ##### `type=env` usage + + In the following example, `type=env` is automatically detected because an + environment variable matching `id` is set. - - `id` - ID of the secret. Defaults to `env` name. - - `env` - Secret environment variable. `id` used if unset, otherwise will look for `src`, `source` if `id` unset. + ```console + $ SECRET_TOKEN=token docker buildx build --secret id=SECRET_TOKEN . + ``` ```dockerfile # syntax=docker/dockerfile:1 @@ -1440,10 +1477,26 @@ examples: |- yarn run test ``` + In the following example, the build argument `SECRET_TOKEN` is set to contain + the value of the environment variable `API_KEY`. + ```console - $ SECRET_TOKEN=token docker buildx build --secret id=SECRET_TOKEN . + $ API_KEY=token docker buildx build --secret id=SECRET_TOKEN,env=API_KEY . ``` + You can also specify the name of the environment variable with `src` or `source`: + + ```console + $ API_KEY=token docker buildx build --secret type=env,id=SECRET_TOKEN,src=API_KEY . + ``` + + > [!NOTE] + > Specifying the environment variable name with `src` or `source`, you are + > required to set `type=env` explicitly, or else Buildx assumes that the secret + > is `type=file`, and looks for a file with the name of `src` or `source` (in + > this case, a file named `API_KEY` relative to the location where the `docker + > buildx build` command was executed. + ### Shared memory size for build containers (--shm-size) {#shm-size} Sets the size of the shared memory allocated for build containers when using diff --git a/data/buildx/docker_buildx_imagetools.yaml b/data/buildx/docker_buildx_imagetools.yaml index 7f1aef52926..a4aa11744a9 100644 --- a/data/buildx/docker_buildx_imagetools.yaml +++ b/data/buildx/docker_buildx_imagetools.yaml @@ -4,6 +4,7 @@ long: |- The `imagetools` commands contains subcommands for working with manifest lists in container registries. These commands are useful for inspecting manifests to check multi-platform configuration and attestations. +usage: docker buildx imagetools pname: docker buildx plink: docker_buildx.yaml cname: diff --git a/data/buildx/docker_buildx_ls.yaml b/data/buildx/docker_buildx_ls.yaml index ec394139496..29cdd2ceb5d 100644 --- a/data/buildx/docker_buildx_ls.yaml +++ b/data/buildx/docker_buildx_ls.yaml @@ -39,6 +39,16 @@ options: experimentalcli: false kubernetes: false swarm: false + - option: no-trunc + value_type: bool + default_value: "false" + description: Don't truncate output + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false inherited_options: - option: debug shorthand: D diff --git a/data/buildx/docker_buildx_prune.yaml b/data/buildx/docker_buildx_prune.yaml index a31e9caea43..9accff771c2 100644 --- a/data/buildx/docker_buildx_prune.yaml +++ b/data/buildx/docker_buildx_prune.yaml @@ -57,6 +57,36 @@ options: value_type: bytes default_value: "0" description: Amount of disk space to keep for cache + deprecated: true + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: max-used-space + value_type: bytes + default_value: "0" + description: Maximum amount of disk space allowed to keep for cache + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: min-free-space + value_type: bytes + default_value: "0" + description: Target amount of free disk space after pruning + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: reserved-space + value_type: bytes + default_value: "0" + description: Amount of disk space always allowed to keep for cache deprecated: false hidden: false experimental: false diff --git a/data/desktop-cli/docker_desktop.yaml b/data/desktop-cli/docker_desktop.yaml new file mode 100644 index 00000000000..a222a240064 --- /dev/null +++ b/data/desktop-cli/docker_desktop.yaml @@ -0,0 +1,24 @@ +command: docker desktop +short: Docker Desktop +long: Control Docker Desktop from the CLI +usage: docker desktop +pname: docker +plink: docker.yaml +cname: + - docker desktop start + - docker desktop stop + - docker desktop restart + - docker desktop status + - docker desktop engine +clink: + - docker_desktop_start.yaml + - docker_desktop_stop.yaml + - docker_desktop_restart.yaml + - docker_desktop_status.yaml + - docker_desktop_engine.yaml +deprecated: false +hidden: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false \ No newline at end of file diff --git a/data/desktop-cli/docker_desktop_engine.yaml b/data/desktop-cli/docker_desktop_engine.yaml new file mode 100644 index 00000000000..86295164a62 --- /dev/null +++ b/data/desktop-cli/docker_desktop_engine.yaml @@ -0,0 +1,17 @@ +command: docker desktop engine +short: Commands to list and switch containers (Windows only) +usage: docker desktop engine +pname: docker desktop +plink: docker_desktop.yaml +cname: + - docker desktop engine ls + - docker desktop engine use +clink: + - docker_desktop_engine_ls.yaml + - docker_desktop_engine_use.yaml +deprecated: false +hidden: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false \ No newline at end of file diff --git a/data/desktop-cli/docker_desktop_engine_ls.yaml b/data/desktop-cli/docker_desktop_engine_ls.yaml new file mode 100644 index 00000000000..52a1012d06d --- /dev/null +++ b/data/desktop-cli/docker_desktop_engine_ls.yaml @@ -0,0 +1,11 @@ +command: docker desktop engine ls +short: List available engines (Windows only) +usage: docker desktop engine ls +pname: docker desktop engine +plink: docker_desktop_engine.yaml +deprecated: false +hidden: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false \ No newline at end of file diff --git a/data/desktop-cli/docker_desktop_engine_use.yaml b/data/desktop-cli/docker_desktop_engine_use.yaml new file mode 100644 index 00000000000..e289519506c --- /dev/null +++ b/data/desktop-cli/docker_desktop_engine_use.yaml @@ -0,0 +1,11 @@ +command: docker desktop engine use +short: Switch to Windows or Linux containers (Windows only) +usage: docker desktop engine use NAME +pname: docker desktop engine +plink: docker_desktop_engine.yaml +deprecated: false +hidden: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false \ No newline at end of file diff --git a/data/desktop-cli/docker_desktop_restart.yaml b/data/desktop-cli/docker_desktop_restart.yaml new file mode 100644 index 00000000000..4809ede1544 --- /dev/null +++ b/data/desktop-cli/docker_desktop_restart.yaml @@ -0,0 +1,11 @@ +command: docker desktop restart +short: Restart Docker Desktop +usage: docker desktop restart +pname: docker desktop +plink: docker_desktop.yaml +deprecated: false +hidden: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false \ No newline at end of file diff --git a/data/desktop-cli/docker_desktop_start.yaml b/data/desktop-cli/docker_desktop_start.yaml new file mode 100644 index 00000000000..3422aa8873d --- /dev/null +++ b/data/desktop-cli/docker_desktop_start.yaml @@ -0,0 +1,32 @@ +command: docker desktop start +short: Start Docker Desktop +usage: docker desktop start [OPTIONS] +pname: docker desktop +plink: docker_desktop.yaml +options: + - option: detach + value_type: bool + default_value: false + description: Start Docker Desktop in the background + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: timeout + value_type: init + default_value: 0 + description: Specify in seconds how long to wait for Docker Desktop to start before timing out + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +deprecated: false +hidden: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false diff --git a/data/desktop-cli/docker_desktop_status.yaml b/data/desktop-cli/docker_desktop_status.yaml new file mode 100644 index 00000000000..e69a46a6e17 --- /dev/null +++ b/data/desktop-cli/docker_desktop_status.yaml @@ -0,0 +1,11 @@ +command: docker desktop status +short: Display Docker Desktop's status +usage: docker desktop status +pname: docker desktop +plink: docker_desktop.yaml +deprecated: false +hidden: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false \ No newline at end of file diff --git a/data/desktop-cli/docker_desktop_stop.yaml b/data/desktop-cli/docker_desktop_stop.yaml new file mode 100644 index 00000000000..e0b775a4e6f --- /dev/null +++ b/data/desktop-cli/docker_desktop_stop.yaml @@ -0,0 +1,41 @@ +command: docker desktop stop +short: Stop Docker Desktop +usage: docker desktop stop [OPTIONS] +pname: docker desktop +plink: docker_desktop.yaml +options: + - option: detach + value_type: bool + default_value: false + description: Stop Docker Desktop in the background + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: force + value_type: bool + default_value: false + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: timeout + value_type: init + default_value: 0 + description: Specify in seconds how long to wait for Docker Desktop to stop before timing out + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +deprecated: false +hidden: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false \ No newline at end of file diff --git a/data/engine-cli/docker_container_prune.yaml b/data/engine-cli/docker_container_prune.yaml index e6031d90813..c595b3e6f86 100644 --- a/data/engine-cli/docker_container_prune.yaml +++ b/data/engine-cli/docker_container_prune.yaml @@ -62,7 +62,7 @@ examples: |- * label (`label=`, `label==`, `label!=`, or `label!==`) - only remove containers with (or without, in case `label!=...` is used) the specified labels. The `until` filter can be Unix timestamps, date formatted - timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed + timestamps, or Go duration strings supported by [ParseDuration](https://pkg.go.dev/time#ParseDuration) (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time. Supported formats for date formatted time stamps include RFC3339Nano, RFC3339, `2006-01-02T15:04:05`, `2006-01-02T15:04:05.999999999`, `2006-01-02T07:00`, and `2006-01-02`. The local diff --git a/data/engine-cli/docker_container_restart.yaml b/data/engine-cli/docker_container_restart.yaml index 2b9a97c183e..464e1454ae3 100644 --- a/data/engine-cli/docker_container_restart.yaml +++ b/data/engine-cli/docker_container_restart.yaml @@ -10,6 +10,7 @@ options: shorthand: s value_type: string description: Signal to send to the container + details_url: '#signal' deprecated: false hidden: false experimental: false @@ -21,6 +22,7 @@ options: value_type: int default_value: "0" description: Seconds to wait before killing the container + details_url: '#time' deprecated: false hidden: false experimental: false @@ -42,6 +44,37 @@ examples: |- ```console $ docker restart my_container ``` + + + ### Stop container with signal (-s, --signal) {#signal} + + The `--signal` flag sends the system call signal to the container to exit. + This signal can be a signal name in the format `SIG`, for instance + `SIGKILL`, or an unsigned number that matches a position in the kernel's + syscall table, for instance `9`. Refer to [signal(7)](https://man7.org/linux/man-pages/man7/signal.7.html) + for available signals. + + The default signal to use is defined by the image's [`StopSignal`](https://github.com/opencontainers/image-spec/blob/v1.1.0/config.md), + which can be set through the [`STOPSIGNAL`](/reference/dockerfile/#stopsignal) + Dockerfile instruction when building the image, or configured using the + [`--stop-signal`](/reference/cli/docker/container/run/#stop-signal) + option when creating the container. If no signal is configured for the + container, `SIGTERM` is used as default. + + ### Stop container with timeout (-t, --timeout) {#time} + + The `--time` flag sets the number of seconds to wait for the container + to stop after sending the pre-defined (see [`--signal`]{#signal)) system call signal. + If the container does not exit after the timeout elapses, it's forcibly killed + with a `SIGKILL` signal. + + If you set `--time` to `-1`, no timeout is applied, and the daemon + waits indefinitely for the container to exit. + + The default timeout can be specified using the [`--stop-timeout`](/reference/cli/docker/container/run/#stop-timeout) + option when creating the container. If no default is configured for the container, + the Daemon determines the default, and is 10 seconds for Linux containers, and + 30 seconds for Windows containers. deprecated: false hidden: false experimental: false diff --git a/data/engine-cli/docker_container_run.yaml b/data/engine-cli/docker_container_run.yaml index 6070800032a..0312bce2776 100644 --- a/data/engine-cli/docker_container_run.yaml +++ b/data/engine-cli/docker_container_run.yaml @@ -2126,12 +2126,12 @@ examples: |- policy controls whether the Docker daemon restarts a container after exit. Docker supports the following restart policies: - | Policy | Result | - |:---------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| - | `no` | Do not automatically restart the container when it exits. This is the default. | - | `on-failure[:max-retries]` | Restart only if the container exits with a non-zero exit status. Optionally, limit the number of restart retries the Docker daemon attempts. | - | `unless-stopped` | Restart the container unless it's explicitly stopped or Docker itself is stopped or restarted. | - | `always` | Always restart the container regardless of the exit status. When you specify always, the Docker daemon tries to restart the container indefinitely. The container always starts on daemon startup, regardless of the current state of the container. | + | Flag | Description | + | :------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | + | `no` | Don't automatically restart the container. (Default) | + | `on-failure[:max-retries]` | Restart the container if it exits due to an error, which manifests as a non-zero exit code. Optionally, limit the number of times the Docker daemon attempts to restart the container using the `:max-retries` option. The `on-failure` policy only prompts a restart if the container exits with a failure. It doesn't restart the container if the daemon restarts. | + | `always` | Always restart the container if it stops. If it's manually stopped, it's restarted only when Docker daemon restarts or the container itself is manually restarted. | + | `unless-stopped` | Similar to `always`, except that when the container is stopped (manually or otherwise), it isn't restarted even after Docker daemon restarts. | ```console $ docker run --restart=always redis @@ -2252,7 +2252,7 @@ examples: |- It's conventional to use `host.docker.internal` as the hostname referring to `host-gateway`. Docker Desktop automatically resolves this hostname, see - [Explore networking features](/desktop/networking/#i-want-to-connect-from-a-container-to-a-service-on-the-host). + [Explore networking features](/desktop/features/networking/#i-want-to-connect-from-a-container-to-a-service-on-the-host). The following example shows how the special `host-gateway` value works. The example runs an HTTP server that serves a file from host to container over the diff --git a/data/engine-cli/docker_container_stop.yaml b/data/engine-cli/docker_container_stop.yaml index 13b9e613ced..77c07cab639 100644 --- a/data/engine-cli/docker_container_stop.yaml +++ b/data/engine-cli/docker_container_stop.yaml @@ -5,7 +5,7 @@ long: |- The main process inside the container will receive `SIGTERM`, and after a grace period, `SIGKILL`. The first signal can be changed with the `STOPSIGNAL` instruction in the container's Dockerfile, or the `--stop-signal` option to - `docker run`. + `docker run` and `docker create`. usage: docker container stop [OPTIONS] CONTAINER [CONTAINER...] pname: docker container plink: docker_container.yaml @@ -14,6 +14,7 @@ options: shorthand: s value_type: string description: Signal to send to the container + details_url: '#signal' deprecated: false hidden: false experimental: false @@ -25,6 +26,7 @@ options: value_type: int default_value: "0" description: Seconds to wait before killing the container + details_url: '#time' deprecated: false hidden: false experimental: false @@ -46,6 +48,36 @@ examples: |- ```console $ docker stop my_container ``` + + ### Stop container with signal (-s, --signal) {#signal} + + The `--signal` flag sends the system call signal to the container to exit. + This signal can be a signal name in the format `SIG`, for instance + `SIGKILL`, or an unsigned number that matches a position in the kernel's + syscall table, for instance `9`. Refer to [signal(7)](https://man7.org/linux/man-pages/man7/signal.7.html) + for available signals. + + The default signal to use is defined by the image's [`StopSignal`](https://github.com/opencontainers/image-spec/blob/v1.1.0/config.md), + which can be set through the [`STOPSIGNAL`](/reference/dockerfile/#stopsignal) + Dockerfile instruction when building the image, or configured using the + [`--stop-signal`](/reference/cli/docker/container/run/#stop-signal) + option when creating the container. If no signal is configured for the + container, `SIGTERM` is used as default. + + ### Stop container with timeout (-t, --timeout) {#time} + + The `--time` flag sets the number of seconds to wait for the container + to stop after sending the pre-defined (see [`--signal`]{#signal)) system call signal. + If the container does not exit after the timeout elapses, it's forcibly killed + with a `SIGKILL` signal. + + If you set `--time` to `-1`, no timeout is applied, and the daemon + waits indefinitely for the container to exit. + + The default timeout can be specified using the [`--stop-timeout`](/reference/cli/docker/container/run/#stop-timeout) + option when creating the container. If no default is configured for the container, + the Daemon determines the default, and is 10 seconds for Linux containers, and + 30 seconds for Windows containers. deprecated: false hidden: false experimental: false diff --git a/data/engine-cli/docker_image_build.yaml b/data/engine-cli/docker_image_build.yaml index 24523a92b6a..7f626cef86e 100644 --- a/data/engine-cli/docker_image_build.yaml +++ b/data/engine-cli/docker_image_build.yaml @@ -2,7 +2,7 @@ command: docker image build aliases: docker image build, docker build, docker builder build short: Build an image from a Dockerfile long: |- - > [!NOTE] + > [!IMPORTANT] > This page refers to the **legacy implementation** of `docker build`, > using the legacy (pre-BuildKit) build backend. > This configuration is only relevant if you're building Windows containers. diff --git a/data/engine-cli/docker_image_prune.yaml b/data/engine-cli/docker_image_prune.yaml index e69dc4b9383..2cae8c59072 100644 --- a/data/engine-cli/docker_image_prune.yaml +++ b/data/engine-cli/docker_image_prune.yaml @@ -96,7 +96,7 @@ examples: |- * label (`label=`, `label==`, `label!=`, or `label!==`) - only remove images with (or without, in case `label!=...` is used) the specified labels. The `until` filter can be Unix timestamps, date formatted - timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed + timestamps, or Go duration strings supported by [ParseDuration](https://pkg.go.dev/time#ParseDuration) (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time. Supported formats for date formatted time stamps include RFC3339Nano, RFC3339, `2006-01-02T15:04:05`, `2006-01-02T15:04:05.999999999`, `2006-01-02T07:00`, and `2006-01-02`. The local diff --git a/data/engine-cli/docker_network_prune.yaml b/data/engine-cli/docker_network_prune.yaml index b291f37a864..01b9e8ff9a5 100644 --- a/data/engine-cli/docker_network_prune.yaml +++ b/data/engine-cli/docker_network_prune.yaml @@ -61,7 +61,7 @@ examples: |- * label (`label=`, `label==`, `label!=`, or `label!==`) - only remove networks with (or without, in case `label!=...` is used) the specified labels. The `until` filter can be Unix timestamps, date formatted - timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed + timestamps, or Go duration strings supported by [ParseDuration](https://pkg.go.dev/time#ParseDuration) (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time. Supported formats for date formatted time stamps include RFC3339Nano, RFC3339, `2006-01-02T15:04:05`, `2006-01-02T15:04:05.999999999`, `2006-01-02T07:00`, and `2006-01-02`. The local diff --git a/data/engine-cli/docker_node_ps.yaml b/data/engine-cli/docker_node_ps.yaml index a689d091a9e..dfb13ba296e 100644 --- a/data/engine-cli/docker_node_ps.yaml +++ b/data/engine-cli/docker_node_ps.yaml @@ -82,11 +82,11 @@ examples: |- $ docker node ps swarm-manager1 NAME IMAGE NODE DESIRED STATE CURRENT STATE - redis.1.7q92v0nr1hcgts2amcjyqg3pq redis:3.0.6 swarm-manager1 Running Running 5 hours - redis.6.b465edgho06e318egmgjbqo4o redis:3.0.6 swarm-manager1 Running Running 29 seconds - redis.7.bg8c07zzg87di2mufeq51a2qp redis:3.0.6 swarm-manager1 Running Running 5 seconds - redis.9.dkkual96p4bb3s6b10r7coxxt redis:3.0.6 swarm-manager1 Running Running 5 seconds - redis.10.0tgctg8h8cech4w0k0gwrmr23 redis:3.0.6 swarm-manager1 Running Running 5 seconds + redis.1.7q92v0nr1hcgts2amcjyqg3pq redis:7.4.1 swarm-manager1 Running Running 5 hours + redis.6.b465edgho06e318egmgjbqo4o redis:7.4.1 swarm-manager1 Running Running 29 seconds + redis.7.bg8c07zzg87di2mufeq51a2qp redis:7.4.1 swarm-manager1 Running Running 5 seconds + redis.9.dkkual96p4bb3s6b10r7coxxt redis:7.4.1 swarm-manager1 Running Running 5 seconds + redis.10.0tgctg8h8cech4w0k0gwrmr23 redis:7.4.1 swarm-manager1 Running Running 5 seconds ``` ### Filtering (--filter) {#filter} @@ -112,11 +112,11 @@ examples: |- $ docker node ps -f name=redis swarm-manager1 NAME IMAGE NODE DESIRED STATE CURRENT STATE - redis.1.7q92v0nr1hcgts2amcjyqg3pq redis:3.0.6 swarm-manager1 Running Running 5 hours - redis.6.b465edgho06e318egmgjbqo4o redis:3.0.6 swarm-manager1 Running Running 29 seconds - redis.7.bg8c07zzg87di2mufeq51a2qp redis:3.0.6 swarm-manager1 Running Running 5 seconds - redis.9.dkkual96p4bb3s6b10r7coxxt redis:3.0.6 swarm-manager1 Running Running 5 seconds - redis.10.0tgctg8h8cech4w0k0gwrmr23 redis:3.0.6 swarm-manager1 Running Running 5 seconds + redis.1.7q92v0nr1hcgts2amcjyqg3pq redis:7.4.1 swarm-manager1 Running Running 5 hours + redis.6.b465edgho06e318egmgjbqo4o redis:7.4.1 swarm-manager1 Running Running 29 seconds + redis.7.bg8c07zzg87di2mufeq51a2qp redis:7.4.1 swarm-manager1 Running Running 5 seconds + redis.9.dkkual96p4bb3s6b10r7coxxt redis:7.4.1 swarm-manager1 Running Running 5 seconds + redis.10.0tgctg8h8cech4w0k0gwrmr23 redis:7.4.1 swarm-manager1 Running Running 5 seconds ``` #### id @@ -127,7 +127,7 @@ examples: |- $ docker node ps -f id=bg8c07zzg87di2mufeq51a2qp swarm-manager1 NAME IMAGE NODE DESIRED STATE CURRENT STATE - redis.7.bg8c07zzg87di2mufeq51a2qp redis:3.0.6 swarm-manager1 Running Running 5 seconds + redis.7.bg8c07zzg87di2mufeq51a2qp redis:7.4.1 swarm-manager1 Running Running 5 seconds ``` #### label @@ -141,8 +141,8 @@ examples: |- $ docker node ps -f "label=usage" NAME IMAGE NODE DESIRED STATE CURRENT STATE - redis.6.b465edgho06e318egmgjbqo4o redis:3.0.6 swarm-manager1 Running Running 10 minutes - redis.7.bg8c07zzg87di2mufeq51a2qp redis:3.0.6 swarm-manager1 Running Running 9 minutes + redis.6.b465edgho06e318egmgjbqo4o redis:7.4.1 swarm-manager1 Running Running 10 minutes + redis.7.bg8c07zzg87di2mufeq51a2qp redis:7.4.1 swarm-manager1 Running Running 9 minutes ``` diff --git a/data/engine-cli/docker_service_create.yaml b/data/engine-cli/docker_service_create.yaml index 09bc67f5cc9..4a88cdc0f11 100644 --- a/data/engine-cli/docker_service_create.yaml +++ b/data/engine-cli/docker_service_create.yaml @@ -787,19 +787,19 @@ examples: |- ### Create a service ```console - $ docker service create --name redis redis:3.0.6 + $ docker service create --name redis redis:7.4.1 dmu1ept4cxcfe8k8lhtux3ro3 - $ docker service create --mode global --name redis2 redis:3.0.6 + $ docker service create --mode global --name redis2 redis:7.4.1 a8q9dasaafudfs8q8w32udass $ docker service ls ID NAME MODE REPLICAS IMAGE - dmu1ept4cxcf redis replicated 1/1 redis:3.0.6 - a8q9dasaafud redis2 global 1/1 redis:3.0.6 + dmu1ept4cxcf redis replicated 1/1 redis:7.4.1 + a8q9dasaafud redis2 global 1/1 redis:7.4.1 ``` #### Create a service using an image on a private registry (--with-registry-auth) {#with-registry-auth} @@ -828,7 +828,7 @@ examples: |- service. The following command creates a `redis` service with `5` replica tasks: ```console - $ docker service create --name redis --replicas=5 redis:3.0.6 + $ docker service create --name redis --replicas=5 redis:7.4.1 4cdgfyky7ozwh3htjfw0d12qv ``` @@ -845,7 +845,7 @@ examples: |- $ docker service ls ID NAME MODE REPLICAS IMAGE - 4cdgfyky7ozw redis replicated 3/5 redis:3.0.7 + 4cdgfyky7ozw redis replicated 3/5 redis:7.4.1 ``` Once all the tasks are created and `RUNNING`, the actual number of tasks is @@ -855,7 +855,7 @@ examples: |- $ docker service ls ID NAME MODE REPLICAS IMAGE - 4cdgfyky7ozw redis replicated 5/5 redis:3.0.7 + 4cdgfyky7ozw redis replicated 5/5 redis:7.4.1 ``` ### Create a service with secrets (--secret) {#secret} @@ -866,7 +866,7 @@ examples: |- Create a service specifying a secret: ```console - $ docker service create --name redis --secret secret.json redis:3.0.6 + $ docker service create --name redis --secret secret.json redis:7.4.1 4cdgfyky7ozwh3htjfw0d12qv ``` @@ -877,7 +877,7 @@ examples: |- $ docker service create --name redis \ --secret source=ssh-key,target=ssh \ --secret source=app-key,target=app,uid=1000,gid=1001,mode=0400 \ - redis:3.0.6 + redis:7.4.1 4cdgfyky7ozwh3htjfw0d12qv ``` @@ -903,14 +903,14 @@ examples: |- as `0755`. ```console - $ docker service create --name=redis --config redis-conf redis:3.0.6 + $ docker service create --name=redis --config redis-conf redis:7.4.1 ``` Create a service with a config and specify the target location and file mode: ```console $ docker service create --name redis \ - --config source=redis-conf,target=/etc/redis/redis.conf,mode=0400 redis:3.0.6 + --config source=redis-conf,target=/etc/redis/redis.conf,mode=0400 redis:7.4.1 ``` To grant a service access to multiple configs, use multiple `--config` flags. @@ -927,7 +927,7 @@ examples: |- --name redis \ --update-delay 10s \ --update-parallelism 2 \ - redis:3.0.6 + redis:7.4.1 ``` When you run a [service update](/reference/cli/docker/service/update/), the scheduler updates a @@ -944,7 +944,7 @@ examples: |- --name redis_2 \ --replicas 5 \ --env MYVAR=foo \ - redis:3.0.6 + redis:7.4.1 ``` To specify multiple environment variables, specify multiple `--env` flags, each @@ -956,7 +956,7 @@ examples: |- --replicas 5 \ --env MYVAR=foo \ --env MYVAR2=bar \ - redis:3.0.6 + redis:7.4.1 ``` ### Create a service with specific hostname (--hostname) {#hostname} @@ -965,7 +965,7 @@ examples: |- For example: ```console - $ docker service create --name redis --hostname myredis redis:3.0.6 + $ docker service create --name redis --hostname myredis redis:7.4.1 ``` ### Set metadata on a service (-l, --label) {#label} @@ -978,7 +978,7 @@ examples: |- --name redis_2 \ --label com.example.foo="bar" \ --label bar=baz \ - redis:3.0.6 + redis:7.4.1 ``` For more information about labels, refer to [apply custom @@ -1367,7 +1367,7 @@ examples: |- $ docker service create \ --name redis_2 \ --mode global \ - redis:3.0.6 + redis:7.4.1 ``` ### Specify service constraints (--constraint) {#constraint} @@ -1400,7 +1400,7 @@ examples: |- --name redis_2 \ --constraint node.platform.os==linux \ --constraint node.labels.type==queue \ - redis:3.0.6 + redis:7.4.1 ``` If the service constraints exclude all nodes in the cluster, a message is printed @@ -1448,7 +1448,7 @@ examples: |- --replicas 9 \ --name redis_2 \ --placement-pref spread=node.labels.datacenter \ - redis:3.0.6 + redis:7.4.1 ``` This uses `--placement-pref` with a `spread` strategy (currently the only @@ -1500,7 +1500,7 @@ examples: |- --name redis_2 \ --placement-pref 'spread=node.labels.datacenter' \ --placement-pref 'spread=node.labels.rack' \ - redis:3.0.6 + redis:7.4.1 ``` When updating a service with `docker service update`, `--placement-pref-add` diff --git a/data/engine-cli/docker_service_inspect.yaml b/data/engine-cli/docker_service_inspect.yaml index 38f7f4b4fc6..33a835305f8 100644 --- a/data/engine-cli/docker_service_inspect.yaml +++ b/data/engine-cli/docker_service_inspect.yaml @@ -65,7 +65,7 @@ examples: |- ```console $ docker service ls ID NAME MODE REPLICAS IMAGE - dmu1ept4cxcf redis replicated 3/3 redis:3.0.6 + dmu1ept4cxcf redis replicated 3/3 redis:7.4.1 ``` Both `docker service inspect redis`, and `docker service inspect dmu1ept4cxcf` @@ -90,7 +90,7 @@ examples: |- "Name": "redis", "TaskTemplate": { "ContainerSpec": { - "Image": "redis:3.0.6" + "Image": "redis:7.4.1" }, "Resources": { "Limits": {}, diff --git a/data/engine-cli/docker_service_ls.yaml b/data/engine-cli/docker_service_ls.yaml index 2a4d3f4e1fd..0731f5bc3b1 100644 --- a/data/engine-cli/docker_service_ls.yaml +++ b/data/engine-cli/docker_service_ls.yaml @@ -70,7 +70,7 @@ examples: |- ID NAME MODE REPLICAS IMAGE c8wgl7q4ndfd frontend replicated 5/5 nginx:alpine - dmu1ept4cxcf redis replicated 3/3 redis:3.0.6 + dmu1ept4cxcf redis replicated 3/3 redis:7.4.1 iwe3278osahj mongo global 7/7 mongo:3.3 hh08h9uu8uwr job replicated-job 1/1 (3/5 completed) nginx:latest ``` @@ -101,7 +101,7 @@ examples: |- ```console $ docker service ls -f "id=0bcjw" ID NAME MODE REPLICAS IMAGE - 0bcjwfh8ychr redis replicated 1/1 redis:3.0.6 + 0bcjwfh8ychr redis replicated 1/1 redis:7.4.1 ``` #### label @@ -117,7 +117,7 @@ examples: |- ID NAME MODE REPLICAS IMAGE 01sl1rp6nj5u frontend2 replicated 1/1 nginx:alpine 36xvvwwauej0 frontend replicated 5/5 nginx:alpine - 74nzcxxjv6fq backend replicated 3/3 redis:3.0.6 + 74nzcxxjv6fq backend replicated 3/3 redis:7.4.1 ``` The following filter matches only services with the `project` label with the @@ -127,7 +127,7 @@ examples: |- $ docker service ls --filter label=project=project-a ID NAME MODE REPLICAS IMAGE 36xvvwwauej0 frontend replicated 5/5 nginx:alpine - 74nzcxxjv6fq backend replicated 3/3 redis:3.0.6 + 74nzcxxjv6fq backend replicated 3/3 redis:7.4.1 ``` #### mode @@ -151,7 +151,7 @@ examples: |- ```console $ docker service ls --filter name=redis ID NAME MODE REPLICAS IMAGE - 0bcjwfh8ychr redis replicated 1/1 redis:3.0.6 + 0bcjwfh8ychr redis replicated 1/1 redis:7.4.1 ``` ### Format the output (--format) {#format} diff --git a/data/engine-cli/docker_service_ps.yaml b/data/engine-cli/docker_service_ps.yaml index c75f16dc224..74aa851e76d 100644 --- a/data/engine-cli/docker_service_ps.yaml +++ b/data/engine-cli/docker_service_ps.yaml @@ -84,35 +84,35 @@ examples: |- $ docker service ps redis ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS - 0qihejybwf1x redis.1 redis:3.0.5 manager1 Running Running 8 seconds - bk658fpbex0d redis.2 redis:3.0.5 worker2 Running Running 9 seconds - 5ls5s5fldaqg redis.3 redis:3.0.5 worker1 Running Running 9 seconds - 8ryt076polmc redis.4 redis:3.0.5 worker1 Running Running 9 seconds - 1x0v8yomsncd redis.5 redis:3.0.5 manager1 Running Running 8 seconds - 71v7je3el7rr redis.6 redis:3.0.5 worker2 Running Running 9 seconds - 4l3zm9b7tfr7 redis.7 redis:3.0.5 worker2 Running Running 9 seconds - 9tfpyixiy2i7 redis.8 redis:3.0.5 worker1 Running Running 9 seconds - 3w1wu13yupln redis.9 redis:3.0.5 manager1 Running Running 8 seconds - 8eaxrb2fqpbn redis.10 redis:3.0.5 manager1 Running Running 8 seconds + 0qihejybwf1x redis.1 redis:7.4.0 manager1 Running Running 8 seconds + bk658fpbex0d redis.2 redis:7.4.0 worker2 Running Running 9 seconds + 5ls5s5fldaqg redis.3 redis:7.4.0 worker1 Running Running 9 seconds + 8ryt076polmc redis.4 redis:7.4.0 worker1 Running Running 9 seconds + 1x0v8yomsncd redis.5 redis:7.4.0 manager1 Running Running 8 seconds + 71v7je3el7rr redis.6 redis:7.4.0 worker2 Running Running 9 seconds + 4l3zm9b7tfr7 redis.7 redis:7.4.0 worker2 Running Running 9 seconds + 9tfpyixiy2i7 redis.8 redis:7.4.0 worker1 Running Running 9 seconds + 3w1wu13yupln redis.9 redis:7.4.0 manager1 Running Running 8 seconds + 8eaxrb2fqpbn redis.10 redis:7.4.0 manager1 Running Running 8 seconds ``` In addition to running tasks, the output also shows the task history. For - example, after updating the service to use the `redis:3.0.6` image, the output + example, after updating the service to use the `redis:7.4.1` image, the output may look like this: ```console $ docker service ps redis ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS - 50qe8lfnxaxk redis.1 redis:3.0.6 manager1 Running Running 6 seconds ago - ky2re9oz86r9 \_ redis.1 redis:3.0.5 manager1 Shutdown Shutdown 8 seconds ago - 3s46te2nzl4i redis.2 redis:3.0.6 worker2 Running Running less than a second ago - nvjljf7rmor4 \_ redis.2 redis:3.0.6 worker2 Shutdown Rejected 23 seconds ago "No such image: redis@sha256:6…" - vtiuz2fpc0yb \_ redis.2 redis:3.0.5 worker2 Shutdown Shutdown 1 second ago - jnarweeha8x4 redis.3 redis:3.0.6 worker1 Running Running 3 seconds ago - vs448yca2nz4 \_ redis.3 redis:3.0.5 worker1 Shutdown Shutdown 4 seconds ago - jf1i992619ir redis.4 redis:3.0.6 worker1 Running Running 10 seconds ago - blkttv7zs8ee \_ redis.4 redis:3.0.5 worker1 Shutdown Shutdown 11 seconds ago + 50qe8lfnxaxk redis.1 redis:7.4.1 manager1 Running Running 6 seconds ago + ky2re9oz86r9 \_ redis.1 redis:7.4.0 manager1 Shutdown Shutdown 8 seconds ago + 3s46te2nzl4i redis.2 redis:7.4.1 worker2 Running Running less than a second ago + nvjljf7rmor4 \_ redis.2 redis:7.4.1 worker2 Shutdown Rejected 23 seconds ago "No such image: redis@sha256:6…" + vtiuz2fpc0yb \_ redis.2 redis:7.4.0 worker2 Shutdown Shutdown 1 second ago + jnarweeha8x4 redis.3 redis:7.4.1 worker1 Running Running 3 seconds ago + vs448yca2nz4 \_ redis.3 redis:7.4.0 worker1 Shutdown Shutdown 4 seconds ago + jf1i992619ir redis.4 redis:7.4.1 worker1 Running Running 10 seconds ago + blkttv7zs8ee \_ redis.4 redis:7.4.0 worker1 Shutdown Shutdown 11 seconds ago ``` The number of items in the task history is determined by the @@ -130,10 +130,10 @@ examples: |- $ docker service ps --no-trunc redis ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS - 50qe8lfnxaxksi9w2a704wkp7 redis.1 redis:3.0.6@sha256:6a692a76c2081888b589e26e6ec835743119fe453d67ecf03df7de5b73d69842 manager1 Running Running 5 minutes ago - ky2re9oz86r9556i2szb8a8af \_ redis.1 redis:3.0.5@sha256:f8829e00d95672c48c60f468329d6693c4bdd28d1f057e755f8ba8b40008682e worker2 Shutdown Shutdown 5 minutes ago - bk658fpbex0d57cqcwoe3jthu redis.2 redis:3.0.6@sha256:6a692a76c2081888b589e26e6ec835743119fe453d67ecf03df7de5b73d69842 worker2 Running Running 5 seconds - nvjljf7rmor4htv7l8rwcx7i7 \_ redis.2 redis:3.0.6@sha256:6a692a76c2081888b589e26e6ec835743119fe453d67ecf03df7de5b73d69842 worker2 Shutdown Rejected 5 minutes ago "No such image: redis@sha256:6a692a76c2081888b589e26e6ec835743119fe453d67ecf03df7de5b73d69842" + 50qe8lfnxaxksi9w2a704wkp7 redis.1 redis:7.4.1@sha256:6a692a76c2081888b589e26e6ec835743119fe453d67ecf03df7de5b73d69842 manager1 Running Running 5 minutes ago + ky2re9oz86r9556i2szb8a8af \_ redis.1 redis:7.4.0@sha256:f8829e00d95672c48c60f468329d6693c4bdd28d1f057e755f8ba8b40008682e worker2 Shutdown Shutdown 5 minutes ago + bk658fpbex0d57cqcwoe3jthu redis.2 redis:7.4.1@sha256:6a692a76c2081888b589e26e6ec835743119fe453d67ecf03df7de5b73d69842 worker2 Running Running 5 seconds + nvjljf7rmor4htv7l8rwcx7i7 \_ redis.2 redis:7.4.1@sha256:6a692a76c2081888b589e26e6ec835743119fe453d67ecf03df7de5b73d69842 worker2 Shutdown Rejected 5 minutes ago "No such image: redis@sha256:6a692a76c2081888b589e26e6ec835743119fe453d67ecf03df7de5b73d69842" ``` ### Filtering (--filter) {#filter} @@ -159,8 +159,8 @@ examples: |- $ docker service ps -f "id=8" redis ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS - 8ryt076polmc redis.4 redis:3.0.6 worker1 Running Running 9 seconds - 8eaxrb2fqpbn redis.10 redis:3.0.6 manager1 Running Running 8 seconds + 8ryt076polmc redis.4 redis:7.4.1 worker1 Running Running 9 seconds + 8eaxrb2fqpbn redis.10 redis:7.4.1 manager1 Running Running 8 seconds ``` #### name @@ -171,7 +171,7 @@ examples: |- $ docker service ps -f "name=redis.1" redis ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS - qihejybwf1x5 redis.1 redis:3.0.6 manager1 Running Running 8 seconds + qihejybwf1x5 redis.1 redis:7.4.1 manager1 Running Running 8 seconds ``` @@ -183,10 +183,10 @@ examples: |- $ docker service ps -f "node=manager1" redis ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS - 0qihejybwf1x redis.1 redis:3.0.6 manager1 Running Running 8 seconds - 1x0v8yomsncd redis.5 redis:3.0.6 manager1 Running Running 8 seconds - 3w1wu13yupln redis.9 redis:3.0.6 manager1 Running Running 8 seconds - 8eaxrb2fqpbn redis.10 redis:3.0.6 manager1 Running Running 8 seconds + 0qihejybwf1x redis.1 redis:7.4.1 manager1 Running Running 8 seconds + 1x0v8yomsncd redis.5 redis:7.4.1 manager1 Running Running 8 seconds + 3w1wu13yupln redis.9 redis:7.4.1 manager1 Running Running 8 seconds + 8eaxrb2fqpbn redis.10 redis:7.4.1 manager1 Running Running 8 seconds ``` #### desired-state diff --git a/data/engine-cli/docker_service_scale.yaml b/data/engine-cli/docker_service_scale.yaml index 7aac0d255db..6ac7ce86756 100644 --- a/data/engine-cli/docker_service_scale.yaml +++ b/data/engine-cli/docker_service_scale.yaml @@ -96,7 +96,7 @@ examples: |- ID NAME MODE REPLICAS IMAGE 3pr5mlvu3fh9 frontend replicated 5/5 nginx:alpine - 74nzcxxjv6fq backend replicated 3/3 redis:3.0.6 + 74nzcxxjv6fq backend replicated 3/3 redis:7.4.1 ``` deprecated: false hidden: false diff --git a/data/engine-cli/docker_system_events.yaml b/data/engine-cli/docker_system_events.yaml index 04199335445..eef3dccfe69 100644 --- a/data/engine-cli/docker_system_events.yaml +++ b/data/engine-cli/docker_system_events.yaml @@ -125,7 +125,7 @@ long: |- #### Limit events by time (--since, --until) {#since} The `--since` and `--until` parameters can be Unix timestamps, date formatted - timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed + timestamps, or Go duration strings supported by [ParseDuration](https://pkg.go.dev/time#ParseDuration) (e.g. `10m`, `1h30m`) computed relative to the client machine’s time. If you do not provide the `--since` option, the command returns only new and/or live events. Supported formats for date formatted time stamps include RFC3339Nano, RFC3339, `2006-01-02T15:04:05`, diff --git a/data/engine-cli/docker_system_prune.yaml b/data/engine-cli/docker_system_prune.yaml index ffa0df8f072..1ae98cdc2e6 100644 --- a/data/engine-cli/docker_system_prune.yaml +++ b/data/engine-cli/docker_system_prune.yaml @@ -144,7 +144,7 @@ examples: |- * label (`label=`, `label==`, `label!=`, or `label!==`) - only remove containers, images, networks, and volumes with (or without, in case `label!=...` is used) the specified labels. The `until` filter can be Unix timestamps, date formatted - timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed + timestamps, or Go duration strings supported by [ParseDuration](https://pkg.go.dev/time#ParseDuration) (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time. Supported formats for date formatted time stamps include RFC3339Nano, RFC3339, `2006-01-02T15:04:05`, `2006-01-02T15:04:05.999999999`, `2006-01-02T07:00`, and `2006-01-02`. The local diff --git a/data/redirects.yml b/data/redirects.yml index d3a3d121f46..cae91bfb671 100644 --- a/data/redirects.yml +++ b/data/redirects.yml @@ -88,7 +88,7 @@ "/desktop/use-desktop/pause/": - /go/mac-desktop-pause/ - /go/win-desktop-pause/ -"/desktop/settings/#file-sharing": +"/desktop/settings-and-maintenance/settings/#file-sharing": - /go/mac-file-sharing/ "/engine/security/rootless/": # Instructions on running docker in rootless mode. This redirect is currently @@ -98,7 +98,7 @@ - /go/storage-driver/ "/docker-hub/vulnerability-scanning/": - /go/tip-scanning/ -"/desktop/windows/wsl/": +"/desktop/features/wsl/": # Link used by Docker Desktop to refer users on how to activate WSL 2 - /go/wsl2/ "/reference/api/hub/latest/": @@ -229,9 +229,9 @@ - "/go/build-checks-experimental/" # Build links (external) -"https://www.docker.com/build-early-access-program/?utm_campaign=onboard-30-customer-zero&utm_medium=in-product-ad&utm_source=desktop_v4": +"https://app.docker.com/build/?utm_campaign=onboard-30-customer-zero&utm_medium=in-product-ad&utm_source=desktop_v4": - /go/build-eap/ -"https://www.docker.com/products/build-cloud/?utm_campaign=2024-02-02-banner_dbc_ga&utm_medium=in-product-ad&utm_source=desktop_v4": +"https://app.docker.com/build/?utm_campaign=2024-02-02-banner_dbc_ga&utm_medium=in-product-ad&utm_source=desktop_v4": - /go/build-ga/ "https://www.docker.com/products/build-cloud/?utm_campaign=2024-02-02-dbc_cli&utm_medium=in-product-ad&utm_source=desktop_v4": - /go/docker-build-cloud/ diff --git a/docker-bake.hcl b/docker-bake.hcl index 32f915ed24d..dbbf1d568cc 100644 --- a/docker-bake.hcl +++ b/docker-bake.hcl @@ -10,6 +10,10 @@ variable "DOCS_SITE_DIR" { default = "public" } +variable "DRY_RUN" { + default = null +} + group "default" { targets = ["release"] } @@ -69,12 +73,12 @@ target "path-warnings" { } # -# releaser targets are defined in _releaser/Dockerfile +# releaser targets are defined in hack/releaser/Dockerfile # and are used for AWS S3 deployment # target "releaser-build" { - context = "_releaser" + context = "hack/releaser" target = "releaser" output = ["type=cacheonly"] provenance = false @@ -98,6 +102,7 @@ variable "AWS_LAMBDA_FUNCTION" { target "_common-aws" { args = { + DRY_RUN = DRY_RUN AWS_REGION = AWS_REGION AWS_S3_BUCKET = AWS_S3_BUCKET AWS_S3_CONFIG = AWS_S3_CONFIG @@ -114,7 +119,7 @@ target "_common-aws" { target "aws-s3-update-config" { inherits = ["_common-aws"] - context = "_releaser" + context = "hack/releaser" target = "aws-s3-update-config" no-cache-filter = ["aws-update-config"] output = ["type=cacheonly"] @@ -122,7 +127,7 @@ target "aws-s3-update-config" { target "aws-lambda-invoke" { inherits = ["_common-aws"] - context = "_releaser" + context = "hack/releaser" target = "aws-lambda-invoke" no-cache-filter = ["aws-lambda-invoke"] output = ["type=cacheonly"] @@ -130,7 +135,7 @@ target "aws-lambda-invoke" { target "aws-cloudfront-update" { inherits = ["_common-aws"] - context = "_releaser" + context = "hack/releaser" target = "aws-cloudfront-update" contexts = { sitedir = DOCS_SITE_DIR diff --git a/go.mod b/go.mod index dc30c721c03..752e39197d3 100644 --- a/go.mod +++ b/go.mod @@ -3,19 +3,19 @@ module github.com/docker/docs go 1.23.1 require ( - github.com/docker/buildx v0.17.1 // indirect - github.com/docker/cli v27.3.2-0.20241008150905-cb3048fbebb1+incompatible // indirect - github.com/docker/compose/v2 v2.30.1 // indirect - github.com/docker/scout-cli v1.13.0 // indirect - github.com/moby/buildkit v0.16.0 // indirect - github.com/moby/moby v27.3.1+incompatible // indirect + github.com/docker/buildx v0.19.2 // indirect + github.com/docker/cli v27.4.0+incompatible // indirect + github.com/docker/compose/v2 v2.32.0 // indirect + github.com/docker/scout-cli v1.15.0 // indirect + github.com/moby/buildkit v0.18.0 // indirect + github.com/moby/moby v27.4.0+incompatible // indirect ) replace ( - github.com/docker/buildx => github.com/docker/buildx v0.17.1 - github.com/docker/cli => github.com/docker/cli v27.3.1+incompatible - github.com/docker/compose/v2 => github.com/docker/compose/v2 v2.30.1 - github.com/docker/scout-cli => github.com/docker/scout-cli v1.13.0 - github.com/moby/buildkit => github.com/moby/buildkit v0.16.0 - github.com/moby/moby => github.com/moby/moby v27.3.1+incompatible + github.com/docker/buildx => github.com/docker/buildx v0.19.2 + github.com/docker/cli => github.com/docker/cli v27.4.0+incompatible + github.com/docker/compose/v2 => github.com/docker/compose/v2 v2.31.0 + github.com/docker/scout-cli => github.com/docker/scout-cli v1.15.0 + github.com/moby/buildkit => github.com/moby/buildkit v0.18.0 + github.com/moby/moby => github.com/moby/moby v27.4.0+incompatible ) diff --git a/go.sum b/go.sum index a5ee7ec9827..628d1d59fce 100644 --- a/go.sum +++ b/go.sum @@ -82,6 +82,12 @@ github.com/docker/buildx v0.17.0 h1:Z+QQxsJJPldaeU/4aNXoudFwDDK0/ALFYmDcP5q5fiY= github.com/docker/buildx v0.17.0/go.mod h1:sBKkoZFs+R2D6ARyQ4/GE/FQHHFsl9PkHdvv/GXAsMo= github.com/docker/buildx v0.17.1 h1:9ob2jGp4+W9PxWw68GsoNFp+eYFc7eUoRL9VljLCSM4= github.com/docker/buildx v0.17.1/go.mod h1:kJOhOhS47LRvrLFRulFiO5SE6VJf54yYMn7DzjgO5W0= +github.com/docker/buildx v0.18.0 h1:rSauXHeJt90NvtXrLK5J992Eb0UPJZs2vV3u1zTf1nE= +github.com/docker/buildx v0.18.0/go.mod h1:JGNSshOhHs5FhG3u51jXUf4lLOeD2QBIlJ2vaRB67p4= +github.com/docker/buildx v0.19.1 h1:muQEvRJLvOCS0p/67gPwjnQPWqE5ot3sGkb2Eq7vCmw= +github.com/docker/buildx v0.19.1/go.mod h1:k4WP+XmGRYL0a7l4RZAI2TqpwhuAuSQ5U/rosRgFmAA= +github.com/docker/buildx v0.19.2 h1:2zXzgP2liQKgQ5BiOqMc+wz7hfWgAIMWw5MR6QDG++I= +github.com/docker/buildx v0.19.2/go.mod h1:k4WP+XmGRYL0a7l4RZAI2TqpwhuAuSQ5U/rosRgFmAA= github.com/docker/cli v24.0.2+incompatible h1:QdqR7znue1mtkXIJ+ruQMGQhpw2JzMJLRXp6zpzF6tM= github.com/docker/cli v24.0.2+incompatible/go.mod h1:JLrzqnKDaYBop7H2jaqPtU4hHvMKP+vjCwu2uszcLI8= github.com/docker/cli v24.0.4+incompatible h1:Y3bYF9ekNTm2VFz5U/0BlMdJy73D+Y1iAAZ8l63Ydzw= @@ -128,6 +134,10 @@ github.com/docker/cli v27.3.0+incompatible h1:h7J5eiGdUbH2Q4EcGr1mFb20qzS7Nrot3E github.com/docker/cli v27.3.0+incompatible/go.mod h1:JLrzqnKDaYBop7H2jaqPtU4hHvMKP+vjCwu2uszcLI8= github.com/docker/cli v27.3.1+incompatible h1:qEGdFBF3Xu6SCvCYhc7CzaQTlBmqDuzxPDpigSyeKQQ= github.com/docker/cli v27.3.1+incompatible/go.mod h1:JLrzqnKDaYBop7H2jaqPtU4hHvMKP+vjCwu2uszcLI8= +github.com/docker/cli v27.3.2-0.20241107125754-eb986ae71b0c+incompatible h1:KqHavmeo5+ct30Z2UKxbVhUEfuzI9JZFgPdVVaWS4Uc= +github.com/docker/cli v27.3.2-0.20241107125754-eb986ae71b0c+incompatible/go.mod h1:JLrzqnKDaYBop7H2jaqPtU4hHvMKP+vjCwu2uszcLI8= +github.com/docker/cli v27.4.0+incompatible h1:/nJzWkcI1MDMN+U+px/YXnQWJqnu4J+QKGTfD6ptiTc= +github.com/docker/cli v27.4.0+incompatible/go.mod h1:JLrzqnKDaYBop7H2jaqPtU4hHvMKP+vjCwu2uszcLI8= github.com/docker/compose-cli v1.0.35 h1:uZyEHLalfqBS2PiTpA1LAULyJmuQ+YtZg7nG4Xl3/Cc= github.com/docker/compose-cli v1.0.35/go.mod h1:mSXI4hFLpRU3EtI8NTo32bNwI0UXSr8jnq+/rYjGAUU= github.com/docker/compose/v2 v2.22.0 h1:3rRz4L7tPU75wRsV8JZh2/aTgerQvPa1cpzZN+tHqUY= @@ -174,6 +184,12 @@ github.com/docker/compose/v2 v2.30.0 h1:EjtEBeIPeqzlY3DUQhdjkiMwigX8TrUrgPAyAqey github.com/docker/compose/v2 v2.30.0/go.mod h1:WlU5gYgsYfNLuDeUdTusvutEC5PV3sDc15aClbR5lPw= github.com/docker/compose/v2 v2.30.1 h1:AwDaEcmgskxaI75Wjt3KL6/Xqq/GXKUQcBpo/RqMEkw= github.com/docker/compose/v2 v2.30.1/go.mod h1:pt/uv8KQ6VaM0IbHZwB1UdwDIs9PB4nN4LoWst+dqXc= +github.com/docker/compose/v2 v2.30.2 h1:7PypFsyl5wjlSeOyx3LCb8XMcAGkb+D0fqM47OIKe8I= +github.com/docker/compose/v2 v2.30.2/go.mod h1:ND4+yaNoJ3Jh1OgrEO64uzMq/VKRqBkMS8zpb65Fve8= +github.com/docker/compose/v2 v2.30.3 h1:e8H7xGLCZOeFo46GEtyDGHlkBbNgXqbXKIXPOSL8cfU= +github.com/docker/compose/v2 v2.30.3/go.mod h1:ayPsSsRSc5WpVFehPrTDFuljAydxaf8g0aM9UKbaMXk= +github.com/docker/compose/v2 v2.31.0 h1:8Sm0c4MjIhksguxIA5koYMXoTJDAp/CaZ1cdZrMvMdw= +github.com/docker/compose/v2 v2.31.0/go.mod h1:oQq3UDEdsnB3AUO72AxaoeLbkCgmUu1+8tLzvmphmXA= github.com/docker/distribution v2.8.2+incompatible h1:T3de5rq0dB1j30rp0sA2rER+m322EBzniBPB6ZIzuh8= github.com/docker/distribution v2.8.2+incompatible/go.mod h1:J2gT2udsDAN96Uj4KfcMRqY0/ypR+oyYUYmja8H+y+w= github.com/docker/distribution v2.8.3+incompatible h1:AtKxIZ36LoNK51+Z6RpzLpddBirtxJnzDrHLEKxTAYk= @@ -226,6 +242,8 @@ github.com/docker/scout-cli v1.12.0 h1:NhmT4BzL2lYiIk5hPFvK5FzQ8izbLDL3/Rugcyulv github.com/docker/scout-cli v1.12.0/go.mod h1:Eo1RyCJsx3ldz/YTY5yGxu9g9mwTYbRUutxQUkow3Fc= github.com/docker/scout-cli v1.13.0 h1:RThUM56yooV5izqgMEYQS+a6Yx+vGmZofJwX0qjgkco= github.com/docker/scout-cli v1.13.0/go.mod h1:Eo1RyCJsx3ldz/YTY5yGxu9g9mwTYbRUutxQUkow3Fc= +github.com/docker/scout-cli v1.15.0 h1:VhA9niVftEyZ9f5KGwKnrSfQOp2X3uIU3VbE/gTVMTM= +github.com/docker/scout-cli v1.15.0/go.mod h1:Eo1RyCJsx3ldz/YTY5yGxu9g9mwTYbRUutxQUkow3Fc= github.com/elazarl/goproxy v0.0.0-20191011121108-aa519ddbe484/go.mod h1:Ro8st/ElPeALwNFlcTpWmkr6IoMFfkjXAvTHpevnDsM= github.com/evanphx/json-patch v4.9.0+incompatible/go.mod h1:50XU6AFN0ol/bzJsmQLiYLvXMP4fmwYFNcr97nuDLSk= github.com/fatih/color v1.7.0/go.mod h1:Zm6kSWBoL9eyXnKyktHP6abPY2pDugNf5KwzbycvMj4= @@ -300,6 +318,12 @@ github.com/moby/buildkit v0.15.1 h1:J6wrew7hphKqlq1wuu6yaUb/1Ra7gEzDAovylGztAKM= github.com/moby/buildkit v0.15.1/go.mod h1:Yis8ZMUJTHX9XhH9zVyK2igqSHV3sxi3UN0uztZocZk= github.com/moby/buildkit v0.16.0 h1:wOVBj1o5YNVad/txPQNXUXdelm7Hs/i0PUFjzbK0VKE= github.com/moby/buildkit v0.16.0/go.mod h1:Xqx/5GlrqE1yIRORk0NSCVDFpQAU1WjlT6KHYZdisIQ= +github.com/moby/buildkit v0.17.0 h1:ZA/4AxwBbve1f3ZaNNJQiCBtTV62R6YweWNwq4A+sTc= +github.com/moby/buildkit v0.17.0/go.mod h1:ru8NFyDHD8HbuKaLXJIjK9nr3x6FZR+IWjtF07S+wdM= +github.com/moby/buildkit v0.17.1-0.20241031124041-354f2d13c905 h1:KMEmQThIQYXKvBurcvM+6zZjxP2CoNSsF/wUpW+RC/E= +github.com/moby/buildkit v0.17.1-0.20241031124041-354f2d13c905/go.mod h1:ru8NFyDHD8HbuKaLXJIjK9nr3x6FZR+IWjtF07S+wdM= +github.com/moby/buildkit v0.18.0 h1:KSelhNINJcNA3FCWBbGCytvicjP+kjU5kZlZhkTUkVo= +github.com/moby/buildkit v0.18.0/go.mod h1:vCR5CX8NGsPTthTg681+9kdmfvkvqJBXEv71GZe5msU= github.com/moby/locker v1.0.1/go.mod h1:S7SDdo5zpBK84bzzVlKr2V0hz+7x9hWbYC/kq7oQppc= github.com/moby/moby v24.0.2+incompatible h1:yH+5dRHH1x3XRKzl1THA2aGTy6CHYnkt5N924ADMax8= github.com/moby/moby v24.0.2+incompatible/go.mod h1:fDXVQ6+S340veQPv35CzDahGBmHsiclFwfEygB/TWMc= @@ -333,6 +357,8 @@ github.com/moby/moby v27.3.0+incompatible h1:AhSu/R7C5uiyd+JCts3kxrKyTzXa3FilBJ0 github.com/moby/moby v27.3.0+incompatible/go.mod h1:fDXVQ6+S340veQPv35CzDahGBmHsiclFwfEygB/TWMc= github.com/moby/moby v27.3.1+incompatible h1:KQbXBjo7PavKpzIl7UkHT31y9lw/e71Uvrqhr4X+zMA= github.com/moby/moby v27.3.1+incompatible/go.mod h1:fDXVQ6+S340veQPv35CzDahGBmHsiclFwfEygB/TWMc= +github.com/moby/moby v27.4.0+incompatible h1:jGXXZCMAmFZS9pKsQqUt9yAPHOC450PM9lbQYPSQnuc= +github.com/moby/moby v27.4.0+incompatible/go.mod h1:fDXVQ6+S340veQPv35CzDahGBmHsiclFwfEygB/TWMc= github.com/moby/sys/symlink v0.1.0/go.mod h1:GGDODQmbFOjFsXvfLVn3+ZRxkch54RkSiGqsZeMYowQ= github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q= github.com/morikuni/aec v1.0.0/go.mod h1:BbKIizmSmc5MMPqRYbxO4ZU0S0+P200+tUnFx7PXmsc= diff --git a/_releaser/Dockerfile b/hack/releaser/Dockerfile similarity index 85% rename from _releaser/Dockerfile rename to hack/releaser/Dockerfile index 5b945dd596a..11c574d173a 100644 --- a/_releaser/Dockerfile +++ b/hack/releaser/Dockerfile @@ -1,11 +1,11 @@ # syntax=docker/dockerfile:1 -ARG GO_VERSION=1.19 +ARG GO_VERSION=1.23 FROM scratch AS sitedir FROM golang:${GO_VERSION}-alpine AS base -RUN apk add --no-cache jq openssl +RUN apk add --no-cache openssl ENV CGO_ENABLED=0 WORKDIR /src COPY go.mod go.sum ./ @@ -19,6 +19,7 @@ RUN --mount=type=bind,target=. \ go build -o /out/releaser . FROM base AS aws-s3-update-config +ARG DRY_RUN=false ARG AWS_REGION ARG AWS_S3_BUCKET ARG AWS_S3_CONFIG @@ -30,6 +31,7 @@ RUN --mount=type=bind,target=. \ releaser aws s3-update-config FROM base AS aws-lambda-invoke +ARG DRY_RUN=false ARG AWS_REGION ARG AWS_LAMBDA_FUNCTION RUN --mount=type=bind,from=releaser,source=/out/releaser,target=/usr/bin/releaser \ @@ -39,16 +41,17 @@ RUN --mount=type=bind,from=releaser,source=/out/releaser,target=/usr/bin/release releaser aws lambda-invoke FROM base AS aws-cloudfront-update +ARG DRY_RUN=false ARG AWS_REGION ARG AWS_LAMBDA_FUNCTION ARG AWS_CLOUDFRONT_ID +ARG AWS_LAMBDA_FUNCTION_FILE="cloudfront-lambda-redirects.js" +ARG REDIRECTS_FILE="/site/redirects.json" +ARG REDIRECTS_PREFIXES_FILE="redirects-prefixes.json" RUN --mount=type=bind,target=. \ --mount=type=bind,from=sitedir,target=/site \ --mount=type=bind,from=releaser,source=/out/releaser,target=/usr/bin/releaser \ --mount=type=secret,id=AWS_ACCESS_KEY_ID \ --mount=type=secret,id=AWS_SECRET_ACCESS_KEY \ --mount=type=secret,id=AWS_SESSION_TOKEN \ - AWS_LAMBDA_FUNCTION_FILE=cloudfront-lambda-redirects.js \ - REDIRECTS_JSON=$(jq -c '.' /site/redirects.json) \ - REDIRECTS_PREFIXES_JSON=$(jq -c '.' redirects-prefixes.json) \ releaser aws cloudfront-update diff --git a/_releaser/aws.go b/hack/releaser/aws.go similarity index 81% rename from _releaser/aws.go rename to hack/releaser/aws.go index 3f79c2bd2e4..b608b7c5d41 100644 --- a/_releaser/aws.go +++ b/hack/releaser/aws.go @@ -4,6 +4,7 @@ import ( "archive/zip" "bytes" "encoding/json" + "errors" "fmt" "log" "os" @@ -30,9 +31,15 @@ type AwsS3UpdateConfigCmd struct { Region string `kong:"name='region',env='AWS_REGION'"` S3Bucket string `kong:"name='s3-bucket',env='AWS_S3_BUCKET'"` S3Config string `kong:"name='s3-website-config',env='AWS_S3_CONFIG'"` + DryRun bool `kong:"name='dry-run',env='DRY_RUN'"` } func (s *AwsS3UpdateConfigCmd) Run() error { + if s.DryRun { + log.Printf("INFO: Dry run mode enabled. Configuration:\nRegion: %s\nS3Bucket: %s\nS3Config: %s\n", s.Region, s.S3Bucket, s.S3Config) + return nil + } + file, err := os.ReadFile(s.S3Config) if err != nil { return fmt.Errorf("failed to read s3 config file %s: %w", s.S3Config, err) @@ -74,9 +81,15 @@ func (s *AwsS3UpdateConfigCmd) Run() error { type AwsLambdaInvokeCmd struct { Region string `kong:"name='region',env='AWS_REGION'"` LambdaFunction string `kong:"name='lambda-function',env='AWS_LAMBDA_FUNCTION'"` + DryRun bool `kong:"name='dry-run',env='DRY_RUN'"` } func (s *AwsLambdaInvokeCmd) Run() error { + if s.DryRun { + log.Printf("INFO: Dry run mode enabled. Configuration:\nRegion: %s\nLambdaFunction: %s\n", s.Region, s.LambdaFunction) + return nil + } + svc := lambda.New(session.Must(session.NewSessionWithOptions(session.Options{ SharedConfigState: session.SharedConfigEnable, })), &aws.Config{ @@ -100,19 +113,26 @@ type AwsCloudfrontUpdateCmd struct { Function string `kong:"name='lambda-function',env='AWS_LAMBDA_FUNCTION'"` FunctionFile string `kong:"name='lambda-function-file',env='AWS_LAMBDA_FUNCTION_FILE'"` CloudfrontID string `kong:"name='cloudfront-id',env='AWS_CLOUDFRONT_ID'"` - RedirectsJSON string `kong:"name='redirects-json',env='REDIRECTS_JSON'"` - RedirectsPrefixesJSON string `kong:"name='redirects-prefixes-json',env='REDIRECTS_PREFIXES_JSON'"` + RedirectsFile string `kong:"name='redirects-file',env='REDIRECTS_FILE'"` + RedirectsPrefixesFile string `kong:"name='redirects-prefixes-file',env='REDIRECTS_PREFIXES_FILE'"` + DryRun bool `kong:"name='dry-run',env='DRY_RUN'"` } func (s *AwsCloudfrontUpdateCmd) Run() error { var err error ver := time.Now().UTC().Format(time.RFC3339) - zipdt, err := getLambdaFunctionZip(s.FunctionFile, s.RedirectsJSON, s.RedirectsPrefixesJSON) + zipdt, err := getLambdaFunctionZip(s.FunctionFile, s.RedirectsFile, s.RedirectsPrefixesFile, s.DryRun) if err != nil { return fmt.Errorf("cannot create lambda function zip: %w", err) } + if s.DryRun { + log.Printf("INFO: Dry run mode enabled. Configuration:\nRegion: %s\nFunction: %s\nFunctionFile: %s\nCloudfrontID: %s\nRedirectsFile: %s\nRedirectsPrefixesFile: %s\n", + s.Region, s.Function, s.FunctionFile, s.CloudfrontID, s.RedirectsFile, s.RedirectsPrefixesFile) + return nil + } + svc := lambda.New(session.Must(session.NewSessionWithOptions(session.Options{ SharedConfigState: session.SharedConfigEnable, })), &aws.Config{ @@ -124,13 +144,14 @@ func (s *AwsCloudfrontUpdateCmd) Run() error { FunctionName: aws.String(s.Function), }) if err != nil { - if aerr, ok := err.(awserr.Error); ok && aerr.Code() != lambda.ErrCodeResourceNotFoundException { + var aerr awserr.Error + if errors.As(err, &aerr) && aerr.Code() != lambda.ErrCodeResourceNotFoundException { return fmt.Errorf("cannot find lambda function %q: %w", s.Function, err) } _, err = svc.CreateFunction(&lambda.CreateFunctionInput{ FunctionName: aws.String(s.Function), }) - if aerr, ok := err.(awserr.Error); ok && aerr.Code() != lambda.ErrCodeResourceConflictException { + if errors.As(err, &aerr) && aerr.Code() != lambda.ErrCodeResourceConflictException { return err } } @@ -228,24 +249,39 @@ func (s *AwsCloudfrontUpdateCmd) Run() error { return nil } -func getLambdaFunctionZip(funcFilename string, redirectsJSON string, redirectsPrefixesJSON string) ([]byte, error) { +func getLambdaFunctionZip(funcFilename, redirectsFile, redirectsPrefixesFile string, dryrun bool) ([]byte, error) { funcdt, err := os.ReadFile(funcFilename) if err != nil { return nil, fmt.Errorf("failed to read lambda function file %q: %w", funcFilename, err) } + redirects, err := os.ReadFile(redirectsFile) + if err != nil { + return nil, fmt.Errorf("failed to read redirects file %q: %w", redirectsFile, err) + } + + redirectsPrefixes, err := os.ReadFile(redirectsPrefixesFile) + if err != nil { + return nil, fmt.Errorf("failed to read redirects prefixes file %q: %w", redirectsPrefixesFile, err) + } + var funcbuf bytes.Buffer functpl := template.Must(template.New("").Parse(string(funcdt))) if err = functpl.Execute(&funcbuf, struct { RedirectsJSON string RedirectsPrefixesJSON string }{ - redirectsJSON, - redirectsPrefixesJSON, + string(redirects), + string(redirectsPrefixes), }); err != nil { return nil, err } + if dryrun { + log.Printf("INFO: Dry run mode enabled. Lambda Function Definition:\n\n%s\n", funcbuf.String()) + return nil, nil + } + tmpdir, err := os.MkdirTemp("", "lambda-zip") if err != nil { return nil, err diff --git a/_releaser/cloudfront-lambda-redirects.js b/hack/releaser/cloudfront-lambda-redirects.js similarity index 100% rename from _releaser/cloudfront-lambda-redirects.js rename to hack/releaser/cloudfront-lambda-redirects.js diff --git a/_releaser/go.mod b/hack/releaser/go.mod similarity index 50% rename from _releaser/go.mod rename to hack/releaser/go.mod index 3232fbe7015..d17c092280c 100644 --- a/_releaser/go.mod +++ b/hack/releaser/go.mod @@ -1,15 +1,14 @@ -module github.com/docker/docs/_releaser +module github.com/docker/docs/hack/releaser -go 1.18 +go 1.22 require ( - github.com/alecthomas/kong v0.7.1 - github.com/aws/aws-sdk-go v1.44.180 + github.com/alecthomas/kong v1.4.0 + github.com/aws/aws-sdk-go v1.55.5 ) require ( github.com/davecgh/go-spew v1.1.1 // indirect github.com/jmespath/go-jmespath v0.4.0 // indirect - golang.org/x/net v0.17.0 // indirect gopkg.in/yaml.v2 v2.4.0 // indirect ) diff --git a/hack/releaser/go.sum b/hack/releaser/go.sum new file mode 100644 index 00000000000..8a68e163bf9 --- /dev/null +++ b/hack/releaser/go.sum @@ -0,0 +1,24 @@ +github.com/alecthomas/assert/v2 v2.11.0 h1:2Q9r3ki8+JYXvGsDyBXwH3LcJ+WK5D0gc5E8vS6K3D0= +github.com/alecthomas/assert/v2 v2.11.0/go.mod h1:Bze95FyfUr7x34QZrjL+XP+0qgp/zg8yS+TtBj1WA3k= +github.com/alecthomas/kong v1.4.0 h1:UL7tzGMnnY0YRMMvJyITIRX1EpO6RbBRZDNcCevy3HA= +github.com/alecthomas/kong v1.4.0/go.mod h1:p2vqieVMeTAnaC83txKtXe8FLke2X07aruPWXyMPQrU= +github.com/alecthomas/repr v0.4.0 h1:GhI2A8MACjfegCPVq9f1FLvIBS+DrQ2KQBFZP1iFzXc= +github.com/alecthomas/repr v0.4.0/go.mod h1:Fr0507jx4eOXV7AlPV6AVZLYrLIuIeSOWtW57eE/O/4= +github.com/aws/aws-sdk-go v1.55.5 h1:KKUZBfBoyqy5d3swXyiC7Q76ic40rYcbqH7qjh59kzU= +github.com/aws/aws-sdk-go v1.55.5/go.mod h1:eRwEWoyTWFMVYVQzKMNHWP5/RV4xIUGMQfXQHfHkpNU= +github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= +github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c= +github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= +github.com/hexops/gotextdiff v1.0.3 h1:gitA9+qJrrTCsiCl7+kh75nPqQt1cx4ZkudSTLoUqJM= +github.com/hexops/gotextdiff v1.0.3/go.mod h1:pSWU5MAI3yDq+fZBTazCSJysOMbxWL1BSow5/V2vxeg= +github.com/jmespath/go-jmespath v0.4.0 h1:BEgLn5cpjn8UN1mAw4NjwDrS35OdebyEtFe+9YPoQUg= +github.com/jmespath/go-jmespath v0.4.0/go.mod h1:T8mJZnbsbmF+m6zOOFylbeCJqk5+pHWvzYPziyZiYoo= +github.com/jmespath/go-jmespath/internal/testify v1.5.1 h1:shLQSRRSCCPj3f2gpwzGwWFoC7ycTf1rcQZHOlsJ6N8= +github.com/jmespath/go-jmespath/internal/testify v1.5.1/go.mod h1:L3OGu8Wl2/fWfCI6z80xFu9LTZmf1ZRjMHUOPmWr69U= +github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM= +github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4= +github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME= +gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= +gopkg.in/yaml.v2 v2.2.8/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI= +gopkg.in/yaml.v2 v2.4.0 h1:D8xgwECY7CYvx+Y2n4sBz93Jn9JRvxdiyyo8CTfuKaY= +gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ= diff --git a/_releaser/main.go b/hack/releaser/main.go similarity index 100% rename from _releaser/main.go rename to hack/releaser/main.go diff --git a/_releaser/redirects-prefixes.json b/hack/releaser/redirects-prefixes.json similarity index 100% rename from _releaser/redirects-prefixes.json rename to hack/releaser/redirects-prefixes.json diff --git a/_releaser/s3-config.json b/hack/releaser/s3-config.json similarity index 100% rename from _releaser/s3-config.json rename to hack/releaser/s3-config.json diff --git a/scripts/test_go_redirects.sh b/hack/test/go_redirects similarity index 100% rename from scripts/test_go_redirects.sh rename to hack/test/go_redirects diff --git a/hack/test/unused_media b/hack/test/unused_media new file mode 100755 index 00000000000..56cb8879688 --- /dev/null +++ b/hack/test/unused_media @@ -0,0 +1,33 @@ +#!/usr/bin/env sh + +echo "checking for unused media files..." +FORMATS="svg png webp mp4 jpg jpeg" +DIRECTORIES="content static" + +FORMAT_FLAGS="" +for format in $FORMATS; do + FORMAT_FLAGS="$FORMAT_FLAGS -e $format" +done + +echo "Searching for media with formats: $FORMATS" +echo "Searching in directories: $DIRECTORIES" + +MEDIA=$(fd . $FORMAT_FLAGS $DIRECTORIES) + +UNUSED_COUNT=0 + +for file in $MEDIA; do + rg -q "$(basename $file)" . + if [ $? -ne 0 ]; then + echo "$file" + UNUSED_COUNT=$((UNUSED_COUNT + 1)) + fi +done + +if [ $UNUSED_COUNT -eq 0 ]; then + echo "No unused media files." + exit 0 +else + echo "$UNUSED_COUNT unused media files found. Please remove them." + exit 1 +fi diff --git a/scripts/vendor.sh b/hack/vendor similarity index 100% rename from scripts/vendor.sh rename to hack/vendor diff --git a/hugo.yaml b/hugo.yaml index 3631f41b174..56a269f10a1 100644 --- a/hugo.yaml +++ b/hugo.yaml @@ -107,14 +107,15 @@ params: docs_url: https://docs.docker.com latest_engine_api_version: "1.47" - docker_ce_version: "27.2.1" - compose_version: "v2.30.1" + docker_ce_version: "27.4.0" + docker_ce_version_prev: "27.3.1" + compose_version: "v2.32.0" compose_file_v3: "3.8" compose_file_v2: "2.4" buildkit_version: "0.16.0" example_go_version: "1.23" - example_alpine_version: "3.20" + example_alpine_version: "3.21" example_node_version: "20" min_version_thresholds: @@ -244,7 +245,7 @@ module: proxy: https://proxy.golang.org,direct hugoVersion: extended: false - min: "0.124.1" + min: "0.139.0" mounts: - source: assets target: assets diff --git a/hugo_stats.json b/hugo_stats.json index fb4024a5d39..4cb719a37c9 100644 --- a/hugo_stats.json +++ b/hugo_stats.json @@ -42,8 +42,8 @@ "Docker-Desktop", "Docker-Hub", "Docker-Scout-Dashboard", + "Docker-plan", "Download", - "Editor-or-IDE", "Entra-ID", "Entra-ID-SAML-2.0", "External-cloud-storage", @@ -57,7 +57,6 @@ "Git-Bash", "Git-Bash-CLI", "GitHub-Actions", - "GitHub.com", "GitLab", "Go", "HTTP", @@ -70,6 +69,8 @@ "JavaScript", "Jenkins", "Latest", + "Legacy-Docker-plan", + "Legacy-Docker-plans", "Linux", "Local-or-Hub-storage", "MDM", @@ -77,7 +78,6 @@ "Mac", "Mac-/-Linux", "Mac-/-Linux-/-Git-Bash", - "Mac-/-Linux-/-Windows-Git-Bash", "Mac-/-Linux-CLI", "Mac-and-Linux", "Mac-with-Apple-silicon", @@ -126,9 +126,7 @@ "WSL-2-backend-Arm-Beta", "WSL-2-backend-x86_64", "Web-browser", - "What-administrative-tasks-can-I-perform-in-Docker-Hub", "What-are-the-key-features-of-Docker-Desktop", - "What-key-features-are-included-in-Docker-Hub", "Whats-included-in-Docker-Desktop", "Windows", "Windows-Command-Prompt", @@ -143,7 +141,6 @@ "aspect-video", "bake-action", "bg-amber-light", - "bg-amber-light-200", "bg-background-light", "bg-black/50", "bg-black/70", @@ -196,7 +193,6 @@ "containerd-image-store", "cursor-pointer", "dark:bg-amber-dark", - "dark:bg-amber-dark-200", "dark:bg-background-dark", "dark:bg-blue-dark", "dark:bg-blue-dark-400", @@ -266,6 +262,7 @@ "flex-col", "flex-col-reverse", "flex-grow", + "flex-grow-0", "flex-none", "flex-shrink", "flex-wrap", @@ -347,6 +344,7 @@ "lg:gap-8", "lg:grid-cols-2", "lg:grid-cols-3", + "lg:grid-cols-4", "lg:hidden", "lg:no-underline", "lg:pb-2", @@ -520,6 +518,7 @@ "transition", "truncate", "underline-offset-2", + "uppercase", "w-2", "w-8", "w-[1200px]", diff --git a/layouts/_default/_markup/render-link.html b/layouts/_default/_markup/render-link.html index 38353aa933b..ce470139841 100644 --- a/layouts/_default/_markup/render-link.html +++ b/layouts/_default/_markup/render-link.html @@ -4,7 +4,6 @@ {{- .Text | safeHTML -}} diff --git a/layouts/_default/cli.html b/layouts/_default/cli.html index 58c99c2c2c9..a18752576c2 100644 --- a/layouts/_default/cli.html +++ b/layouts/_default/cli.html @@ -5,8 +5,8 @@ {{ else }} {{ $data = index site.Data .Params.datafile }} {{ end }} - {{ .Scratch.Set "headings" slice }} - {{ .Scratch.Set "subheadings" slice }} + {{ .Store.Set "headings" slice }} + {{ .Store.Set "subheadings" slice }}
{{ partial "breadcrumbs.html" . }} @@ -84,11 +84,11 @@

{{ .Title }}

{{ $heading := dict "level" 2 "text" "Description" }} {{ partialCached "heading.html" $heading "cli-description" }} {{ $subHeadings := (strings.FindRE `(?m:#{3,4} .*)` .) }} - {{ $.Scratch.Add "headings" $heading }} + {{ $.Store.Add "headings" $heading }} {{ range $subHeadings }} {{ $lvl := strings.Count "#" . }} {{ $txt := strings.TrimLeft "# " . }} - {{ $.Scratch.Add "headings" (dict "level" $lvl "text" $txt) }} + {{ $.Store.Add "headings" (dict "level" $lvl "text" $txt) }} {{ end }} {{ . | $.RenderString (dict "display" "block") }} {{ end }} @@ -97,7 +97,7 @@

{{ .Title }}

{{ with $opts }} {{ $heading := dict "level" 2 "text" "Options" }} {{ partialCached "heading.html" $heading "cli-options" }} - {{ $.Scratch.Add "headings" $heading }} + {{ $.Store.Add "headings" $heading }}
@@ -162,18 +162,18 @@

{{ .Title }}

{{ $heading := dict "level" 2 "text" "Examples" }} {{ partialCached "heading.html" $heading "cli-examples" }} {{ $subHeadings := (strings.FindRE `(?m:#{3,4} .*)` .) }} - {{ $.Scratch.Add "headings" $heading }} + {{ $.Store.Add "headings" $heading }} {{ range $subHeadings }} {{ $lvl := strings.Count "#" . }} {{ $txt := strings.TrimLeft "# " . }} - {{ $.Scratch.Add "headings" (dict "level" $lvl "text" $txt) }} + {{ $.Store.Add "headings" (dict "level" $lvl "text" $txt) }} {{ end }} {{ $.RenderString (dict "display" "block") . }} {{ end }} {{ if eq .Kind "section" }} {{ $heading := dict "level" 2 "text" "Subcommands" }} {{ partialCached "heading.html" $heading "cli-subcommands" }} - {{ $.Scratch.Add "headings" $heading }} + {{ $.Store.Add "headings" $heading }}
@@ -202,7 +202,7 @@

{{ .Title }}

{{ T "tableOfContents" }}