docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'chrisward/dvp' of github.com:ChrisChinchilla/docs into chrisward/dvp

This commit is contained in:
Chris Chinchilla 2023-04-12 14:44:18 +02:00
parent 5573db4540 5ebb7432b0
commit 297bf78cac
161 changed files with 3805 additions and 4804 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.github/vale/Docker/ComplexWords.yml vendored
View File

@ -63,6 +63,7 @@ swap:
facilitate: ease
females: women
finalize: complete|finish
illustrate: show
itemized: listed
jeopardize: risk
liaise: work with|partner with

2
.github/vale/Docker/Substitute.yml vendored
View File

@ -3,6 +3,8 @@ message: "Consider using '%s' instead of '%s'"
link: https://docs.docker.com/contribute/style/recommended-words/
ignorecase: true
level: suggestion
action:
name: replace
swap:
'\b(?:eg|e\.g\.)[\s,]': for example
'\b(?:ie|i\.e\.)[\s,]': that is

1
.github/vale/Vocab/Docker/accept.txt vendored
View File

@ -1,4 +1,5 @@
(Certified|Verified) Publisher( Program)?
Docker-Sponsored Open Source
Autotest
BuildKit
Docker

4
README.md
View File

@ -20,7 +20,7 @@ an existing issue. If possible, we recommend that you suggest a fix to the issue
by creating a pull request.
You can ask general questions and get community support through the [Docker
Community Slack](http://dockr.ly/slack). Personalized support is available
Community Slack](https://dockr.ly/comm-slack). Personalized support is available
through the Docker Pro, Team, and Business subscriptions. See [Docker
Pricing](https://www.docker.com/pricing) for details.
@ -49,4 +49,4 @@ contribute, see our [Contribute section](https://docs.docker.com/contribute/over
## Copyright and license
Copyright 2013-2023 Docker, inc, released under the Apache 2.0 license.
Copyright 2013-2023 Docker, inc, released under the <a href="https://github.com/docker/docs/blob/main/LICENSE">Apache 2.0 license</a> .

49
_config.yml
View File

@ -45,7 +45,7 @@ exclude:
latest_engine_api_version: "1.42"
docker_ce_version: "23.0.0"
compose_v1_version: "1.29.2"
compose_version: "v2.16.0"
compose_version: "v2.17.2"
compose_file_v3: "3.9"
compose_file_v2: "2.4"
machine_version: "0.16.0"
@ -215,3 +215,50 @@ fetch-remote:
- dest: "build/attestations/attestation-storage.md"
src:
- "docs/attestations/attestation-storage.md"
- repo: "https://github.com/compose-spec/compose-spec"
default_branch: "master"
ref: "master"
paths:
- dest: "compose/compose-file/01-status.md"
src:
- "01-status.md"
- dest: "compose/compose-file/02-model.md"
src:
- "02-model.md"
- dest: "compose/compose-file/03-compose-file.md"
src:
- "03-compose-file.md"
- dest: "compose/compose-file/04-version-and-name.md"
src:
- "04-version-and-name.md"
- dest: "compose/compose-file/05-services.md"
src:
- "05-services.md"
- dest: "compose/compose-file/06-networks.md"
src:
- "06-networks.md"
- dest: "compose/compose-file/07-volumes.md"
src:
- "07-volumes.md"
- dest: "compose/compose-file/08-configs.md"
src:
- "08-configs.md"
- dest: "compose/compose-file/09-secrets.md"
src:
- "09-secrets.md"
- dest: "compose/compose-file/10-fragments.md"
src:
- "10-fragments.md"
- dest: "compose/compose-file/11-extension.md"
src:
- "11-extension.md"
- dest: "compose/compose-file/12-interpolation.md"
src:
- "12-interpolation.md"
- dest: "compose/compose-file/build.md"
src:
- "build.md"
- dest: "compose/compose-file/deploy.md"
src:
- "deploy.md"

22
_data/compose-cli/docker_compose.yaml
View File

@ -63,12 +63,19 @@ long: |-
### Use `-p` to specify a project name
Each configuration has a project name. If you supply a `-p` flag, you can specify a project name. If you don’t
specify the flag, Compose uses the current directory name.
Project name can also be set by `COMPOSE_PROJECT_NAME` environment variable.
Many Compose subcommands can be run without a Compose file by passing
the project name.
Each configuration has a project name. Compose sets the project name using
the following mechanisms, in order of precedence:
- The `-p` command line flag
- The `COMPOSE_PROJECT_NAME` environment variable
- The top level `name:` variable from the config file (or the last `name:`
from a series of config files specified using `-f`)
- The `basename` of the project directory containing the config file (or
containing the first config file specified using `-f`)
- The `basename` of the current directory if no config file is specified
Project names must contain only lowercase letters, decimal digits, dashes,
and underscores, and must begin with a lowercase letter or decimal digit. If
the `basename` of the project directory or current directory violates this
constraint, you must use one of the other mechanisms.
```console
$ docker compose -p my_project ps -a
@ -198,7 +205,8 @@ options:
kubernetes: false
swarm: false
- option: env-file
value_type: string
value_type: stringArray
default_value: '[]'
description: Specify an alternate environment file.
deprecated: false
hidden: false

140
_data/compose-cli/docker_compose_convert.yaml Normal file
View File

@ -0,0 +1,140 @@
command: docker compose convert
aliases: docker compose convert, docker compose config
short: Converts the compose file to platform's canonical format
long: |-
`docker compose convert` renders the actual data model to be applied on the target platform. When used with the Docker engine,
it merges the Compose files set by `-f` flags, resolves variables in the Compose file, and expands short-notation into
the canonical format.
To allow smooth migration from docker-compose, this subcommand declares alias `docker compose config`
usage: docker compose convert [OPTIONS] [SERVICE...]
pname: docker compose
plink: docker_compose.yaml
options:
- option: format
value_type: string
default_value: yaml
description: 'Format the output. Values: [yaml | json]'
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: hash
value_type: string
description: Print the service config hash, one per line.
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: images
value_type: bool
default_value: "false"
description: Print the image names, one per line.
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: no-consistency
value_type: bool
default_value: "false"
description: |
Don't check model consistency - warning: may produce invalid Compose output
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: no-interpolate
value_type: bool
default_value: "false"
description: Don't interpolate environment variables.
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: no-normalize
value_type: bool
default_value: "false"
description: Don't normalize compose model.
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: output
shorthand: o
value_type: string
description: Save to file (default to stdout)
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: profiles
value_type: bool
default_value: "false"
description: Print the profile names, one per line.
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: quiet
shorthand: q
value_type: bool
default_value: "false"
description: Only validate the configuration, don't print anything.
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: resolve-image-digests
value_type: bool
default_value: "false"
description: Pin image tags to digests.
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: services
value_type: bool
default_value: "false"
description: Print the service names, one per line.
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: volumes
value_type: bool
default_value: "false"
description: Print the volume names, one per line.
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false

10
_data/compose-cli/docker_compose_restart.yaml
View File

@ -15,6 +15,16 @@ usage: docker compose restart [OPTIONS] [SERVICE...]
pname: docker compose
plink: docker_compose.yaml
options:
- option: no-deps
value_type: bool
default_value: "false"
description: Don't restart dependent services.
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: timeout
shorthand: t
value_type: int

34
_data/compose-cli/docker_compose_up.yaml
View File

@ -231,18 +231,6 @@ options:
experimentalcli: false
kubernetes: false
swarm: false
- option: timeout
shorthand: t
value_type: int
default_value: "10"
description: |
Use this timeout in seconds for container shutdown when attached or when containers are already running.
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: timestamps
value_type: bool
default_value: "false"
@ -263,6 +251,28 @@ options:
experimentalcli: false
kubernetes: false
swarm: false
- option: wait-timeout
value_type: int
default_value: "0"
description: timeout waiting for application to be running|healthy.
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: waitTimeout
shorthand: t
value_type: int
default_value: "10"
description: |
Use this waitTimeout in seconds for container shutdown when attached or when containers are already running.
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
deprecated: false
experimental: false
experimentalcli: false

150
_data/init-cli/docker_init.yaml Normal file
View File

@ -0,0 +1,150 @@
command: docker init
short: Creates Docker-related starter files for your project
long: |-
Initialize a project with the files necessary to run the project in a container.
Docker Desktop 4.18 and later provides the Docker Init plugin with the `docker init` CLI command. Run `docker init` in your project directory to be walked through the creation of the following files with sensible defaults for your project:
* .dockerignore
* Dockerfile
* docker-compose.yaml
If any of the files already exist, a prompt appears and provides a warning as well as giving you the option to overwrite all the files.
> **Warning**
>
> You can't recover overwritten files.
> To back up an existing file before selecting to overwrite it, rename the file or copy it to another directory.
{: .warning}
After running `docker init`, you can choose one of the following templates:
* Go: Suitable for a Go server application.
* Other: General purpose starting point for containerizing your application.
After `docker init` has completed, you must modify the created files and tailor them to your project. Visit the following topics to learn more about the files:
* [.dockerignore](../../../engine/reference/builder.md#dockerignore-file)
* [Dockerfile](../../../engine/reference/builder.md)
* [docker-compose.yaml](../../../compose/compose-file/03-compose-file.md)
usage: docker init [OPTIONS]
pname: docker
plink: docker.yaml
options:
- option: version
value_type: bool
default_value: "false"
description: Display version of the init plugin
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
examples: |-
### Example of selecting Other
The following example runs `docker init` and walks through the options after selecting `Other`.
```console
$ docker init
Welcome to the Docker Init CLI!
This utility will walk you through creating the following files with sensible defaults for your project:
- .dockerignore
- Dockerfile
- docker-compose.yaml
Let's get started!
? What application platform does your project use? [Use arrows to move, type to filter]
> Go - suitable for a Go server application
Other - general purpose starting point for containerizing your application
Don't see something you need? Let us know!
Quit
```
The following appears after selecting `Other`.
```console
CREATED: .dockerignore
CREATED: Dockerfile
CREATED: docker-compose.yaml
✔ Your Docker files are ready!
Take a moment to review them and tailor them to your application.
When you're ready, start your application by running: docker compose up --build
```
### Example of selecting Go
The following example runs `docker init` and walks through the options after selecting `Go`.
```console
$ docker init
Welcome to the Docker Init CLI!
This utility will walk you through creating the following files with sensible defaults for your project:
- .dockerignore
- Dockerfile
- docker-compose.yaml
Let's get started!
? What application platform does your project use? [Use arrows to move, type to filter]
> Go - (detected) suitable for a Go server application
Other - general purpose starting point for containerizing your application
Don't see something you need? Let us know!
Quit
```
The following appears after selecting `Go`.
```console
? What application platform does your project use? Go
? What version of Go do you want to use? (1.20)
```
The following appears after selecting the default `1.20`.
```console
? What version of Go do you want to use? 1.20
? What's the relative directory (with a leading .) of your main package? (.)
```
The following appears after selecting the default `.`.
```console
? What's the relative directory (with a leading .) of your main package? .
? What port does your server listen on? (3333)
```
The following appears after selecting the default `3333`.
```console
? What port does your server listen on? 3333
CREATED: .dockerignore
CREATED: Dockerfile
CREATED: docker-compose.yaml
✔ Your Docker files are ready!
Take a moment to review them and tailor them to your application.
When you're ready, start your application by running: docker compose up --build -d
Your application will be available at http://localhost:3333
To stop your application, run: docker compose down
```

6
_data/scout-cli/docker_scout.yaml
View File

@ -5,10 +5,16 @@ usage: docker scout [command]
pname: docker
plink: docker.yaml
cname:
- docker scout compare
- docker scout cves
- docker scout quickview
- docker scout recommendations
- docker scout version
clink:
- docker_scout_compare.yaml
- docker_scout_cves.yaml
- docker_scout_quickview.yaml
- docker_scout_recommendations.yaml
- docker_scout_version.yaml
deprecated: false
experimental: false

212
_data/scout-cli/docker_scout_compare.yaml Normal file
View File

@ -0,0 +1,212 @@
command: docker scout compare
short: '[early preview] Compare two images and display differences'
long: |-
The `docker scout compare` command analyzes two images and displays a comparison of both.
> This command is in **early preview** and its behaviour might change in the future
The main usage is to compare two versions of the same image.
For instance when a new image is built and compared to the version running in production.
The following artifact types are supported:
- Images
- OCI layout directories
- Tarball archives, as created by `docker save`
The tool analyzes the provided software artifact, and generates a vulnerability report.
By default, the tool expects an image reference, such as:
- `redis`
- `curlimages/curl:7.87.0`
- `mcr.microsoft.com/dotnet/runtime:7.0`
If the artifact you want to analyze is an OCI directory or a tarball archive, you must use the `--type` or `--to-type` flag.
usage: docker scout compare --to IMAGE|DIRECTORY|ARCHIVE IMAGE|DIRECTORY|ARCHIVE
pname: docker scout
plink: docker_scout.yaml
options:
- option: debug
value_type: bool
default_value: "false"
description: Debug messages
deprecated: false
hidden: true
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: format
value_type: string
default_value: text
description: |-
Output format of the generated vulnerability report:
- text: default output, plain text with or without colors depending on the terminal
- markdown: Markdown output
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: ignore-base
value_type: bool
default_value: "false"
description: Filter out CVEs introduced from base image
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: only-fixed
value_type: bool
default_value: "false"
description: Filter to fixable CVEs
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: only-package-type
value_type: stringSlice
default_value: '[]'
description: |
Comma separated list of package types (like apk, deb, rpm, npm, pypi, golang, etc)
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: only-severity
value_type: stringSlice
default_value: '[]'
description: |
Comma separated list of severities (critical, high, medium, low, unspecified) to filter CVEs by
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: only-unfixed
value_type: bool
default_value: "false"
description: Filter to unfixed CVEs
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: output
shorthand: o
value_type: string
description: Write the report to a file.
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: platform
value_type: string
description: Platform of image to analyze
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: ref
value_type: string
description: |-
Reference to use if the provided tarball contains multiple references.
Can only be used with --type archive.
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: to
value_type: string
description: image, directory or archive to compare to
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: to-ref
value_type: string
description: |-
Reference to use if the provided tarball contains multiple references.
Can only be used with --type archive.
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: to-type
value_type: string
default_value: image
description: |-
Type of the image to analyze. Can be one of:
- image
- oci-dir
- archive (docker save tarball)
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: type
value_type: string
default_value: image
description: |-
Type of the image to analyze. Can be one of:
- image
- oci-dir
- archive (docker save tarball)
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
examples: |-
### Compare an image to the latest tag
```console
$ docker scout compare --to namespace/repo:latest namespace/repo:v1.2.3-pre
```
### Ignore base images
```console
$ docker scout compare --ignore-base --to namespace/repo:latest namespace/repo:v1.2.3-pre
```
### Generate a markdown output
```console
$ docker scout compare --format markdown --to namespace/repo:latest namespace/repo:v1.2.3-pre
```
### Only compare maven packages and only display critical vulnerabilities for maven packages
```console
$ docker scout compare --only-package-type maven --only-severity critical --to namespace/repo:latest namespace/repo:v1.2.3-pre
```
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false

6
_data/scout-cli/docker_scout_cves.yaml
View File

@ -54,7 +54,7 @@ options:
swarm: false
- option: format
value_type: string
default_value: txt-by-packages
default_value: packages
description: |-
Output format of the generated vulnerability report:
- packages: default output, plain text with vulnerabilities grouped by packages
@ -111,7 +111,7 @@ options:
value_type: stringSlice
default_value: '[]'
description: |
Comma separated list of severities (critical, high, medium, low) to filter CVEs by
Comma separated list of severities (critical, high, medium, low, unspecified) to filter CVEs by
deprecated: false
hidden: false
experimental: false
@ -140,7 +140,7 @@ options:
swarm: false
- option: platform
value_type: string
description: Platform of image for which to list CVEs for
description: Platform of image to analyze
deprecated: false
hidden: false
experimental: false

91
_data/scout-cli/docker_scout_quickview.yaml Normal file
View File

@ -0,0 +1,91 @@
command: docker scout quickview
short: Quick overview of an image
long: |-
The `docker scout quickview` command displays a quick overview of an image.
It displays a summary of the vulnerabilities in the image and the vulnerabilities from the base image.
If available it also displays base image refresh and update recommendations.
usage: docker scout quickview IMAGE|DIRECTORY|ARCHIVE
pname: docker scout
plink: docker_scout.yaml
options:
- option: debug
value_type: bool
default_value: "false"
description: Debug messages
deprecated: false
hidden: true
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: output
shorthand: o
value_type: string
description: Write the report to a file.
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: platform
value_type: string
description: Platform of image to analyze
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: ref
value_type: string
description: |-
Reference to use if the provided tarball contains multiple references.
Can only be used with --type archive.
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: type
value_type: string
default_value: image
description: |-
Type of the image to analyze. Can be one of:
- image
- oci-dir
- archive (docker save tarball)
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
examples: |-
### Quick overview of an image
```console
$ docker scout quickview golang:1.19.4
...Pulling
✓ Pulled
✓ SBOM of image already cached, 278 packages indexed
Your image golang:1.19.4 │ 5C 3H 6M 63L
Base image buildpack-deps:bullseye-scm │ 5C 1H 3M 48L 6?
Refreshed base image buildpack-deps:bullseye-scm │ 0C 0H 0M 42L
│ -5 -1 -3 -6 -6
Updated base image buildpack-deps:sid-scm │ 0C 0H 1M 29L
│ -5 -1 -2 -19 -6
│ Know more about vulnerabilities:
│ docker scout cves golang:1.19.4
│ Know more about base image update recommendations:
│ docker scout recommendations golang:1.19.4
```
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false

133
_data/scout-cli/docker_scout_recommendations.yaml Normal file
View File

@ -0,0 +1,133 @@
command: docker scout recommendations
short: Display available base image updates and remediation recommendations
long: |-
The `docker scout recommendations` command display recommendations for base images updates.
It analyzes the image and display recommendations to refresh or update the base image.
For each recommendation it shows a list of benefits like less vulnerabilities, smaller image, etc.
The following artifact types are supported:
- Images
- OCI layout directories
- Tarball archives, as created by `docker save`
The tool analyzes the provided software artifact, and generates base image updates and remediation recommendations.
By default, the tool expects an image reference, such as:
- `redis`
- `curlimages/curl:7.87.0`
- `mcr.microsoft.com/dotnet/runtime:7.0`
If the artifact you want to analyze is an OCI directory or a tarball archive, you must use the `--type` flag.
usage: docker scout recommendations IMAGE|DIRECTORY|ARCHIVE
pname: docker scout
plink: docker_scout.yaml
options:
- option: debug
value_type: bool
default_value: "false"
description: Debug messages
deprecated: false
hidden: true
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: only-refresh
value_type: bool
default_value: "false"
description: Only display base image refresh recommendations
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: only-update
value_type: bool
default_value: "false"
description: Only display base image update recommendations
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: output
shorthand: o
value_type: string
description: Write the report to a file.
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: platform
value_type: string
description: Platform of image to analyze
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: ref
value_type: string
description: |-
Reference to use if the provided tarball contains multiple references.
Can only be used with --type archive.
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: tag
value_type: string
description: Specify tag
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: type
value_type: string
default_value: image
description: |-
Type of the image to analyze. Can be one of:
- image
- oci-dir
- archive (docker save tarball)
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
examples: |-
### Display base image update recommendations
```console
$ docker scout recommendations golang:1.19.4
```
### Display base image refresh only recommendations
```console
$ docker scout recommendations --only-refresh golang:1.19.4
```
### Display base image update only recommendations
```console
$ docker scout recommendations --only-update golang:1.19.4
```
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false

135
_data/scout-cli/docker_scout_sbom.yaml Normal file
View File

@ -0,0 +1,135 @@
command: docker scout sbom
short: Generate or display SBOM of an image
long: |-
The `docker scout sbom` command analyzes a software artifact to generate the corresponding Software Bill Of Materials (SBOM).
The SBOM can be used to list all packages, or the ones from a specific type (as dep, maven, etc).
The following artifact types are supported:
- Images
- OCI layout directories
- Tarball archives, as created by `docker save`
The tool analyzes the provided software artifact, and generates a vulnerability report.
By default, the tool expects an image reference, such as:
- `redis`
- `curlimages/curl:7.87.0`
- `mcr.microsoft.com/dotnet/runtime:7.0`
If the artifact you want to analyze is an OCI directory or a tarball archive, you must use the `--type` flag.
usage: docker scout sbom IMAGE|DIRECTORY|ARCHIVE
pname: docker scout
plink: docker_scout.yaml
options:
- option: debug
value_type: bool
default_value: "false"
description: Debug messages
deprecated: false
hidden: true
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: format
value_type: string
default_value: json
description: |-
Output format:
- list: list of packages of the image
- json: json representation of the SBOM
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: only-package-type
value_type: stringSlice
default_value: '[]'
description: |-
Comma separated list of package types (like apk, deb, rpm, npm, pypi, golang, etc)
Can only be used with --format list
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: output
shorthand: o
value_type: string
description: Write the report to a file.
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: platform
value_type: string
description: Platform of image to analyze
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: ref
value_type: string
description: |-
Reference to use if the provided tarball contains multiple references.
Can only be used with --type archive.
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: type
value_type: string
default_value: image
description: |-
Type of the image to analyze. Can be one of:
- image
- oci-dir
- archive (docker save tarball)
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
examples: |-
### Display the list of packages
```console
$ docker scout sbom alpine
```
### Only display packages of a specific type
```console
$ docker scout sbom --only-package-type apk alpine
```
### Display the full SBOM as json
```console
$ docker scout sbom --format json alpine
```
### Write SBOM to a file
```console
$ docker scout sbom --format json --output alpine.sbom alpine
```
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false

242
_data/toc.yaml
View File

@ -49,6 +49,18 @@ guides:
path: /get-started/09_image_best/
- title: "Part 10: What next?"
path: /get-started/11_what_next/
- sectiontitle: Docker Desktop hands-on guides
section:
- path: /get-started/hands-on-overview/
title: Overview
- path: /get-started/what-is-a-container/
title: What is a container?
- path: /get-started/run-your-own-container/
title: How do I run a container?
- path: /get-started/run-docker-hub-images/
title: Run Docker Hub images
- path: /get-started/publish-your-own-image/
title: Publish your images
- sectiontitle: Language-specific guides
section:
- path: /language/
@ -499,6 +511,8 @@ reference:
title: docker import
- path: /engine/reference/commandline/info/
title: docker info
- path: /engine/reference/commandline/init/
title: docker init (Beta)
- path: /engine/reference/commandline/inspect/
title: docker inspect
- path: /engine/reference/commandline/kill/
@ -609,8 +623,14 @@ reference:
section:
- path: /engine/reference/commandline/scout/
title: docker scout
- path: /engine/reference/commandline/scout_compare/
title: docker scout compare
- path: /engine/reference/commandline/scout_cves/
title: docker scout cves
- path: /engine/reference/commandline/scout_quickview/
title: docker scout quickview
- path: /engine/reference/commandline/scout_recommendations/
title: docker scout recommendations
- path: /engine/reference/commandline/scout_version/
title: docker scout version
- path: /engine/reference/commandline/search/
@ -884,8 +904,34 @@ reference:
path: /engine/reference/builder/
- sectiontitle: Compose file reference
section:
- path: /compose/compose-file/
title: Compose Specification
- sectiontitle: Compose specification
section:
- path: /compose/compose-file/
title: Overview
- path: /compose/compose-file/01-status/
title: Status of the specification
- path: /compose/compose-file/02-model/
title: Compose application model
- path: /compose/compose-file/03-compose-file/
title: The Compose file
- path: /compose/compose-file/04-version-and-name/
title: Version and name top-level element
- path: /compose/compose-file/05-services/
title: Services top-level element
- path: /compose/compose-file/06-networks/
title: Network top-level element
- path: /compose/compose-file/07-volumes/
title: Volumes top-level element
- path: /compose/compose-file/08-configs/
title: Configs top-level element
- path: /compose/compose-file/09-secrets/
title: Secrets top-level element
- path: /compose/compose-file/10-fragments/
title: Fragments
- path: /compose/compose-file/11-extension/
title: Extensions
- path: /compose/compose-file/12-interpolation/
title: Interpolation
- path: /compose/compose-file/build/
title: Compose file build
- path: /compose/compose-file/deploy/
@ -1581,6 +1627,16 @@ manuals:
title: Kubernetes driver
- path: /build/drivers/remote/
title: Remote driver
- sectiontitle: Exporters
section:
- path: /build/exporters/
title: Overview
- path: /build/exporters/image-registry/
title: Image and registry exporters
- path: /build/exporters/local-tar/
title: Local and tar exporters
- path: /build/exporters/oci-docker/
title: OCI and Docker exporters
- sectiontitle: Cache
section:
- path: /build/cache/
@ -1603,50 +1659,6 @@ manuals:
title: Azure Blob Storage
- path: /build/cache/backends/s3/
title: Amazon S3
- sectiontitle: Exporters
section:
- path: /build/exporters/
title: Overview
- path: /build/exporters/image-registry/
title: Image and registry exporters
- path: /build/exporters/local-tar/
title: Local and tar exporters
- path: /build/exporters/oci-docker/
title: OCI and Docker exporters
- sectiontitle: Continuous integration
section:
- path: /build/ci/
title: CI with Docker
- sectiontitle: GitHub Actions
section:
- path: /build/ci/github-actions/
title: Introduction
- path: /build/ci/github-actions/configure-builder/
title: Configuring your builder
- path: /build/ci/github-actions/multi-platform/
title: Multi-platform image
- path: /build/ci/github-actions/secrets/
title: Secrets
- path: /build/ci/github-actions/push-multi-registries/
title: Push to multi-registries
- path: /build/ci/github-actions/manage-tags-labels/
title: Manage tags and labels
- path: /build/ci/github-actions/cache/
title: Cache management
- path: /build/ci/github-actions/export-docker/
title: Export to Docker
- path: /build/ci/github-actions/test-before-push/
title: Test before push
- path: /build/ci/github-actions/local-registry/
title: Local registry
- path: /build/ci/github-actions/share-image-jobs/
title: Share built image between jobs
- path: /build/ci/github-actions/named-contexts/
title: Named contexts
- path: /build/ci/github-actions/copy-image-registries/
title: Copy image between registries
- path: /build/ci/github-actions/update-dockerhub-desc/
title: Update Docker Hub repo description
- sectiontitle: Bake
section:
- path: /build/bake/
@ -1683,6 +1695,40 @@ manuals:
title: Configure
- path: /build/buildkit/toml-configuration/
title: TOML configuration
- sectiontitle: Continuous integration
section:
- path: /build/ci/
title: CI with Docker
- sectiontitle: GitHub Actions
section:
- path: /build/ci/github-actions/
title: Introduction
- path: /build/ci/github-actions/configure-builder/
title: Configuring your builder
- path: /build/ci/github-actions/multi-platform/
title: Multi-platform image
- path: /build/ci/github-actions/secrets/
title: Secrets
- path: /build/ci/github-actions/push-multi-registries/
title: Push to multi-registries
- path: /build/ci/github-actions/manage-tags-labels/
title: Manage tags and labels
- path: /build/ci/github-actions/cache/
title: Cache management
- path: /build/ci/github-actions/export-docker/
title: Export to Docker
- path: /build/ci/github-actions/test-before-push/
title: Test before push
- path: /build/ci/github-actions/local-registry/
title: Local registry
- path: /build/ci/github-actions/share-image-jobs/
title: Share built image between jobs
- path: /build/ci/github-actions/named-contexts/
title: Named contexts
- path: /build/ci/github-actions/copy-image-registries/
title: Copy image between registries
- path: /build/ci/github-actions/update-dockerhub-desc/
title: Update Docker Hub repo description
- path: /build/release-notes/
title: Release notes
- sectiontitle: Docker Compose
@ -1741,68 +1787,54 @@ manuals:
section:
- path: /docker-hub/
title: Overview
- path: /docker-id/
title: Create an account
- path: /docker-hub/quickstart/
title: Quickstart
- path: /docker-id/
title: Docker ID accounts
- sectiontitle: Repositories
section:
- path: /docker-hub/repos/
title: Manage
- path: /docker-hub/repos/create/
title: Create
- path: /docker-hub/repos/access/
title: Access
- path: /docker-hub/repos/configure/
title: Configure
- path: /docker-hub/service-accounts/
title: Service accounts
- path: /docker-hub/repos/
title: Manage
- path: /docker-hub/official_images/
title: Docker Official images
- sectiontitle: Automated builds
section:
- path: /docker-hub/builds/
title: Set up automated builds
- path: /docker-hub/builds/automated-testing/
title: Testing in automated builds
- path: /docker-hub/builds/advanced/
title: Advanced automated builds
- path: /docker-hub/builds/link-source/
title: Link to GitHub and BitBucket
- path: /docker-hub/webhooks/
title: Webhooks
- path: /docker-hub/vulnerability-scanning/
title: Vulnerability scanning
- path: /docker-hub/audit-log/
title: Audit logs
- sectiontitle: Security and authentication
section:
- path: /docker-hub/access-tokens/
title: Manage access tokens
- sectiontitle: Two-factor authentication
section:
- path: /docker-hub/2fa/
title: Enable two-factor authentication
- path: /docker-hub/2fa/disable-2fa/
title: Disable two-factor authentication
- path: /docker-hub/2fa/recover-hub-account/
title: Recover your Docker Hub account
- path: /docker-hub/2fa/new-recovery-code/
title: Generate a new recovery code
- path: /docker-hub/download-rate-limit/
title: Download rate limit
- sectiontitle: Administration
- path: /docker-hub/webhooks/
title: Webhooks
- path: /docker-hub/service-accounts/
title: Service accounts
- sectiontitle: Automated builds
section:
- path: /docker-hub/image-management/
title: Advanced Image Management dashboard
- path: /docker-hub/convert-account/
title: Convert an account into an organization
- path: /docker-hub/deactivate-account/
title: Deactivate an account or an organization
- path: /docker-hub/builds/how-builds-work/
title: How Automated builds work
- path: /docker-hub/builds/
title: Set up Automated builds
- path: /docker-hub/builds/manage-builds/
title: Manage your builds
- path: /docker-hub/builds/troubleshoot/
title: Troubleshoot your builds
- path: /docker-hub/builds/automated-testing/
title: Testing in Automated builds
- path: /docker-hub/builds/advanced/
title: Advanced options for builds
- path: /docker-hub/builds/link-source/
title: Link to GitHub and BitBucket
- path: /docker-hub/vulnerability-scanning/
title: Vulnerability scanning
- path: /docker-hub/image-management/
title: Advanced Image Management
- sectiontitle: Docker Verified Publisher
section:
- path: /docker-hub/publish/
title: Overview
- path: /docker-hub/publish/insights-analytics/
title: Insights and analytics
- path: /docker-hub/dsos-program/
title: Docker-Sponsored Open Source Program
- path: /docker-hub/oci-artifacts/
title: OCI artifacts
- path: /docker-hub/release-notes/
@ -1819,8 +1851,10 @@ manuals:
- path: /scout/artifactory/
title: Artifactory integration
- sectiontitle: Administration
- sectiontitle: Administration and security
section:
- path: /docker-hub/admin-overview/
title: Overview
- sectiontitle: Onboarding
section:
- path: /docker-hub/onboard-team/
@ -1839,8 +1873,10 @@ manuals:
title: FAQs
- path: /docker-hub/orgs/
title: Create your organization
- path: /docker-hub/convert-account/
title: Convert an account into an organization
- path: /docker-hub/manage-a-team/
title: Manage a team
title: Create and manage a team
- path: /docker-hub/members/
title: Manage members
- path: /docker-hub/configure-sign-in/
@ -1859,10 +1895,30 @@ manuals:
title: FAQs
- path: /docker-hub/scim/
title: SCIM
- path: /docker-hub/group-mapping/
title: Group mapping
- sectiontitle: Security and authentication
section:
- path: /docker-hub/access-tokens/
title: Create and manage access tokens
- sectiontitle: Two-factor authentication
section:
- path: /docker-hub/2fa/
title: Enable two-factor authentication
- path: /docker-hub/2fa/disable-2fa/
title: Disable two-factor authentication
- path: /docker-hub/2fa/recover-hub-account/
title: Recover your Docker Hub account
- path: /docker-hub/2fa/new-recovery-code/
title: Generate a new recovery code
- path: /docker-hub/audit-log/
title: Audit logs
- path: /docker-hub/domain-audit/
title: Domain audit
- path: /docker-hub/image-access-management/
title: Image Access Management
- path: /docker-hub/deactivate-account/
title: Deactivate an account or organization
- sectiontitle: Billing
section:

18
_includes/desktop-install.html
View File

@ -13,7 +13,7 @@
<a class="btn btn-primary" href="https://desktop.docker.com/win/main/amd64/Docker%20Desktop%20Installer.exe?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-win-amd64" role="button">Download file</a>
<br>
<br>
<b>Checksum:</b> SHA-256 69ea659b0ca0e160a1de9bd63dc5697f5eb89fff1d33484fb8ef9793e43d0d45
<b>Checksum:</b> SHA-256 7b17e26d7c2d0245ba9f2526e20349e113819cfb47d1f3e8dbd3cc8ea8ccf6b7
</div>
</div>
</div>
@ -31,7 +31,7 @@
<a class="btn btn-primary" href="https://desktop.docker.com/mac/main/amd64/Docker.dmg?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-mac-amd64" role="button">Download file</a>
<br>
<br>
<b>Checksum:</b> SHA-256 eb0531122a62859ce7b029e943fdad365603a916e6c15c107514c1e4a818d7ef
<b>Checksum:</b> SHA-256 2e099af08e17666228282b970992160fa423ce8f5fa9e36b79495a1960803091
</div>
</div>
</div>
@ -49,7 +49,7 @@
<a class="btn btn-primary" href="https://desktop.docker.com/mac/main/arm64/Docker.dmg?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-mac-arm64" role="button">Download file</a>
<br>
<br>
<b>Checksum:</b> SHA-256 5e01465d93dfe18d7678a96705e7c26bb654b6766f06373b5cffbf77c641bccc
<b>Checksum:</b> SHA-256 2ae4b2ec556c107f969e51b72ad1920fefa38dbd0d8e3db64815c26b9f2b126d
</div>
</div>
</div>
@ -64,10 +64,10 @@
</div>
<div id="collapseFour" class="panel-collapse collapse" role="tabpanel" aria-labelledby="headingFour">
<div class="panel-body">
<a class="btn btn-primary" href="https://desktop.docker.com/linux/main/amd64/docker-desktop-4.17.0-amd64.deb?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-linux-amd64" role="button">Download file</a>
<a class="btn btn-primary" href="https://desktop.docker.com/linux/main/amd64/docker-desktop-4.18.0-amd64.deb?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-linux-amd64" role="button">Download file</a>
<br>
<br>
<b>Checksum:</b> SHA-256 6828d35ae02763255790de6690909935a1f7c951373179ac0efd6c6b578b5219
<b>Checksum:</b> SHA-256 d579f653b5223a3c24234992203283c5a6da28146702f8899964e08b8ba45198
</div>
</div>
</div>
@ -82,10 +82,10 @@
</div>
<div id="collapseFive" class="panel-collapse collapse" role="tabpanel" aria-labelledby="headingFive">
<div class="panel-body">
<a class="btn btn-primary" href="https://desktop.docker.com/linux/main/amd64/docker-desktop-4.17.0-x86_64.rpm?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-linux-amd64" role="button">Download file</a>
<a class="btn btn-primary" href="https://desktop.docker.com/linux/main/amd64/docker-desktop-4.18.0-x86_64.rpm?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-linux-amd64" role="button">Download file</a>
<br>
<br>
<b>Checksum:</b> SHA-256 7973c5bf41bdc78ca39ba64f93c6e4a33263d8dbfc604651bf1562bfeeea26f7
<b>Checksum:</b> SHA-256 4d64ea1c9e9da66ca0a37820135926eb4bbcdf658cafdbe87497aae384bf65c7
</div>
</div>
</div>
@ -100,10 +100,10 @@
</div>
<div id="collapseSix" class="panel-collapse collapse" role="tabpanel" aria-labelledby="headingSix">
<div class="panel-body">
<a class="btn btn-primary" href="https://desktop.docker.com/linux/main/amd64/docker-desktop-4.17.0-x86_64.pkg.tar.zst?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-linux-amd64" role="button">Download file</a>
<a class="btn btn-primary" href="https://desktop.docker.com/linux/main/amd64/docker-desktop-4.18.0-x86_64.pkg.tar.zst?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-linux-amd64" role="button">Download file</a>
<br>
<br>
<b>Checksum:</b> SHA-256 c783ce942c84f899d1f576d01d34fd4de3cefa0a1d577eda2bc5c4ceaec6cfdb
<b>Checksum:</b> SHA-256 0d6f8c54457f89cfaba3222ab4754caa8df547a0050aa8749d679609bad9456d
</div>
</div>
</div>

29
_layouts/landing.html
View File

@ -144,19 +144,18 @@
<p><a href="/build/building/multi-stage/">Multi-stage builds</a></p>
</div></div></div>
<div id="features" class="tab-pane fade" markdown="1">
<p><a href="/support/"target="_blank" rel="noopener">Get support</a></p>
<p><a href="/support/">Get support</a></p>
<p><a href="https://dockercommunity.slack.com/"target="_blank" rel="noopener">Docker community Slack</a></p>
<p><a href="https://www.docker.com/company/contact/"target="_blank" rel="noopener">Contact Docker</a></dp>
<p></a></p>
<p></a></div>
<p><a href="https://www.docker.com/company/contact/"target="_blank" rel="noopener">Contact Docker</a></p>
</div>
<div id="faqs" class="tab-pane fade" markdown="1">
<div class="row">
<div class="col-xs-12 col-md-6 col-lg-6">
<h6 style="margin-top: 0;">Common FAQs</h6>
<p><a href="https://github.com/docker/for-linux">What are the system requirements for Docker Desktop?</a></p>
<p><a href="/desktop/install/windows-install/#system-requirements">Where can I find example Compose files?</a></p>
<p><a href="/desktop/install/windows-install/#system-requirements"> <p><a href="/desktop/faqs/general/">How do I connect to a container service?</a></p></a></p>
<p><a href="/get-started/04_sharing_app/">How do I share images on Docker Hub?</a></p></a></p>
<p><a href="/desktop/faqs/general/#what-are-the-system-requirements-for-docker-desktop">What are the system requirements for Docker Desktop?</a></p>
<p><a href="https://github.com/docker/awesome-compose" target="_blank" rel="noopener">Where can I find example Compose files?</a></p>
<p><a href="/desktop/faqs/general/#how-do-i-connect-from-a-container-to-a-service-on-the-host">How do I connect from a container to a service?</a></p>
<p><a href="/get-started/04_sharing_app/">How do I share images on Docker Hub?</a></p>
</div>
<div class="col-xs-12 col-md-6 col-lg-6">
<h6 style="margin-top: 0;">Products</h6>
@ -165,7 +164,7 @@
<p><a href="/desktop/faqs/windowsfaqs/">Docker Desktop for Windows</a></p>
<p><a href="/desktop/faqs/linuxfaqs/">Docker Desktop for Linux</a></p>
<p><a href="/single-sign-on/faqs/">Docker Single Sign-on</a></p>
<p></a></p></div></div></div></div>
</div></div></div></div>
</div>
</div>
</div>
@ -367,11 +366,11 @@
<div class="col-xs-12 col-md-6">
<h2 class="title">Develop with Docker</h2>
<p>Learn how to develop language-specific apps using Docker.</p>
<p><a href="/language/nodejs/" target="_blank" rel="noopener">Containerize a Node.js app using Docker</a></p>
<p><a href="/language/python/" target="_blank" rel="noopener">Containerize a Python app using Docker</a></p>
<p><a href="/language/java/" target="_blank" rel="noopener">Containerize a Java app using Docker</a></p>
<p><a href="/language/golang/" target="_blank" rel="noopener">Containerize a Go app using Docker</a></p>
<p><a href="/samples/" target="_blank" rel="noopener">View more languages and frameworks in Docker samples</a></p>
<p><a href="/language/nodejs/" >Containerize a Node.js app using Docker</a></p>
<p><a href="/language/python/">Containerize a Python app using Docker</a></p>
<p><a href="/language/java/">Containerize a Java app using Docker</a></p>
<p><a href="/language/golang/">Containerize a Go app using Docker</a></p>
<p><a href="/samples/">View more languages and frameworks in Docker samples</a></p>
</div>
</div>
</div>
@ -386,7 +385,7 @@
</div>
<div class="row">
<div class="col-xs-12 col-sm-6 col-md-4 card-holder">
<a href="/get-started/" class="card" target="_blank" rel="noopener">
<a href="/get-started/" class="card">
<h5 class="title">Tutorial</h5>
<p>Self-paced tutorials to increase your Docker knowledge.</p>
</a>

38
assets/images/arrow-up.svg Normal file
View File

@ -0,0 +1,38 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<svg
viewBox="0 0 384 512"
version="1.1"
id="svg4"
sodipodi:docname="arrow-up.svg"
inkscape:version="1.2.2 (732a01da63, 2022-12-09)"
xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
xmlns="http://www.w3.org/2000/svg"
xmlns:svg="http://www.w3.org/2000/svg">
<defs
id="defs8" />
<sodipodi:namedview
id="namedview6"
pagecolor="#ffffff"
bordercolor="#000000"
borderopacity="0.25"
inkscape:showpageshadow="2"
inkscape:pageopacity="0.0"
inkscape:pagecheckerboard="0"
inkscape:deskcolor="#d1d1d1"
showgrid="false"
inkscape:zoom="1.6191406"
inkscape:cx="93.568154"
inkscape:cy="256.30881"
inkscape:window-width="1920"
inkscape:window-height="1009"
inkscape:window-x="-8"
inkscape:window-y="-8"
inkscape:window-maximized="1"
inkscape:current-layer="svg4" />
<!--! Font Awesome Free 6.3.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2023 Fonticons, Inc. -->
<path
d="M214.6 41.4c-12.5-12.5-32.8-12.5-45.3 0l-160 160c-12.5 12.5-12.5 32.8 0 45.3s32.8 12.5 45.3 0L160 141.2V448c0 17.7 14.3 32 32 32s32-14.3 32-32V141.2L329.4 246.6c12.5 12.5 32.8 12.5 45.3 0s12.5-32.8 0-45.3l-160-160z"
id="path2"
style="fill:#666666;stroke:#677285;stroke-opacity:1" />
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 1.5 KiB

1
assets/images/desktop.svg Normal file
View File

@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" height="24px" viewBox="0 0 24 24" width="24px" fill="#677285"><path d="M19 4H5c-1.11 0-2 .9-2 2v12c0 1.1.89 2 2 2h14c1.1 0 2-.9 2-2V6c0-1.1-.89-2-2-2zm-1 14H6c-.55 0-1-.45-1-1V8h14v9c0 .55-.45 1-1 1z"/></svg>
Side by Side

After

Width:  |  Height:  |  Size: 248 B

1
assets/images/sign-on.svg Normal file
View File

@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" height="24px" viewBox="0 0 24 24" width="24px" fill="#677285"><path d="M0 0h24v24H0V0z" fill="none"/><path d="M12.65 10C11.7 7.31 8.9 5.5 5.77 6.12c-2.29.46-4.15 2.29-4.63 4.58C.32 14.57 3.26 18 7 18c2.61 0 4.83-1.67 5.65-4H17v2c0 1.1.9 2 2 2s2-.9 2-2v-2c1.1 0 2-.9 2-2s-.9-2-2-2h-8.35zM7 14c-1.1 0-2-.9-2-2s.9-2 2-2 2 .9 2 2-.9 2-2 2z"/></svg>
Side by Side

After

Width:  |  Height:  |  Size: 384 B

1
assets/images/sso.svg Normal file
View File

@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" enable-background="new 0 0 24 24" height="24px" viewBox="0 0 24 24" width="24px" fill="#677285"><g><rect fill="none" height="24" width="24"/><rect fill="none" height="24" width="24"/></g><g><path d="M22,9V8c0-0.55-0.45-1-1-1h0c-0.55,0-1,0.45-1,1v1h-1c-0.55,0-1,0.45-1,1v0c0,0.55,0.45,1,1,1h1v1c0,0.55,0.45,1,1,1h0 c0.55,0,1-0.45,1-1v-1h1c0.55,0,1-0.45,1-1v0c0-0.55-0.45-1-1-1H22z"/><g><path d="M8,12c2.21,0,4-1.79,4-4s-1.79-4-4-4S4,5.79,4,8S5.79,12,8,12z"/><path d="M8,13c-2.67,0-8,1.34-8,4v3h16v-3C16,14.34,10.67,13,8,13z"/><path d="M12.51,4.05C13.43,5.11,14,6.49,14,8s-0.57,2.89-1.49,3.95C14.47,11.7,16,10.04,16,8S14.47,4.3,12.51,4.05z"/><path d="M16.53,13.83C17.42,14.66,18,15.7,18,17v3h2v-3C20,15.55,18.41,14.49,16.53,13.83z"/></g></g></svg>
Side by Side

After

Width:  |  Height:  |  Size: 785 B

2
assets/js/anchorlinks.js
View File

@ -1,7 +1,7 @@
(function (d) {
"use strict";
for (const h of d.querySelectorAll("H1, H2, H3")) {
if (h.id != null && h.id.length > 0) {
if (h.id != null && h.id.length > 0 && !h.parentElement.classList.contains("component")) {
h.insertAdjacentHTML('beforeend', `<a href="#${h.id}" class="anchorLink">🔗</a>`)
}
}

12
billing/faqs.md
View File

@ -48,3 +48,15 @@ Contact the [Docker Sales Team](https://www.docker.com/company/contact){:target=
### Do I need to do anything at the end of my subscription term?
No. All monthly and annual subscriptions are automatically renewed at the end of the term using the original form of payment.
### How do I redeem a coupon?
You can redeem a coupon for any paid Docker subscription.
A coupon can be used when you:
- Sign up to a new paid subscription from a free subscription
- Upgrade an existing paid subscription
You are asked to enter your coupon code when you confirm or enter your payment method.
If you use a coupon to pay for a subscription, when the coupon expires, your payment method is charged the full cost of your subscription. If you do not have a saved payment method, your account is downgraded to a free subscription.

2
build/attestations/sbom.md
View File

@ -214,7 +214,7 @@ an open source tool for generating an SBOM.
You can select a different plugin to use with the `generator` option, specifying
an image that implements the
[BuildKit SBOM scanner protocol](https://github.com/moby/buildkit/blob/master/docs/sbom-protocol.md){: target="blank" rel="noopener" }.
[BuildKit SBOM scanner protocol](https://github.com/moby/buildkit/blob/master/docs/attestations/sbom-protocol.md){: target="blank" rel="noopener" }.
```console
$ docker buildx build --attest type=sbom,generator=<image> .

4
build/bake/compose-file.md
View File

@ -98,7 +98,7 @@ Unlike the [HCL format](file-definition.md#hcl-definition), there are some
limitations with the compose format:
* Specifying variables or global scope attributes is not yet supported
* `inherits` service field is not supported, but you can use [YAML anchors](https://docs.docker.com/compose/compose-file/#fragments){:target="blank" rel="noopener" class=""}
* `inherits` service field is not supported, but you can use [YAML anchors](../../compose/compose-file/10-fragments.md){:target="blank" rel="noopener" class=""}
to reference other services like the example above
## `.env` file
@ -155,7 +155,7 @@ $ docker buildx bake --print
## Extension field with `x-bake`
Even if some fields are not (yet) available in the compose specification, you
can use the [special extension](../../compose/compose-file/index.md#extension)
can use the [special extension](../../compose/compose-file/11-extension.md)
field `x-bake` in your compose file to evaluate extra fields:
```yaml

2
build/building/env-vars.md
View File

@ -183,7 +183,7 @@ attestations.
Usage:
```console
$ export BUILDX_NO_DEFAULT_ATTESTATION=1
$ export BUILDX_NO_DEFAULT_ATTESTATIONS=1
```
## BUILDX_NO_DEFAULT_LOAD

56
build/index.md
View File

@ -96,34 +96,6 @@ advanced scenarios.
</p>
</div>
</div>
<div class="col-xs-12 col-sm-12 col-md-12 col-lg-4 block">
<div class="component">
<div class="component-icon">
<a href="/build/cache/">
<img src="/assets/images/build-cache.svg" alt="Two arrows rotating in a circle" width="70px" height="70px">
</a>
</div>
<h2><a href="/build/cache/">Build caching</a></h2>
<p>
Avoid unnecessary repetitions of costly operations, such as package installs.
</p>
</div>
</div>
<div class="col-xs-12 col-sm-12 col-md-12 col-lg-4 block">
<div class="component">
<div class="component-icon">
<a href="/build/ci/">
<img src="/assets/images/build-ci.svg" alt="Infinity loop" width="70px" height="70px">
</a>
</div>
<h2><a href="/build/ci/">Continuous integration</a></h2>
<p>
Learn how to use Docker in your continuous integration pipelines.
</p>
</div>
</div>
</div>
<div class="row">
<div class="col-xs-12 col-sm-12 col-md-12 col-lg-4 block">
<div class="component">
<div class="component-icon">
@ -137,6 +109,21 @@ advanced scenarios.
</p>
</div>
</div>
<div class="col-xs-12 col-sm-12 col-md-12 col-lg-4 block">
<div class="component">
<div class="component-icon">
<a href="/build/cache/">
<img src="/assets/images/build-cache.svg" alt="Two arrows rotating in a circle" width="70px" height="70px">
</a>
</div>
<h2><a href="/build/cache/">Build caching</a></h2>
<p>
Avoid unnecessary repetitions of costly operations, such as package installs.
</p>
</div>
</div>
</div>
<div class="row">
<div class="col-xs-12 col-sm-12 col-md-12 col-lg-4 block">
<div class="component">
<div class="component-icon">
@ -150,6 +137,19 @@ advanced scenarios.
</p>
</div>
</div>
<div class="col-xs-12 col-sm-12 col-md-12 col-lg-4 block">
<div class="component">
<div class="component-icon">
<a href="/build/ci/">
<img src="/assets/images/build-ci.svg" alt="Infinity loop" width="70px" height="70px">
</a>
</div>
<h2><a href="/build/ci/">Continuous integration</a></h2>
<p>
Learn how to use Docker in your continuous integration pipelines.
</p>
</div>
</div>
<div class="col-xs-12 col-sm-12 col-md-12 col-lg-4 block">
<div class="component">
<div class="component-icon">

4
build/install-buildx.md
View File

@ -6,6 +6,10 @@ redirect_from:
- /build/buildx/install/
---
This page describes how to install Buildx, the CLI plugin for managing Docker builds.
Buildx requires Docker Engine version 19.03 or later.
## Docker Desktop
Docker Buildx is included by default in Docker Desktop.

7
compose/compose-file/01-status.md Normal file
View File

@ -0,0 +1,7 @@
---
title: Status of the specification
keywords: compose, compose specification
fetch_remote:
line_start: 2
line_end: -1
---

7
compose/compose-file/02-model.md Normal file
View File

@ -0,0 +1,7 @@
---
title: Compose application model
keywords: compose, compose specification
fetch_remote:
line_start: 2
line_end: -1
---

7
compose/compose-file/03-compose-file.md Normal file
View File

@ -0,0 +1,7 @@
---
title: The Compose file
keywords: compose, compose specification
fetch_remote:
line_start: 2
line_end: -1
---

7
compose/compose-file/04-version-and-name.md Normal file
View File

@ -0,0 +1,7 @@
---
title: Version and name top-level element
keywords: compose, compose specification
fetch_remote:
line_start: 2
line_end: -1
---

7
compose/compose-file/05-services.md Normal file
View File

@ -0,0 +1,7 @@
---
title: Services top-level element
keywords: compose, compose specification
fetch_remote:
line_start: 2
line_end: -1
---

7
compose/compose-file/06-networks.md Normal file
View File

@ -0,0 +1,7 @@
---
title: Networks top-level element
keywords: compose, compose specification
fetch_remote:
line_start: 2
line_end: -1
---

7
compose/compose-file/07-volumes.md Normal file
View File

@ -0,0 +1,7 @@
---
title: Volumes top-level element
keywords: compose, compose specification
fetch_remote:
line_start: 2
line_end: -1
---

7
compose/compose-file/08-configs.md Normal file
View File

@ -0,0 +1,7 @@
---
title: Configs top-level element
keywords: compose, compose specification
fetch_remote:
line_start: 2
line_end: -1
---

7
compose/compose-file/09-secrets.md Normal file
View File

@ -0,0 +1,7 @@
---
title: Secrets top-level element
keywords: compose, compose specification
fetch_remote:
line_start: 2
line_end: -1
---

7
compose/compose-file/10-fragments.md Normal file
View File

@ -0,0 +1,7 @@
---
title: Fragments
keywords: compose, compose specification
fetch_remote:
line_start: 2
line_end: -1
---

7
compose/compose-file/11-extension.md Normal file
View File

@ -0,0 +1,7 @@
---
title: Extensions
keywords: compose, compose specification
fetch_remote:
line_start: 2
line_end: -1
---

7
compose/compose-file/12-interpolation.md Normal file
View File

@ -0,0 +1,7 @@
---
title: Interpolation
keywords: compose, compose specification
fetch_remote:
line_start: 2
line_end: -1
---

436
compose/compose-file/build.md
View File

@ -1,435 +1,7 @@
---
description: Compose file build reference
keywords: fig, composition, compose, docker
title: Compose file build reference
toc_max: 4
toc_min: 2
keywords: fig, composition, compose, docker
fetch_remote:
line_start: 8
line_end: -1
---
Compose specification is a platform-neutral way to define multi-container applications. A Compose implementation
focusing on development use-case to run application on local machine will obviously also support (re)building
application from sources. The Compose Build specification allows to define the build process within a Compose file
in a portable way.
## Definitions
Compose Specification is extended to support an OPTIONAL `build` subsection on services. This section define the
build requirements for service container image. Only a subset of Compose file services MAY define such a Build
subsection, others being created based on `Image` attribute. When a Build subsection is present for a service, it
is *valid* for a Compose file to miss an `Image` attribute for corresponding service, as Compose implementation
can build image from source.
Build can be either specified as a single string defining a context path, or as a detailed build definition.
In the former case, the whole path is used as a Docker context to execute a docker build, looking for a canonical
`Dockerfile` at context root. Context path can be absolute or relative, and if so relative path MUST be resolved
from Compose file parent folder. As an absolute path prevent the Compose file to be portable, Compose implementation
SHOULD warn user accordingly.
In the later case, build arguments can be specified, including an alternate `Dockerfile` location. This one can be
absolute or relative path. If Dockerfile path is relative, it MUST be resolved from context path. As an absolute
path prevent the Compose file to be portable, Compose implementation SHOULD warn user if an absolute alternate
Dockerfile path is used.
## Consistency with Image
When service definition do include both `Image` attribute and a `Build` section, Compose implementation can't
guarantee a pulled image is strictly equivalent to building the same image from sources. Without any explicit
user directives, Compose implementation with Build support MUST first try to pull Image, then build from source
if image was not found on registry. Compose implementation MAY offer options to customize this behaviour by user
request.
## Publishing built images
Compose implementation with Build support SHOULD offer an option to push built images to a registry. Doing so, it
MUST NOT try to push service images without an `Image` attribute. Compose implementation SHOULD warn user about
missing `Image` attribute which prevent image being pushed.
Compose implementation MAY offer a mechanism to compute an `Image` attribute for service when not explicitly
declared in yaml file. In such a case, the resulting Compose configuration is considered to have a valid `Image`
attribute, whenever the actual raw yaml file doesn't explicitly declare one.
## Illustrative sample
The following sample illustrates Compose specification concepts with a concrete sample application. The sample is non-normative.
```yaml
services:
frontend:
image: awesome/webapp
build: ./webapp
backend:
image: awesome/database
build:
context: backend
dockerfile: ../backend.Dockerfile
custom:
build: ~/custom
```
When used to build service images from source, such a Compose file will create three docker images:
* `awesome/webapp` docker image is built using `webapp` sub-directory within Compose file parent folder as docker build context. Lack of a `Dockerfile` within this folder will throw an error.
* `awesome/database` docker image is built using `backend` sub-directory within Compose file parent folder. `backend.Dockerfile` file is used to define build steps, this file is searched relative to context path, which means for this sample `..` will resolve to Compose file parent folder, so `backend.Dockerfile` is a sibling file.
* a docker image is built using `custom` directory within user's HOME as docker context. Compose implementation warn user about non-portable path used to build image.
On push, both `awesome/webapp` and `awesome/database` docker images are pushed to (default) registry. `custom` service image is skipped as no `Image` attribute is set and user is warned about this missing attribute.
## Build definition
The `build` element define configuration options that are applied by Compose implementations to build Docker image from source.
`build` can be specified either as a string containing a path to the build context or a detailed structure:
```yml
services:
webapp:
build: ./dir
```
Using this string syntax, only the build context can be configured as a relative path to the Compose file's parent folder.
This path MUST be a directory and contain a `Dockerfile`.
Alternatively `build` can be an object with fields defined as follow
### context (REQUIRED)
`context` defines either a path to a directory containing a Dockerfile, or a url to a git repository.
When the value supplied is a relative path, it MUST be interpreted as relative to the location of the Compose file.
Compose implementations MUST warn user about absolute path used to define build context as those prevent Compose file
from being portable.
```yml
build:
context: ./dir
```
See [Build context](../../build/building/context.md) page for more information.
### dockerfile
`dockerfile` allows to set an alternate Dockerfile. A relative path MUST be resolved from the build context.
Compose implementations MUST warn user about absolute path used to define Dockerfile as those prevent Compose file
from being portable.
```yml
build:
context: .
dockerfile: webapp.Dockerfile
```
### args
`args` define build arguments, i.e. Dockerfile `ARG` values.
Using following Dockerfile:
```Dockerfile
ARG GIT_COMMIT
RUN echo "Based on commit: $GIT_COMMIT"
```
`args` can be set in Compose file under the `build` key to define `GIT_COMMIT`. `args` can be set a mapping or a list:
```yml
build:
context: .
args:
GIT_COMMIT: cdc3b19
```
```yml
build:
context: .
args:
- GIT_COMMIT=cdc3b19
```
Value can be omitted when specifying a build argument, in which case its value at build time MUST be obtained by user interaction,
otherwise build arg won't be set when building the Docker image.
```yml
args:
- GIT_COMMIT
```
### ssh
`ssh` defines SSH authentications that the image builder SHOULD use during image build (e.g., cloning private repository)
`ssh` property syntax can be either:
* `default` - let the builder connect to the ssh-agent.
* `ID=path` - a key/value definition of an ID and the associated path. Can be either a [PEM](https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail) file, or path to ssh-agent socket
Simple `default` sample
```yaml
build:
context: .
ssh:
- default # mount the default ssh agent
```
or
```yaml
build:
context: .
ssh: ["default"] # mount the default ssh agent
```
Using a custom id `myproject` with path to a local SSH key:
```yaml
build:
context: .
ssh:
- myproject=~/.ssh/myproject.pem
```
Image builder can then rely on this to mount SSH key during build.
For illustration, [BuildKit extended syntax](https://github.com/compose-spec/compose-spec/pull/234/%5Bmoby/buildkit@master/frontend/dockerfile/docs/syntax.md#run---mounttypessh%5D(https://github.com/moby/buildkit/blob/master/frontend/dockerfile/docs/syntax.md#run---mounttypessh)) can be used to mount ssh key set by ID and access a secured resource:
`RUN --mount=type=ssh,id=myproject git clone ...`
### cache_from
`cache_from` defines a list of sources the Image builder SHOULD use for cache resolution.
Cache location syntax MUST follow the global format `[NAME|type=TYPE[,KEY=VALUE]]`. Simple `NAME` is actually a shortcut notation for `type=registry,ref=NAME`.
Compose Builder implementations MAY support custom types, the Compose Specification defines canonical types which MUST be supported:
- `registry` to retrieve build cache from an OCI image set by key `ref`
```yml
build:
context: .
cache_from:
- alpine:latest
- type=local,src=path/to/cache
- type=gha
```
Unsupported caches MUST be ignored and not prevent user from building image.
### cache_to
`cache_to` defines a list of export locations to be used to share build cache with future builds.
```yml
build:
context: .
cache_to:
- user/app:cache
- type=local,dest=path/to/cache
```
Cache target is defined using the same `type=TYPE[,KEY=VALUE]` syntax defined by [`cache_from`](#cache_from).
Unsupported cache target MUST be ignored and not prevent user from building image.
### extra_hosts
`extra_hosts` adds hostname mappings at build-time. Use the same syntax as [extra_hosts](index.md#extra_hosts).
```yml
extra_hosts:
- "somehost:162.242.195.82"
- "otherhost:50.31.209.229"
```
Compose implementations MUST create matching entry with the IP address and hostname in the container's network
configuration, which means for Linux `/etc/hosts` will get extra lines:
```
162.242.195.82 somehost
50.31.209.229 otherhost
```
### isolation
`isolation` specifies a build’s container isolation technology. Like [isolation](index.md#isolation) supported values
are platform-specific.
### labels
`labels` add metadata to the resulting image. `labels` can be set either as an array or a map.
reverse-DNS notation SHOULD be used to prevent labels from conflicting with those used by other software.
```yml
build:
context: .
labels:
com.example.description: "Accounting webapp"
com.example.department: "Finance"
com.example.label-with-empty-value: ""
```
```yml
build:
context: .
labels:
- "com.example.description=Accounting webapp"
- "com.example.department=Finance"
- "com.example.label-with-empty-value"
```
### no_cache
`no_cache` disables image builder cache and enforces a full rebuild from source for all image layers. This only
applies to layers declared in the Dockerfile, referenced images COULD be retrieved from local image store whenever tag
has been updated on registry (see [pull](#pull)).
### pull
`pull` requires the image builder to pull referenced images (`FROM` Dockerfile directive), even if those are already
available in the local image store.
### shm_size
`shm_size` set the size of the shared memory (`/dev/shm` partition on Linux) allocated for building Docker image. Specify
as an integer value representing the number of bytes or as a string expressing a [byte value](index.md#specifying-byte-values).
```yml
build:
context: .
shm_size: '2gb'
```
```yaml
build:
context: .
shm_size: 10000000
```
### target
`target` defines the stage to build as defined inside a multi-stage `Dockerfile`.
```yml
build:
context: .
target: prod
```
### secrets
`secrets` grants access to sensitive data defined by [secrets](index.md#secrets) on a per-service build basis. Two
different syntax variants are supported: the short syntax and the long syntax.
Compose implementations MUST report an error if the secret isn't defined in the
[`secrets`](index.md#secrets-top-level-element) section of the Compose file.
#### Short syntax
The short syntax variant only specifies the secret name. This grants the
container access to the secret and mounts it as read-only to `/run/secrets/<secret_name>`
within the container. The source name and destination mountpoint are both set
to the secret name.
The following example uses the short syntax to grant the build of the `frontend` service
access to the `server-certificate` secret. The value of `server-certificate` is set
to the contents of the file `./server.cert`.
```yml
services:
frontend:
build:
context: .
secrets:
- server-certificate
secrets:
server-certificate:
file: ./server.cert
```
#### Long syntax
The long syntax provides more granularity in how the secret is created within
the service's containers.
- `source`: The name of the secret as it exists on the platform.
- `target`: The name of the file to be mounted in `/run/secrets/` in the
service's task containers. Defaults to `source` if not specified.
- `uid` and `gid`: The numeric UID or GID that owns the file within
`/run/secrets/` in the service's task containers. Default value is USER running container.
- `mode`: The [permissions](https://chmod-calculator.com/) for the file to be mounted in `/run/secrets/`
in the service's task containers, in octal notation.
Default value is world-readable permissions (mode `0444`).
The writable bit MUST be ignored if set. The executable bit MAY be set.
The following example sets the name of the `server-certificate` secret file to `server.crt`
within the container, sets the mode to `0440` (group-readable), and sets the user and group
to `103`. The value of `server-certificate` secret is provided by the platform through a lookup and
the secret lifecycle is not directly managed by the Compose implementation.
```yml
services:
frontend:
build:
context: .
secrets:
- source: server-certificate
target: server.cert
uid: "103"
gid: "103"
mode: 0440
secrets:
server-certificate:
external: true
```
Service builds MAY be granted access to multiple secrets. Long and short syntax for secrets MAY be used in the
same Compose file. Defining a secret in the top-level `secrets` MUST NOT imply granting any service build access to it.
Such grant must be explicit within the service specification as a [secrets](index.md#secrets) service element.
### tags
`tags` defines a list of tag mappings that MUST be associated to the build image. This list comes in addition of
the `image` [property defined in the service section](index.md#image)
```yml
tags:
- "myimage:mytag"
- "registry/username/myrepos:my-other-tag"
```
### platforms
`platforms` defines a list of target [platforms](index.md#platform).
```yml
build:
context: "."
platforms:
- "linux/amd64"
- "linux/arm64"
```
When the `platforms` attribute is omitted, Compose implementations MUST include the service's platform
in the list of the default build target platforms.
Compose implementations SHOULD report an error in the following cases:
* when the list contains multiple platforms but the implementation is incapable of storing multi-platform images
* when the list contains an unsupported platform
```yml
build:
context: "."
platforms:
- "linux/amd64"
- "unsupported/unsupported"
```
* when the list is non-empty and does not contain the service's platform
```yml
services:
frontend:
platform: "linux/amd64"
build:
context: "."
platforms:
- "linux/arm64"
```
## Implementations
* [docker-compose](../../compose/index.md)
* [buildx bake](../../build/bake/index.md)

299
compose/compose-file/deploy.md
View File

@ -1,298 +1,7 @@
---
description: Compose file deploy reference
keywords: fig, composition, compose, docker
title: Compose file deploy reference
toc_max: 4
toc_min: 2
keywords: fig, composition, compose, docker
fetch_remote:
line_start: 8
line_end: -1
---
Compose specification is a platform-neutral way to define multi-container applications. A Compose implementation supporting
deployment of application model MAY require some additional metadata as the Compose application model is way too abstract
to reflect actual infrastructure needs per service, or lifecycle constraints.
Compose Specification Deployment allows users to declare additional metadata on services so Compose implementations get
relevant data to allocate adequate resources on platform and configure them to match user's needs.
## Definitions
Compose Specification is extended to support an OPTIONAL `deploy` subsection on services. This section define runtime requirements
for a service.
### endpoint_mode
`endpoint_mode` specifies a service discovery method for external clients connecting to a service. Default and available values
are platform specific, anyway the Compose specification define two canonical values:
* `endpoint_mode: vip`: Assigns the service a virtual IP (VIP) that acts as the front end for clients to reach the service
on a network. Platform routes requests between the client and nodes running the service, without client knowledge of how
many nodes are participating in the service or their IP addresses or ports.
* `endpoint_mode: dnsrr`: Platform sets up DNS entries for the service such that a DNS query for the service name returns a
list of IP addresses (DNS round-robin), and the client connects directly to one of these.
```yml
services:
frontend:
image: awesome/webapp
ports:
- "8080:80"
deploy:
mode: replicated
replicas: 2
endpoint_mode: vip
```
### labels
`labels` specifies metadata for the service. These labels MUST *only* be set on the service and *not* on any containers for the service.
This assumes the platform has some native concept of "service" that can match Compose application model.
```yml
services:
frontend:
image: awesome/webapp
deploy:
labels:
com.example.description: "This label will appear on the web service"
```
### mode
`mode` define the replication model used to run the service on platform. Either `global` (exactly one container per physical node) or `replicated` (a specified number of containers). The default is `replicated`.
```yml
services:
frontend:
image: awesome/webapp
deploy:
mode: global
```
### placement
`placement` specifies constraints and preferences for platform to select a physical node to run service containers.
#### constraints
`constraints` defines a REQUIRED property the platform's node MUST fulfill to run service container. Can be set either
by a list or a map with string values.
```yml
deploy:
placement:
constraints:
- disktype=ssd
```
```yml
deploy:
placement:
constraints:
disktype: ssd
```
#### preferences
`preferences` defines a property the platform's node SHOULD fulfill to run service container. Can be set either
by a list or a map with string values.
```yml
deploy:
placement:
preferences:
- datacenter=us-east
```
```yml
deploy:
placement:
preferences:
datacenter: us-east
```
### replicas
If the service is `replicated` (which is the default), `replicas` specifies the number of containers that SHOULD be
running at any given time.
```yml
services:
frontend:
image: awesome/webapp
deploy:
mode: replicated
replicas: 6
```
### resources
`resources` configures physical resource constraints for container to run on platform. Those constraints can be configured
as a:
- `limits`: The platform MUST prevent container to allocate more
- `reservations`: The platform MUST guarantee container can allocate at least the configured amount
```yml
services:
frontend:
image: awesome/webapp
deploy:
resources:
limits:
cpus: '0.50'
memory: 50M
pids: 1
reservations:
cpus: '0.25'
memory: 20M
```
#### cpus
`cpus` configures a limit or reservation for how much of the available CPU resources (as number of cores) a container can use.
#### memory
`memory` configures a limit or reservation on the amount of memory a container
can allocate, set as a string expressing a
[byte value](index.md#specifying-byte-values).
#### pids
`pids` tunes a container’s PIDs limit, set as an integer.
#### devices
`devices` configures reservations of the devices a container can use. It contains a list of reservations, each set as an object with the following parameters: `capabilities`, `driver`, `count`, `device_ids` and `options`.
Devices are reserved using a list of capabilities, making `capabilities` the only required field. A device MUST satisfy all the requested capabilities for a successful reservation.
##### capabilities
`capabilities` are set as a list of strings, expressing both generic and driver specific capabilities.
The following generic capabilities are recognized today:
- `gpu`: Graphics accelerator
- `tpu`: AI accelerator
To avoid name clashes, driver specific capabilities MUST be prefixed with the driver name.
For example, reserving an nVidia CUDA-enabled accelerator might look like this:
```yml
deploy:
resources:
reservations:
devices:
- capabilities: ["nvidia-compute"]
```
##### driver
A different driver for the reserved device(s) can be requested using `driver` field. The value is specified as a string.
```yml
deploy:
resources:
reservations:
devices:
- capabilities: ["nvidia-compute"]
driver: nvidia
```
##### count
If `count` is set to `all` or not specified, Compose implementations MUST reserve all devices that satisfy the requested capabilities. Otherwise, Compose implementations MUST reserve at least the number of devices specified. The value is specified as an integer.
```yml
deploy:
resources:
reservations:
devices:
- capabilities: ["tpu"]
count: 2
```
`count` and `device_ids` fields are exclusive. Compose implementations MUST return an error if both are specified.
##### device_ids
If `device_ids` is set, Compose implementations MUST reserve devices with the specified IDs providing they satisfy the requested capabilities. The value is specified as a list of strings.
```yml
deploy:
resources:
reservations:
devices:
- capabilities: ["gpu"]
device_ids: ["GPU-f123d1c9-26bb-df9b-1c23-4a731f61d8c7"]
```
`count` and `device_ids` fields are exclusive. Compose implementations MUST return an error if both are specified.
##### options
Driver specific options can be set with `options` as key-value pairs.
```yml
deploy:
resources:
reservations:
devices:
- capabilities: ["gpu"]
driver: gpuvendor
options:
virtualization: false
```
### restart_policy
`restart_policy` configures if and how to restart containers when they exit. If `restart_policy` is not set, Compose implementations MUST consider `restart` field set by service configuration.
- `condition`: One of `none`, `on-failure` or `any` (default: `any`).
- `delay`: How long to wait between restart attempts, specified as a [duration](index.md#specifying-durations) (default: 0).
- `max_attempts`: How many times to attempt to restart a container before giving up (default: never give up). If the restart does not
succeed within the configured `window`, this attempt doesn't count toward the configured `max_attempts` value.
For example, if `max_attempts` is set to '2', and the restart fails on the first attempt, more than two restarts MUST be attempted.
- `window`: How long to wait before deciding if a restart has succeeded, specified as a [duration](index.md#specifying-durations) (default:
decide immediately).
```yml
deploy:
restart_policy:
condition: on-failure
delay: 5s
max_attempts: 3
window: 120s
```
### rollback_config
`rollback_config` configures how the service should be rollbacked in case of a failing update.
- `parallelism`: The number of containers to rollback at a time. If set to 0, all containers rollback simultaneously.
- `delay`: The time to wait between each container group's rollback (default 0s).
- `failure_action`: What to do if a rollback fails. One of `continue` or `pause` (default `pause`)
- `monitor`: Duration after each task update to monitor for failure `(ns|us|ms|s|m|h)` (default 0s).
- `max_failure_ratio`: Failure rate to tolerate during a rollback (default 0).
- `order`: Order of operations during rollbacks. One of `stop-first` (old task is stopped before starting new one),
or `start-first` (new task is started first, and the running tasks briefly overlap) (default `stop-first`).
### update_config
`update_config` configures how the service should be updated. Useful for configuring rolling updates.
- `parallelism`: The number of containers to update at a time.
- `delay`: The time to wait between updating a group of containers.
- `failure_action`: What to do if an update fails. One of `continue`, `rollback`, or `pause` (default: `pause`).
- `monitor`: Duration after each task update to monitor for failure `(ns|us|ms|s|m|h)` (default 0s).
- `max_failure_ratio`: Failure rate to tolerate during an update.
- `order`: Order of operations during updates. One of `stop-first` (old task is stopped before starting new one),
or `start-first` (new task is started first, and the running tasks briefly overlap) (default `stop-first`).
```yml
deploy:
update_config:
parallelism: 2
delay: 10s
order: stop-first
```

2605
compose/compose-file/index.md
View File

File diff suppressed because it is too large Load Diff

15
compose/environment-variables/envvars.md
View File

@ -43,7 +43,20 @@ the container's name on startup.
For example, if your project name is `myapp` and it includes two services `db` and `web`,
then Compose starts containers named `myapp-db-1` and `myapp-web-1` respectively.
It defaults to the `basename` of the project directory.
Compose can set the project name in different ways. The level of precedence (from highest to lowest) for each method is as follows:
1. The `-p` command line flag
2. `COMPOSE_PROJECT_NAME`
3. The top level `name:` variable from the config file (or the last `name:` from
a series of config files specified using `-f`)
4. The `basename` of the project directory containing the config file (or
containing the first config file specified using `-f`)
5. The `basename` of the current directory if no config file is specified
Project names must contain only lowercase letters, decimal digits, dashes, and
underscores, and must begin with a lowercase letter or decimal digit. If the
`basename` of the project directory or current directory violates this
constraint, you must use one of the other mechanisms.
See also the [command-line options overview](../reference/index.md#command-options-overview-and-help) and [using `-p` to specify a project name](../reference/index.md#use--p-to-specify-a-project-name).

20
compose/environment-variables/set-environment-variables.md
View File

@ -30,10 +30,10 @@ services:
When you run `docker compose up`, the `web` service defined in the Compose file substitues in the
image `webapp:v1.5` which was set in the `.env` file. You can verify this with the
[convert command](../../engine/reference/commandline/compose_config.md), which prints your resolved application config to the terminal:
[config command](../../engine/reference/commandline/compose_config.md), which prints your resolved application config to the terminal:
```console
$ docker compose convert
$ docker compose config
services:
web:
@ -43,7 +43,7 @@ services:
The `.env` file should be placed at the root of the project directory next to your `docker-compose.yml` file. You can use an alternative path with one of the following methods:
- The [`--file` option in the CLI](../reference/index.md#use--f-to-specify-name-and-path-of-one-or-more-compose-files)
- The [`--env-file` option in the CLI](#substitute-with---env-file)
- Using the [`env_file` attribute in the Compose file](../compose-file/index.md#env_file)
- Using the [`env_file` attribute in the Compose file](../compose-file/05-services.md#env_file)
For more information on formatting an environment file, see [Use an environment file](env-file.md).
@ -56,7 +56,7 @@ For more information on formatting an environment file, see [Use an environment
### Use the `environment` attribute
You can set environment variables in a service's containers with the
[`environment` attribute](../compose-file/index.md#environment) in your Compose file. It works in the same way as `docker run -e VARIABLE=VALUE ...`
[`environment` attribute](../compose-file/05-services.md#environment) in your Compose file. It works in the same way as `docker run -e VARIABLE=VALUE ...`
```yaml
web:
@ -75,12 +75,12 @@ web:
The value of the `DEBUG` variable in the container is taken from the value for the same variable in the shell in which Compose is run.
See [`environment` attribute](../compose-file/index.md#environment) for more information.
See [`environment` attribute](../compose-file/05-services.md#environment) for more information.
### Use the `env_file` attribute
You can pass multiple environment variables from an external file through to
a service's containers with the [`env_file` option](../compose-file/index.md#env_file). This works in the same way as `docker run --env-file=FILE ...`:
a service's containers with the [`env_file` option](../compose-file/05-services.md#env_file). This works in the same way as `docker run --env-file=FILE ...`:
```yaml
web:
@ -94,7 +94,7 @@ If multiple files are specified, they are evaluated in order and can override va
>
>With this option, environment variables declared in the file cannot then be referenced again separately in the Compose file or used to configure Compose.
See [`env_file` attribute](../compose-file/index.md#env_file) for more information.
See [`env_file` attribute](../compose-file/05-services.md#env_file) for more information.
### Substitute from the shell
@ -146,7 +146,7 @@ services:
If the `--env-file` is not used in the command line, the `.env` file is loaded by default:
```console
$ docker compose convert
$ docker compose config
services:
web:
image: 'webapp:v1.5'
@ -155,7 +155,7 @@ services:
Passing the `--env-file` argument overrides the default file path:
```console
$ docker compose --env-file ./config/.env.dev convert
$ docker compose --env-file ./config/.env.dev config
services:
web:
image: 'webapp:v1.6'
@ -164,7 +164,7 @@ services:
When an invalid file path is being passed as an `--env-file` argument, Compose returns an error:
```console
$ docker compose --env-file ./doesnotexist/.env.dev convert
$ docker compose --env-file ./doesnotexist/.env.dev config
ERROR: Couldn't find env file: /home/user/./doesnotexist/.env.dev
```

2
compose/extends.md
View File

@ -446,4 +446,4 @@ services:
## Reference information
[`extends`](compose-file/index.md#extends)
[`extends`](compose-file/05-services.md#extends)

16
compose/networking.md
View File

@ -54,7 +54,7 @@ the service is accessible outside the swarm as well.
Within the `web` container, your connection string to `db` would look like
`postgres://db:5432`, and from the host machine, the connection string would
look like `postgres://{DOCKER_IP}:5432`.
look like `postgres://{DOCKER_IP}:8001` for example `postgres://localhost:8001` if your container is running locally.
## Update containers on the network
@ -82,14 +82,14 @@ services:
image: postgres
```
See the [links reference](compose-file/index.md#links) for more information.
See the [links reference](compose-file/05-services.md#links) for more information.
## Multi-host networking
When deploying a Compose application on a Docker Engine with [Swarm mode enabled](../engine/swarm/index.md),
you can make use of the built-in `overlay` driver to enable multi-host communication.
Overlay networks are always created as `attachable`. You can optionally set the [`attachable`](compose-file/index.md#attachable) property to `false`.
Overlay networks are always created as `attachable`. You can optionally set the [`attachable`](compose-file/06-networks.md#attachable) property to `false`.
Consult the [Swarm mode section](../engine/swarm/index.md), to see how to set up
a Swarm cluster, and the [Getting started with multi-host networking](../network/network-tutorial-overlay.md)
@ -131,9 +131,9 @@ networks:
bar: "2"
```
Networks can be configured with static IP addresses by setting the [ipv4_address and/or ipv6_address](compose-file/index.md#ipv4_address-ipv6_address) for each attached network.
Networks can be configured with static IP addresses by setting the [ipv4_address and/or ipv6_address](compose-file/05-services.md#ipv4_address-ipv6_address) for each attached network.
Networks can also be given a [custom name](compose-file/index.md#name):
Networks can also be given a [custom name](compose-file/06-networks.md#name):
```yaml
services:
@ -165,7 +165,7 @@ networks:
## Use a pre-existing network
If you want your containers to join a pre-existing network, use the [`external` option](compose-file/index.md#external)
If you want your containers to join a pre-existing network, use the [`external` option](compose-file/06-networks.md#external)
```yaml
services:
# ...
@ -181,5 +181,5 @@ Instead of attempting to create a network called `[projectname]_default`, Compos
For full details of the network configuration options available, see the following references:
- [Top-level `networks` key](compose-file/index.md#networks-top-level-element)
- [Service-level `networks` key](compose-file/index.md#networks)
- [Top-level `networks` key](compose-file/06-networks.md)
- [Service-level `networks` key](compose-file/05-services.md#networks)

2
compose/production.md
View File

@ -23,7 +23,7 @@ production. These changes might include:
- Binding to different ports on the host
- Setting environment variables differently, such as reducing the verbosity of
logging, or to specify settings for external services such as an email server
- Specifying a restart policy like [`restart: always`](compose-file/index.md#restart){: target="_blank" rel="noopener" class="_" } to avoid downtime
- Specifying a restart policy like [`restart: always`](compose-file/05-services.md#restart){: target="_blank" rel="noopener" class="_" } to avoid downtime
- Adding extra services such as a log aggregator
For this reason, consider defining an additional Compose file, say

4
compose/profiles.md
View File

@ -18,7 +18,7 @@ development tasks.
## Assigning profiles to services
Services are associated with profiles through the
[`profiles` attribute](compose-file/index.md#profiles) which takes an
[`profiles` attribute](compose-file/05-services.md#profiles) which takes an
array of profile names:
```yaml
@ -183,4 +183,4 @@ $ COMPOSE_PROFILES=dev docker compose up phpmyadmin
## Reference information
[`profiles`](compose-file/index.md#profiles)
[`profiles`](compose-file/05-services.md#profiles)

19
compose/reference/index.md
View File

@ -185,9 +185,22 @@ Status: Downloaded newer image for postgres:latest
## Use `-p` to specify a project name
Each configuration has a project name. If you supply a `-p` flag, you can
specify a project name. If you don't specify the flag, Compose uses the current
directory name. See also the [COMPOSE_PROJECT_NAME environment variable](../environment-variables/envvars.md#compose_project_name).
Each configuration has a project name which Compose can set in different ways. The level of precedence (from highest to lowest) for each method is as follows:
1. The `-p` command line flag
2. The [COMPOSE_PROJECT_NAME environment variable][]
3. The top level `name:` variable from the config file (or the last `name:` from
a series of config files specified using `-f`)
4. The `basename` of the project directory containing the config file (or
containing the first config file specified using `-f`)
5. The `basename` of the current directory if no config file is specified
[COMPOSE_PROJECT_NAME environment variable]: ../environment-variables/envvars.md#compose_project_name
Project names must contain only lowercase letters, decimal digits, dashes, and
underscores, and must begin with a lowercase letter or decimal digit. If the
`basename` of the project directory or current directory violates this
constraint, you must use one of the other mechanisms.
## Use `--profile` to specify one or more active profiles

92
compose/release-notes.md
View File

@ -8,6 +8,98 @@ redirect_from:
---
{% include compose-eol.md %}
## 2.17.2
{% include release-date.html date="2023-03-26" %}
### Update
- Dependencies upgrade: bump compose-go to v1.13.2
### Bug fixes and enhancements
- Fixed invalid project name error for directories with uppercase characters or `.` in the name. Fixed [compose#10405](https://github.com/docker/compose/issues/10405){:
target="_blank" rel="noopener" class="_"}
## 2.17.1
{% include release-date.html date="2023-03-24" %}
### Update
- Dependencies upgrade: bump buildkit to v0.11.5
- Dependencies upgrade: bump compose-go to v1.13.1
- Dependencies upgrade: bump golang to 1.20.2
### Bug fixes and enhancements
- Fixed panic on `alpha watch` command. Pull Request [compose#10393](https://github.com/docker/compose/pull/10393){:
target="_blank" rel="noopener" class="_"}
- Prevented conflicts for services named `extensions`. Fixed [compose-go#247](https://github.com/compose-spec/compose-go/issues/247){:
target="_blank" rel="noopener" class="_"}
- Compose now validates project names more consistently. Fixed [compose-go#363](https://github.com/compose-spec/compose-go/issues/363){:
target="_blank" rel="noopener" class="_"}
## 2.17.0
{% include release-date.html date="2023-03-23" %}
### Update
- Dependencies upgrade: bump buildkit to v0.11.4
- Dependencies upgrade: bump buildx to v0.10.4
- Dependencies upgrade: bump containerd to 1.6.18
- Dependencies upgrade: bump compose-go to v1.13.0
### Bug fixes and enhancements
* Introduced `--wait-timeout` on `up` command. Fixed [compose#10269](https://github.com/docker/compose/issues/10269){:
target="_blank" rel="noopener" class="_"}
* Made `compose service --hash` output sort by service name. Pull Request [compose#10278](https://github.com/docker/compose/pull/10278){:
target="_blank" rel="noopener" class="_"}
* Compose now renders a compact TUI progress report to monitor layers download. Pull Request [compose#10281](https://github.com/docker/compose/pull/10281){:
target="_blank" rel="noopener" class="_"}
* Introduced `restart` for `depends_on`. Fixed [compose#10284](https://github.com/docker/compose/issues/10284){:
target="_blank" rel="noopener" class="_"}
* Added support of `NO_COLOR` env var. Fixed [compose#10340](https://github.com/docker/compose/issues/10340){:
target="_blank" rel="noopener" class="_"}
* Progress writer now uses `dockercli.Err` stream. Fixed [compose#10366](https://github.com/docker/compose/issues/10366){:
target="_blank" rel="noopener" class="_"}
* Introduced `dockerfile_inline`. Fixed [compose#8077](https://github.com/docker/compose/issues/8077){:
target="_blank" rel="noopener" class="_"}
* Added support for `additional_contexts` in the `build` service configuration. Fixed [compose#9461](https://github.com/docker/compose/issues/9461){:
target="_blank" rel="noopener" class="_"} [compose#9961](https://github.com/docker/compose/issues/9961){:
target="_blank" rel="noopener" class="_"}
* Added file delete/rename handling in `watch` mode. Pull Request [compose#10386](https://github.com/docker/compose/pull/10386){:
target="_blank" rel="noopener" class="_"}
* Introduced an `ignore` attribute in `watch` mode. Pull Request [compose#10385](https://github.com/docker/compose/pull/10385){:
target="_blank" rel="noopener" class="_"}
* Compose now uses progress writer to show copies status. Pull Request [compose#10387](https://github.com/docker/compose/pull/10387){:
target="_blank" rel="noopener" class="_"}
* Updated reference documentation for `-p`/`--project-name` flag. Fixed [docs#16915](https://github.com/docker/docs/pull/16915){:
target="_blank" rel="noopener" class="_"}, [compose-spec#311](https://github.com/compose-spec/compose-spec/issues/311){:
target="_blank" rel="noopener" class="_"}
* Introduced a `replace` label to track the relationship between old and new containers of a service. Fixed [compose#9600](https://github.com/docker/compose/issues/9600){:
target="_blank" rel="noopener" class="_"}
* Fixed a bug that meant dependent services were not restarted after a service was restarted. Fixed [compose#10263](https://github.com/docker/compose/issues/10263){:
target="_blank" rel="noopener" class="_"}
* Compose now ignores services without a build section in `watch` mode. Fixed [compose#10270](https://github.com/docker/compose/issues/10270){:
target="_blank" rel="noopener" class="_"}
* Compose now applies config options for pseudo-subcommands. Fixed [compose#10286](https://github.com/docker/compose/issues/10286){:
target="_blank" rel="noopener" class="_"}
* Compose manages only containers with config_hash labels (i.e, created by compose). Fixed [compose#10317](https://github.com/docker/compose/issues/10317){:
target="_blank" rel="noopener" class="_"}
* Compose triggers an error if the project name is empty after normalization. Fixed [compose#10313](https://github.com/docker/compose/issues/10313){:
target="_blank" rel="noopener" class="_"}
* Compose restarts only needed services by checking `depends_on` relations. Fixed [compose#10337](https://github.com/docker/compose/issues/10337){:
target="_blank" rel="noopener" class="_"}
* Fixed a display issue on small terminals. Fixed [compose#10322](https://github.com/docker/compose/issues/10322){:
target="_blank" rel="noopener" class="_"}
* Fixed an issue with building the built images IDs collection. Pull Request [compose#10372](https://github.com/docker/compose/issues/10372){:
target="_blank" rel="noopener" class="_"}
* Use configured name separator to define oneoff container name. Fixed [compose#10354](https://github.com/docker/compose/issues/10354){:
target="_blank" rel="noopener" class="_"}
* Fixed concurrent map read/write issue when recreating containers. Fixed [compose#10319](https://github.com/docker/compose/issues/10319){:
target="_blank" rel="noopener" class="_"}
* Compose now supports Dry Run mode for `stop` and `rm` commands. Pull Request [compose#10257](https://github.com/docker/compose/issues/10257){:
target="_blank" rel="noopener" class="_"}
* Compose now supports Dry Run mode for `pull` command. Pull Request [compose#10341](https://github.com/docker/compose/issues/10341){:
target="_blank" rel="noopener" class="_"}
* Compose now supports Dry Run mode for `push` command. Pull Request [compose#10355](https://github.com/docker/compose/issues/10355){:
target="_blank" rel="noopener" class="_"}
* Compose now supports Dry Run mode for `exec` command. Pull Request [compose#10252](https://github.com/docker/compose/issues/10252){:
target="_blank" rel="noopener" class="_"}
* Compose now supports Dry Run mode for `restart` command. Pull Request [compose#10339](https://github.com/docker/compose/issues/10339){:
target="_blank" rel="noopener" class="_"}
## 2.16.0
{% include release-date.html date="2023-02-08" %}
### Update

6
compose/startup-order.md
View File

@ -7,7 +7,7 @@ notoc: true
{% include compose-eol.md %}
You can control the order of service startup and shutdown with the
[depends_on](compose-file/index.md#depends_on) option. Compose always starts and stops
[depends_on](compose-file/05-services.md#depends_on) option. Compose always starts and stops
containers in dependency order, where dependencies are determined by
`depends_on`, `links`, `volumes_from`, and `network_mode: "service:..."`.
@ -25,6 +25,6 @@ The solution for detecting the ready state of a service is to use the `conditio
## Reference information
- [`depends_on`](compose-file/index.md#depends_on)
- [`healthcheck`](compose-file/index.md#healthcheck)
- [`depends_on`](compose-file/05-services.md#depends_on)
- [`healthcheck`](compose-file/05-services.md#healthcheck)

8
config/containers/logging/configure.md
View File

@ -135,8 +135,7 @@ Docker provides two modes for delivering messages from the container to the log
driver:
* (default) direct, blocking delivery from container to driver
* non-blocking delivery that stores log messages in an intermediate per-container
ring buffer for consumption by driver
* non-blocking delivery that stores log messages in an intermediate per-container buffer for consumption by driver
The `non-blocking` message delivery mode prevents applications from blocking due
to logging back pressure. Applications are likely to fail in unexpected ways when
@ -144,15 +143,14 @@ STDERR or STDOUT streams block.
> **Warning**
>
> When the buffer is full and a new message is enqueued, the oldest message in
> memory is dropped. Dropping messages is often preferred to blocking the
> When the buffer is full, new messages will not be enqueued. Dropping messages is often preferred to blocking the
> log-writing process of an application.
{: .warning}
The `mode` log option controls whether to use the `blocking` (default) or
`non-blocking` message delivery.
The `max-buffer-size` log option controls the size of the ring buffer used for
The `max-buffer-size` log option controls the size of the buffer used for
intermediate message storage when `mode` is set to `non-blocking`. `max-buffer-size`
defaults to 1 megabyte.

7
config/daemon/index.md
View File

@ -69,8 +69,11 @@ Here's what the configuration file might look like:
}
```
With this configuration the Docker daemon runs in debug mode, uses TLS, and
listens for traffic routed to `192.168.59.3` on port `2376`. You can learn what
In addition to Docker Desktop default values, this configuration enables garbage
collection at a 20GB threshold, and enables buildkit.
Using this configuration file, run the Docker daemon in debug mode, using TLS, and
listen for traffic routed to `192.168.59.3` on port `2376`. You can learn what
configuration options are available in the
[dockerd reference docs](../../engine/reference/commandline/dockerd.md#daemon-configuration-file)

7
config/daemon/prometheus.md
View File

@ -36,18 +36,17 @@ exist, create it.
- **Linux**: `/etc/docker/daemon.json`
- **Windows Server**: `C:\ProgramData\docker\config\daemon.json`
- **Docker Desktop for Mac / Docker Desktop for Windows**: Click the Docker icon in the toolbar,
select **Settings**, then select **Daemon**. Click **Advanced**.
select **Settings**, then select **Docker Engine**.
If the file is currently empty, paste the following:
```json
{
"metrics-addr" : "127.0.0.1:9323",
"experimental" : true
"metrics-addr" : "127.0.0.1:9323"
}
```
If the file is not empty, add those two keys, making sure that the resulting
If the file is not empty, add the new key, making sure that the resulting
file is valid JSON. Be careful that every line ends with a comma (`,`) except
for the last line.

10
contribute/contribute-guide.md
View File

@ -27,10 +27,10 @@ There are two ways to contribute a pull request to the docs repository:
Here’s a list of some of the important files:
- `/_data/toc.yaml` defines the left-hand navigation for the docs
- `/js/docs.js` defines most of the docs-specific JS such as the table of contents (ToC) generation and menu syncing
- `/css/style.scss` defines the docs-specific style rules
- `/_layouts/docs.html` is the HTML template file, which defines the header and footer, and includes all the JS/CSS that serves the docs content
- `/_data/toc.yaml` defines the left-hand navigation for the docs.
- `/js/docs.js` defines most of the docs-specific JS such as the table of contents (ToC) generation and menu syncing.
- `/css/style.scss` defines the docs-specific style rules.
- `/_layouts/docs.html` is the HTML template file, which defines the header and footer, and includes all the JS/CSS that serves the docs content.
### Files not edited here
@ -71,7 +71,7 @@ git clone {{ site.repo }}.git
cd docs
```
Then, build and run the documentation using [Docker Compose](../compose/index.md)
Then, build and run the documentation using [Docker Compose](../compose/index.md):
```bash
docker compose up -d --build

2
contribute/overview.md
View File

@ -76,7 +76,7 @@ as possible for you to work in this repository. The following sections guide you
We also provide:
- A section of useful components you can add to your documentation. For components and controls, we use [Bootstrap](https://getbootstrap.com)
- A section of useful components you can add to your documentation. For components and controls, we use [Bootstrap](https://getbootstrap.com).
- Information on Docker's [tone and voice](style/voice-tone.md).
- A [writing checklist](checklist.md) to help you when you're contributing to Docker's documentation.
- A command-line tool called vale to check the style and [help you find errors in your writing](contribute-guide.md#test-the-docs-locally).

2
contribute/style/formatting.md
View File

@ -25,7 +25,7 @@ Page titles should be action orientated. For example:
### Best practice:
- Make sure the title of your page and the TOC entry matches
- Make sure the title of your page and the TOC entry matches.
- If you want to use a ‘:’ in a page title in the table of contents (_toc.yaml), you must wrap the entire title in “” to avoid breaking the build.
## Images

2
desktop/backup-and-restore.md
View File

@ -27,7 +27,7 @@ computer, for example.
2. Use [`docker push`](../engine/reference/commandline/push.md) to push any
images you have built locally and want to keep to the [Docker Hub registry](../docker-hub/index.md).
Make sure to configure the [repository's visibility as "private"](../docker-hub/repos/configure/index.md)
Make sure to configure the [repository's visibility as "private"](../docker-hub/repos/index.md)
for images that should not be publicly accessible.
Alternatively, use [`docker image save -o images.tar image1 [image2 ...]`](../engine/reference/commandline/save.md)

32
desktop/get-started.md
View File

@ -29,37 +29,29 @@ redirect_from:
## Quick Start Guide
Once Docker Desktop is installed, the Quick Start Guide launches. It includes a simple exercise to build an example Docker image, run it as a container, push and save the image to Docker Hub.
The Quick Start Guide includes a simple exercise to build an example Docker image, run it as a container, push and save the image to Docker Hub.
![Docker Quick Start tutorial](images/docker-tutorial.png)
![Docker Quick Start tutorial](images/docker-tutorial.png)
To run the Quick Start Guide on demand, select the Docker menu ![whale menu](images/whale-x.svg){: .inline} and then choose **Quick Start Guide**.
To run the Quick Start Guide, select the Docker menu ![whale menu](images/whale-x.svg){: .inline} and then choose **Quick Start Guide**.
For a more detailed guide, see [Get started](../get-started/index.md).
> **Note**
>
> To access the Quick Start Guide, you must turn off **Access experimental features**.
> Learn how to turn off **Access experimental features** on [Mac](../settings/mac/#experimental-features), [Windows](../settings/windows/#experimental-features), or [Linux](../settings/linux/#experimental-features).
For a more detailed guide, see [Get started](../get-started/index.md), or the [Docker Desktop hands-on guides](../get-started/hands-on-overview.md).
## Sign in to Docker Desktop
We recommend that you authenticate using the **Sign in/Create ID** option in the top-right corner of Docker Desktop.
We recommend that you authenticate using the **Sign in** option in the top-right corner of the Docker Dashboard.
Once logged in, you can access your Docker Hub repositories directly from Docker Desktop.
Authenticated users 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).
In large enterprises where admin access is restricted, administrators can create a registry.json file and deploy it to the developers’ machines using a device management software as part of the Docker Desktop installation process. Enforcing developers to authenticate through Docker Desktop also allows administrators to set up guardrails using features such as [Image Access Management](../docker-hub/image-access-management.md) which allows team members to only have access to Trusted Content on Docker Hub, and pull only from the specified categories of images. For more information, see [Configure registry.json to enforce sign-in](../docker-hub/configure-sign-in.md).
### Two-factor authentication
Docker Desktop lets you to sign in to Docker Hub using two-factor authentication. Two-factor authentication provides an extra layer of security when accessing your Docker Hub account.
You must turn on two-factor authentication in Docker Hub before signing into your Docker Hub account through Docker Desktop. For instructions, see [Enable two-factor authentication for Docker Hub](/docker-hub/2fa/).
After two-factor authentication is turned on:
1. Go to the Docker Desktop menu and then select **Sign in / Create Docker ID**.
2. Enter your Docker ID and password and select **Sign in**.
3. After you have successfully signed in, Docker Desktop prompts you to enter the authentication code. Enter the six-digit code from your phone and then select **Verify**.
In large enterprises where admin access is restricted, administrators can [Configure registry.json to enforce sign-in](../docker-hub/configure-sign-in.md). Enforcing developers to authenticate through Docker Desktop also allows administrators to improve their organization’s security posture for containerized development by taking advantage of [Hardened Desktop](hardened-desktop/index.md).
### Credentials management for Linux users

4
desktop/install/archlinux.md
View File

@ -6,9 +6,9 @@ redirect_from:
- /desktop/linux/install/archlinux/
---
This topic discusses installation of Docker Desktop from an [Arch package](https://desktop-stage.docker.com/linux/main/amd64/docker-desktop-4.17.0-x86_64.pkg.tar.zst?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-linux-amd64) that Docker provides in addition to the supported platforms. Docker has not tested or verified the installation.
This topic discusses installation of Docker Desktop from an [Arch package](https://desktop-stage.docker.com/linux/main/amd64/docker-desktop-4.18.0-x86_64.pkg.tar.zst?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-linux-amd64) that Docker provides in addition to the supported platforms. Docker has not tested or verified the installation.
[Arch package (experimental)](https://desktop.docker.com/linux/main/amd64/docker-desktop-4.17.0-x86_64.pkg.tar.zst?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-linux-amd64){: .button .primary-btn }
[Arch package (experimental)](https://desktop.docker.com/linux/main/amd64/docker-desktop-4.18.0-x86_64.pkg.tar.zst?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-linux-amd64){: .button .primary-btn }
_For checksums, see [Release notes](../release-notes.md)_

4
desktop/install/debian.md
View File

@ -9,7 +9,7 @@ redirect_from:
This page contains information on how to install, launch, and upgrade Docker Desktop on a Debian distribution.
[DEB package](https://desktop.docker.com/linux/main/amd64/docker-desktop-4.17.0-amd64.deb?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-linux-amd64){: .button .primary-btn }
[DEB package](https://desktop.docker.com/linux/main/amd64/docker-desktop-4.18.0-amd64.deb?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-linux-amd64){: .button .primary-btn }
_For checksums, see [Release notes](../release-notes.md)_
@ -52,7 +52,7 @@ Recommended approach to install Docker Desktop on Debian:
1. Set up [Docker's package repository](../../engine/install/debian.md#set-up-the-repository).
2. Download latest [DEB package](https://desktop.docker.com/linux/main/amd64/docker-desktop-4.17.0-amd64.deb?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-linux-amd64).
2. Download latest [DEB package](https://desktop.docker.com/linux/main/amd64/docker-desktop-4.18.0-amd64.deb?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-linux-amd64).
3. Install the package with apt as follows:

4
desktop/install/fedora.md
View File

@ -9,7 +9,7 @@ redirect_from:
This page contains information on how to install, launch and upgrade Docker Desktop on a Fedora distribution.
[RPM package](https://desktop.docker.com/linux/main/amd64/docker-desktop-4.17.0-x86_64.rpm?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-linux-amd64){: .button .primary-btn }
[RPM package](https://desktop.docker.com/linux/main/amd64/docker-desktop-4.18.0-x86_64.rpm?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-linux-amd64){: .button .primary-btn }
## Prerequisites
@ -32,7 +32,7 @@ To install Docker Desktop on Fedora:
1. Set up [Docker's package repository](../../engine/install/fedora.md#set-up-the-repository).
2. Download latest [RPM package](https://desktop.docker.com/linux/main/amd64/docker-desktop-4.17.0-x86_64.rpm?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-linux-amd64).
2. Download latest [RPM package](https://desktop.docker.com/linux/main/amd64/docker-desktop-4.18.0-x86_64.rpm?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-linux-amd64).
3. Install the package with dnf as follows:

37
desktop/install/linux-install.md
View File

@ -17,25 +17,6 @@ This page contains information about general system requirements, supported plat
>For more information see [What is the difference between Docker Desktop for Linux and Docker Engine](../faqs/linuxfaqs.md#what-is-the-difference-between-docker-desktop-for-linux-and-docker-engine).
{: .important}
## System requirements
To install Docker Desktop successfully, your Linux host must meet the following general requirements:
- 64-bit kernel and CPU support for virtualization.
- KVM virtualization support. Follow the [KVM virtualization support instructions](#kvm-virtualization-support) to check if the KVM kernel modules are enabled and how to provide access to the kvm device.
- **QEMU must be version 5.2 or newer**. 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/){:target="_blank" rel="noopener" class="_"}.
- At least 4 GB of RAM.
- Enable configuring ID mapping in user namespaces, see [File sharing](../faqs/linuxfaqs.md#how-do-i-enable-file-sharing).
Docker Desktop for Linux runs a Virtual Machine (VM). For more information on why, see [Why Docker Desktop for Linux runs a VM](../faqs/linuxfaqs.md#why-does-docker-desktop-for-linux-run-a-vm).
> **Note:**
>
> Docker does not provide support for running Docker Desktop in nested virtualization scenarios. We recommend that you run Docker Desktop for Linux natively on supported distributions.
## Supported platforms
Docker provides `.deb` and `.rpm` packages from the following Linux distributions
@ -56,6 +37,24 @@ An experimental package is available for [Arch](archlinux.md)-based distribution
Docker supports Docker Desktop on the current LTS release of the aforementioned distributions and the most recent version. As new versions are made available, Docker stops supporting the oldest version and supports the newest version.
## System requirements
To install Docker Desktop successfully, your Linux host must meet the following general requirements:
- 64-bit kernel and CPU support for virtualization.
- KVM virtualization support. Follow the [KVM virtualization support instructions](#kvm-virtualization-support) to check if the KVM kernel modules are enabled and how to provide access to the kvm device.
- **QEMU must be version 5.2 or newer**. 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/){:target="_blank" rel="noopener" class="_"}.
- At least 4 GB of RAM.
- Enable configuring ID mapping in user namespaces, see [File sharing](../faqs/linuxfaqs.md#how-do-i-enable-file-sharing).
Docker Desktop for Linux runs a Virtual Machine (VM). For more information on why, see [Why Docker Desktop for Linux runs a VM](../faqs/linuxfaqs.md#why-does-docker-desktop-for-linux-run-a-vm).
> **Note:**
>
> Docker does not provide support for running Docker Desktop in nested virtualization scenarios. We recommend that you run Docker Desktop for Linux natively on supported distributions.
### KVM virtualization support

13
desktop/install/mac-install.md
View File

@ -78,11 +78,15 @@ Your Mac must meet the following requirements to install Docker Desktop successf
{% include desktop-license-update.md %}
4. Select **Accept** to continue. Docker Desktop starts after you accept the terms.
4. Select **Accept** to continue.
Note that Docker Desktop will not run if you do not agree to the terms. You can choose to accept the terms at a later date by opening Docker Desktop.
For more information, see [Docker Desktop Subscription Service Agreement](https://www.docker.com/legal/docker-subscription-service-agreement){: target="_blank" rel="noopener" class="_" }. We recommend that you also read the [FAQs](https://www.docker.com/pricing/faq){: target="_blank" rel="noopener" class="_"}.
5. From the installation window, select either:
- **Use recommended settings (Requires password)**. This let's 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](../settings/mac.md#advanced), for more information and how to set the location of the Docker CLI tools.
6. Select **Finish**. If you have applied any of the above configurations that require a password in step 5, you are asked to enter your password to confirm.
### Install from the command line
@ -105,13 +109,6 @@ The `install` command accepts the following flags:
- For example:
`--allowed-org=<org name> --admin-settings='{"configurationFileVersion": 2, "enhancedContainerIsolation": {"value": true, "locked": false}}'`
### Runtime permission requirements
For some functions, Docker Desktop may require elevated privileges. The user is informed and prompted for authorization whenever such
configuration must be performed. [Docker Desktop permission requirements](../mac/permission-requirements.md) provides details on each configuration
and use case.
## Where to go next
- [Docker Desktop for Apple silicon](../install/mac-install.md) for detailed information about Docker Desktop for Apple silicon.

4
desktop/install/ubuntu.md
View File

@ -9,7 +9,7 @@ redirect_from:
This page contains information on how to install, launch and upgrade Docker Desktop on an Ubuntu distribution.
[DEB package](https://desktop.docker.com/linux/main/amd64/docker-desktop-4.17.0-amd64.deb?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-linux-amd64){: .button .primary-btn }
[DEB package](https://desktop.docker.com/linux/main/amd64/docker-desktop-4.18.0-amd64.deb?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-linux-amd64){: .button .primary-btn }
_For checksums, see [Release notes](../release-notes.md)_
@ -48,7 +48,7 @@ Recommended approach to install Docker Desktop on Ubuntu:
1. Set up [Docker's package repository](../../engine/install/ubuntu.md#set-up-the-repository).
2. Download latest [DEB package](https://desktop.docker.com/linux/main/amd64/docker-desktop-4.17.0-amd64.deb?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-linux-amd64).
2. Download latest [DEB package](https://desktop.docker.com/linux/main/amd64/docker-desktop-4.18.0-amd64.deb?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-linux-amd64).
3. Install the package with apt as follows:

136
desktop/mac/permission-requirements.md
View File

@ -13,39 +13,108 @@ It also provides clarity on running containers as `root` as opposed to having `r
## Permission requirements
Docker Desktop for Mac is run as an unprivileged user. However, certain functionalities may be required for Docker Desktop to perform a limited set of privileged configurations such as:
- [Installing symlinks](#installing-symlinks) in `/usr/local/bin`. This ensures the `docker` CLI is on the user’s PATH without having to reconfigure shells, log out then log back in, for example.
- [Binding privileged ports](#binding-privileged-ports) that are less than 1024. The so-called "privileged ports" have not generally been used as a security boundary, however OSes still prevent unprivileged processes from binding them which breaks commands like `docker run -p 127.0.0.1:80:80 docker/getting-started`.
- [Ensuring `localhost` and `kubernetes.docker.internal` are defined](#ensuring-localhost-and-kubernetesdockerinternal-are-defined) in `/etc/hosts`. Some old macOS installs did not have `localhost` in `/etc/hosts`, which caused Docker to fail. Defining the DNS name `kubernetes.docker.internal` allows us to share Kubernetes contexts with containers.
Docker Desktop for Mac is run as an unprivileged user. However, certain functionalities are required for Docker Desktop to perform a limited set of privileged configurations such as:
- [Installing symlinks](#installing-symlinks) in`/usr/local/bin`.
- [Binding privileged ports](#binding-privileged-ports) that are less than 1024. The so-called "privileged ports" are not generally used as a security boundary, however OSes still prevent unprivileged processes from binding them which breaks commands like `docker run -p 127.0.0.1:80:80 docker/getting-started`.
- [Ensuring `localhost` and `kubernetes.docker.internal` are defined](#ensuring-localhost-and-kubernetesdockerinternal-are-defined) in `/etc/hosts`. Some old macOS installs do not have `localhost` in `/etc/hosts`, which causes Docker to fail. Defining the DNS name `kubernetes.docker.internal` allows Docker to share Kubernetes contexts with containers.
- Securely caching the Registry Access Management policy which is read-only for the developer.
Versions prior to 4.15 of Docker Desktop for Mac require `root` access to be granted on the first run. The first time that Docker Desktop is launched the user receives an admin prompt to grant permissions for a privileged helper service `com.docker.vmnetd` to be installed. For subsequent runs, no `root` privileges are required. Following the principle of least privilege, this approach allows `root` access to be used only for the operations for which it is absolutely necessary, while still being able to use Docker Desktop as an unprivileged user.
Depending on which version of Docker Desktop for Mac is used, privileged access is granted either during installation, first run, or only when it is needed.
<ul class="nav nav-tabs">
<li class="active"><a data-toggle="tab" data-target="#tab1">Version 4.18 and later</a></li>
<li><a data-toggle="tab" data-target="#tab2">Version 4.15 - 4.17 </a></li>
<li><a data-toggle="tab" data-target="#tab3">Versions prior to 4.15</a></li>
</ul>
<div class="tab-content">
<div id="tab1" class="tab-pane fade in active" markdown="1">
From version 4.18 and above, Docker Desktop for Mac provides greater control over functionality that's enabled during installation.
The first time Docker Desktop for Mac is launched, you are presented with an installation window where you can choose to either use the default settings, which work for most developers and require privileged access to be granted, or use advanced settings.
If you work in an environment with elevated security requirements, for instance where local administrative access is prohibited, then you can use the advanced settings to remove the need for granting privileged access. You can configure:
- The location of the Docker CLI tools either in the system or user directory
- The default Docker socket
- Privileged port mapping
Depending on which advanced settings you configure, you must enter your password to confirm.
You can change these configurations at a later date from the **Advanced** page in **Settings**.
<hr>
</div>
<div id="tab2" class="tab-pane fade" markdown="1">
Versions 4.15 to 4.17 of Docker Desktop for Mac doesn't require the privileged process to run permanently. Whenever elevated privileges are needed for a configuration, Docker Desktop prompts you with information on the task it needs to perform. Most configurations are applied once, subsequent runs don't prompt for privileged access anymore.
The only time Docker Desktop may start the privileged process is for binding privileged ports that are not allowed by default on the host OS.
<hr>
</div>
<div id="tab3" class="tab-pane fade" markdown="1">
Versions prior to 4.15 of Docker Desktop for Mac require `root` access to be granted on the first run. The first time that Docker Desktop is launched you receive an admin prompt to grant permission for the installation of the `com.docker.vmnetd` privileged helper service. For subsequent runs, `root` privileges aren't required. Following the principle of least privilege, this approach allows `root` access to be used only for the operations for which it is absolutely necessary, while still being able to use Docker Desktop as an unprivileged user.
All privileged operations are run using the privileged helper process `com.docker.vmnetd`.
For security reasons, version 4.15 of Docker Desktop for Mac doesn't require the user to run a permanent privileged process. Whenever elevated privileges are needed for a configuration, Docker Desktop prompts the user with information on the task it needs to perform. Most configurations are applied once, subsequent runs don't prompt for privileged access anymore.
The only time Docker Desktop may start the privileged process is for binding privileged ports that are not allowed by default on the host OS.
<hr>
</div>
</div>
### Installing symlinks
The docker binaries are installed by default in `/Applications/Docker.app/Contents/Resources/bin`. Docker Desktop ensures the `docker` CLI is on the user’s PATH without having to reconfigure shells, log out then log back in for example. As on most systems `/usr/local/bin` is in the user's PATH by default, and so Docker Desktop creates symlinks for all docker binaries in it.
The Docker binaries are installed by default in `/Applications/Docker.app/Contents/Resources/bin`. Docker Desktop ensures the Docker CLI is on your PATH without having to reconfigure shells, log out then log back in for example. As on most systems `/usr/local/bin` is on the PATH by default, and so Docker Desktop creates symlinks for all Docker binaries in it.
Installing symlinks in `/usr/local/bin` is a privileged configuration Docker Desktop performs on the first startup. Docker Desktop checks if symlinks exists and takes the following actions:
<ul class="nav nav-tabs">
<li class="active"><a data-toggle="tab" data-target="#tab4">Version 4.18 and later</a></li>
<li><a data-toggle="tab" data-target="#tab5">Version 4.17 and earlier </a></li>
</ul>
<div class="tab-content">
<div id="tab4" class="tab-pane fade in active" markdown="1">
With version 4.18 or 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 the you must [manually add `$HOME/.docker/bin`](../settings/mac.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 to work without additional changes.
As the `/var/run` is mounted as a tmpfs, its content is deleted on restart, symlink to the Docker socket included. To ensure the Docker socket exists after restart, Docker Desktop sets up a `launchd` startup task that creates the symlink by running `ln -s -f /Users/<user>/.docker/run/docker.sock /var/run/docker.sock`. This ensures the user is not prompted on each startup to create the symlink. If the user does not enable this option at installation, the symlink and the startup task is not created and the user may have to explicitly set the `DOCKER_HOST` environment variable to `/Users/<user>/.docker/run/docker.sock` in the clients it is using. The Docker CLI relies on the current context to retrieve the socket path, the current context is set to `desktop-linux` on Docker Desktop startup.
<hr>
</div>
<div id="tab5" class="tab-pane fade" markdown="1">
For versions prior to 4.18, installing symlinks in `/usr/local/bin` is a privileged configuration Docker Desktop performs on the first startup. Docker Desktop checks if symlinks exists and takes the following actions:
- Creates the symlinks without the admin prompt if `/usr/local/bin` is writable by unprivileged users.
- Triggers an admin prompt for the user to authorize the creation of symlinks in `/usr/local/bin`. If the user authorizes this, symlinks to docker binaries are created in `/usr/local/bin`.
If the user rejects the prompt, is not willing to run configurations requiring elevated privileges, or does not have admin rights on their machine, Docker Desktop creates the symlinks in `~/.docker/bin` and edits the user's shell profile to ensure this location is in the user's PATH. This requires all open shells to be reloaded.
The rejection is recorded for future runs to avoid prompting the user again.
For any failure to ensure binaries are on the user's PATH, the user may need to manually add to their PATH the `/Applications/Docker.app/Contents/Resources/bin` or use the full path to docker binaries.
- Triggers an admin prompt for the user to authorize the creation of symlinks in `/usr/local/bin`. If you authorizes this, symlinks to Docker binaries are created in `/usr/local/bin`. If you reject the prompt, are not willing to run configurations requiring elevated privileges, or don't have admin rights on your machine, Docker Desktop creates the symlinks in `~/.docker/bin` and edits your shell profile to ensure this location is in your PATH. This requires all open shells to be reloaded.
The rejection is recorded for future runs to avoid prompting you again.
For any failure to ensure binaries are on your PATH, you may need to manually add to their PATH the `/Applications/Docker.app/Contents/Resources/bin` or use the full path to Docker binaries.
A particular case is the installation of the `/var/run/docker.sock` symlink. Creating this symlink ensures various docker clients relying on the default docker socket path to work without additional changes. As the `/var/run` is mounted as a tmpfs, its content is deleted on restart, symlink to docker socket included.
To ensure the docker socket exists after restart, Docker Desktop sets up a `launchd` startup task that creates the symlink by running `ln -s -f /Users/<user>/.docker/run/docker.sock /var/run/docker.sock`. This ensures the user is not prompted on each startup to create the symlink. If the user rejects the prompt, the symlink and the startup task is not created and the user may have to explicitly set the `DOCKER_HOST` to `/Users/<user>/.docker/run/docker.sock` in the clients it is using. The docker CLI relies on the current context to retrieve the socket path, the current context is set to `desktop-linux` on Docker Desktop startup.
A particular case is the installation of the `/var/run/docker.sock` symlink. Creating this symlink ensures various Docker clients relying on the default Docker socket path to work without additional changes. As the `/var/run` is mounted as a tmpfs, its content is deleted on restart, symlink to Docker socket included.
To ensure the Docker socket exists after restart, Docker Desktop sets up a `launchd` startup task that creates the symlink by running `ln -s -f /Users/<user>/.docker/run/docker.sock /var/run/docker.sock`. This ensures that you are not prompted on each startup to create the symlink. If you reject the prompt, the symlink and the startup task is not created and you may have to explicitly set the `DOCKER_HOST` to `/Users/<user>/.docker/run/docker.sock` in the clients it is using. The Docker CLI relies on the current context to retrieve the socket path, the current context is set to `desktop-linux` on Docker Desktop startup.
<hr>
</div>
</div>
### Binding privileged ports
When running a container that requires binding privileged ports, Docker Desktop first attempts to bind it directly as an unprivileged process. If the OS prevents this and it fails, Docker Desktop checks if the `com.docker.vmnetd` privileged helper process is running to bind the privileged port through it.
<ul class="nav nav-tabs">
<li class="active"><a data-toggle="tab" data-target="#tab6">Version 4.18 and later</a></li>
<li><a data-toggle="tab" data-target="#tab7">Version 4.17 and earlier </a></li>
</ul>
<div class="tab-content">
<div id="tab6" class="tab-pane fade in active" markdown="1">
If the privileged helper process is not running, Docker Desktop prompts the user for authorization to run it under [launchd](https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html).
With version 4.18 and later you can choose to enable privileged port mapping during installation, or from the **Advanced** page in **Settings** post-installation. Docker Desktop requires authorization to confirm this choice.
<hr>
</div>
<div id="tab7" class="tab-pane fade" markdown="1">
For versions below 4.18 , if you run a container that requires binding privileged ports, Docker Desktop first attempts to bind it directly as an unprivileged process. If the OS prevents this and it fails, Docker Desktop checks if the `com.docker.vmnetd` privileged helper process is running to bind the privileged port through it.
If the privileged helper process is not running, Docker Desktop prompts you for authorization to run it under [launchd](https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html).
This configures the privileged helper to run as in the versions of Docker Desktop prior to 4.15. However, the functionality provided by this privileged helper now only supports port binding and caching the Registry Access Management policy.
If the user declines the launch of the privileged helper process, binding the privileged port cannot be done and the docker CLI returns an error:
If you decline the launch of the privileged helper process, binding the privileged port cannot be done and the Docker CLI returns an error:
```console
$ docker run -p 127.0.0.1:80:80 docker/getting-started
@ -58,20 +127,41 @@ ERRO[0003] error waiting for container: context canceled
> **Note**
>
> The command may fail with the same error if the user takes too long to authorize the prompt to start the helper process, as it may timeout.
> The command may fail with the same error if you take too long to authorize the prompt to start the helper process, as it may timeout.
<hr>
</div>
</div>
### Ensuring `localhost` and `kubernetes.docker.internal` are defined
On first run, Docker Desktop checks if `localhost` is resolved to `127.0.0.1`. In case the resolution fails, it prompts the user to allow adding the mapping to `/etc/hosts`. Similarly, when the Kubernetes cluster is installed, it checks that `kubernetes.docker.internal` is resolved to `127.0.0.1` and prompts the user to do so.
<ul class="nav nav-tabs">
<li class="active"><a data-toggle="tab" data-target="#tab8">Version 4.18 and later</a></li>
<li><a data-toggle="tab" data-target="#tab9">Version 4.17 and earlier </a></li>
</ul>
<div class="tab-content">
<div id="tab8" class="tab-pane fade in active" markdown="1">
With version 4.18 it is your responsibility to ensure that localhost is resolved to `127.0.0.1` and if Kubernetes is used, that `kubernetes.docker.internal` is resolved to `127.0.0.1`.
<hr>
</div>
<div id="tab9" class="tab-pane fade" markdown="1">
On first run, Docker Desktop checks if `localhost` is resolved to `127.0.0.1`. In case the resolution fails, it prompts you to allow adding the mapping to `/etc/hosts`. Similarly, when the Kubernetes cluster is installed, it checks that `kubernetes.docker.internal` is resolved to `127.0.0.1` and prompts you to do so.
<hr>
</div>
</div>
## Installing from the commandline
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](../install/mac-install.md#install-from-the-command-line). In this case, the user is 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](../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 for the user
- Sets up symlinks
- Ensures that `localhost` is resolved to `127.0.0.1`
The limitation of this approach is that Docker Desktop can only be run by one user account per machine, namely the one specified in the `-–user` flag.
The limitation of this approach is that Docker Desktop can only be run by one user-account per machine, namely the one specified in the `-–user` flag.
## Privileged Helper

16
desktop/networking.md
View File

@ -31,8 +31,8 @@ When you run a container with the `-p` argument, for example:
$ docker run -p 80:80 -d nginx
```
Docker Desktop makes whatever is running on port 80 in the container (in
this case, `nginx`) available on port 80 of `localhost`. In this example, the
Docker Desktop makes whatever is running on port 80 in the container, in
this case, `nginx`, available on port 80 of `localhost`. In this example, the
host and container ports are the same. If, for example, you already have something running on port 80 of
your host machine, you can connect the container to a different port:
@ -58,11 +58,15 @@ Docker Desktop on Mac and Linux allows you to use the host’s SSH agent inside
1. Bind mount the SSH agent socket by adding the following parameter to your `docker run` command:
`--mount type=bind,src=/run/host-services/ssh-auth.sock,target=/run/host-services/ssh-auth.sock`
```console
$--mount type=bind,src=/run/host-services/ssh-auth.sock,target=/run/host-services/ssh-auth.sock
```
2. Add the `SSH_AUTH_SOCK` environment variable in your container:
`-e SSH_AUTH_SOCK="/run/host-services/ssh-auth.sock"`
```console
$ -e SSH_AUTH_SOCK="/run/host-services/ssh-auth.sock"
```
To enable the SSH agent in Docker Compose, add the following flags to your service:
@ -104,7 +108,7 @@ However if you are a Windows user, it works with Windows containers.
### I want to connect from a container to a service on the host
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
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. This is for development purpose and does not work in a production environment outside of Docker Desktop.
@ -129,7 +133,7 @@ If you have installed Python on your machine, use the following instructions as
#### I want to connect to a container from the host
Port forwarding works for `localhost`; `--publish`, `-p`, or `-P` all work.
Port forwarding works for `localhost`. `--publish`, `-p`, or `-P` all work.
Ports exposed from Linux are forwarded to the host.
Our current recommendation is to publish a port, or to connect from another

145
desktop/release-notes.md
View File

@ -24,13 +24,148 @@ Take a look at the [Docker Public Roadmap](https://github.com/docker/roadmap/pro
For frequently asked questions about Docker Desktop releases, see [FAQs](faqs/general.md/#releases)
## 4.18.0
{% include release-date.html date="2023-04-03" %}
> Download Docker Desktop
>
> {% include desktop-install.html %}
### New
- Initial beta release of `docker init` as per [the roadmap](https://github.com/docker/roadmap/issues/453).
- Added a new **Learning Center** tab to help users get started with Docker.
- Added an experimental file-watch command to Docker Compose that automatically updates your running Compose services as you edit and save your code.
### Upgrades
- [Buildx v0.10.4](https://github.com/docker/buildx/releases/tag/v0.10.4)
- [Compose 2.17.2](https://github.com/docker/compose/releases/tag/v2.17.2)
- [Containerd v1.6.18](https://github.com/containerd/containerd/releases/tag/v1.6.18), which includes fixes for [CVE-2023-25153](https://github.com/advisories/GHSA-259w-8hf6-59c2) and [CVE-2023-25173](https://github.com/advisories/GHSA-hmfx-3pcx-653p).
- [Docker Engine v20.10.24](https://docs.docker.com/engine/release-notes/20.10/#201024), which contains fixes for [CVE-2023-28841](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2023-28841),
[CVE-2023-28840](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2023-28840), and
[CVE-2023-28842](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2023-28842).
### Bug fixes and enhancements
#### For all platforms
- [Docker Scout CLI](../scout/index.md#docker-scout-cli) can now compare two images and display packages and vulnerabilities differences. This command is in [Early Access](../release-lifecycle.md) and might change in the future.
- [Docker Scout CLI](../scout/index.md#docker-scout-cli) now displays base image update and remediation recommendations using `docker scout recommendations`. It also displays a short overview of an image using `docker scout quickview` commands.
- You can now search for extensions direct from the Marketplace, as well as using **Global Search**.
- Fixed a bug where `docker buildx` container builders would lose access to the network after 24hrs.
- Reduced how often users are prompted for feedback on Docker Desktop.
- Removed minimum VM swap size.
- Added support for subdomain match, CIDR match, `.` and `_.` in HTTP proxy exclude lists.
- Fixed a bug in the transparent TLS proxy when the Server Name Indication field is not set.
- Fixed a grammatical error in Docker Desktop engine status message.
### For Windows
- Fixed a bug where `docker run --gpus=all` hangs. Fixes [docker/for-win#13324](https://github.com/docker/for-win/issues/13324).
- Fixed a bug where Registry Access Management policy updates were not downloaded.
- Docker Desktop now allows Windows containers to work when BitLocker is enabled on `C:`.
- Docker Desktop with the WSL backend no longer requires the `com.docker.service` privileged service to run permanently. For more information see [Permission requirements for Windows](https://docs.docker.com/desktop/windows/permission-requirements/).
### For Mac
- Fixed a performance issue where attributes stored on the host would not be cached for VirtioFS users.
- The first time Docker Desktop for Mac is launched, the user is presented with an installation window to confirm or adjust the configuration that requires privileged access. For more information see [Permission requirements for Mac](https://docs.docker.com/desktop/mac/permission-requirements/).
- Added the **Advanced** tab in **Settings**, where users can adjust the settings which require privileged access.
### For Linux
- Fixed a bug where the VM networking crashes after 24h. [docker/for-linux#131](https://github.com/docker/desktop-linux/issues/131)
### Security
#### For all platforms
- Fixed a security issue with the Artifactory Integration where it would fall back to sending registry credentials over plain HTTP if HTTPS check failed. Only users who have `Access experimental features` enabled are affected. Fixes [docker/for-win#13344](https://github.com/docker/for-win/issues/13344).
#### For Mac
- Removed the `com.apple.security.cs.allow-dyld-environment-variables` and `com.apple.security.cs.disable-library-validation` entitlements which allow an arbitrary dynamic library to be loaded with Docker Desktop via the `DYLD_INSERT_LIBRARIES` environment variable.
### Known Issues
- Uninstalling Docker Desktop on Mac from the **Troubleshoot** page might trigger an unexpected fatal error popup.
## 4.17.1
{% include release-date.html date="2023-03-20" %}
> Download Docker Desktop
>
> [Windows](https://desktop.docker.com/win/main/amd64/101757/Docker%20Desktop%20Installer.exe)
<div class="panel-group" id="accordion14" role="tablist" aria-multiselectable="true">
<div class="panel panel-default">
<div class="panel-heading" role="tab" id="heading14">
<h5 class="panel-title">
<a role="button" data-toggle="collapse" data-parent="#accordion14" href="#collapse14" aria-expanded="true" aria-controls="collapse14">
Checksums
<i class="fa fa-chevron-down"></i>
</a>
</h5>
</div>
<div id="collapse14" class="panel-collapse collapse" role="tabpanel" aria-labelledby="heading14">
<div class="panel-body">
<li><b>Windows:</b> SHA-256 2ea284648a5f708428f3a06bb8e1eb68cbeba6689b53c53d7ca24043a8f34800</li>
</div>
</div>
</div>
</div>
### Bug fixes and enhancements
#### For Windows
- Docker Desktop now allows Windows containers to work when BitLocker is enabled on C:
- Fixed a bug where `docker buildx` container builders would lose access to the network after 24hrs.
- Fixed a bug where Registry Access Management policy updates were not downloaded.
- Improved debug information to better characterise failures under WSL 2.
### Known Issues
- Running containers with `--gpus` on Windows with the WSL 2 backend does not work. This will be fixed in future releases. See [docker/for-win/13324](https://github.com/docker/for-win/issues/13324).
## 4.17.0
{% include release-date.html date="2023-02-27" %}
> Download Docker Desktop
>
> {% include desktop-install.html %}
> [Windows](https://desktop.docker.com/win/main/amd64/99724/Docker%20Desktop%20Installer.exe) |
> [Mac with Intel chip](https://desktop.docker.com/mac/main/amd64/99724/Docker.dmg) |
> [Mac with Apple chip](https://desktop.docker.com/mac/main/arm64/99724/Docker.dmg) |
> [Debian](https://desktop.docker.com/linux/main/amd64/99724/docker-desktop-4.17.0-amd64.deb) |
> [RPM](https://desktop.docker.com/linux/main/amd64/99724/docker-desktop-4.17.0-x86_64.rpm) |
> [Arch package](https://desktop.docker.com/linux/main/amd64/99724/docker-desktop-4.17.0-x86_64.pkg.tar.zst)
<div class="panel-group" id="accordion15" role="tablist" aria-multiselectable="true">
<div class="panel panel-default">
<div class="panel-heading" role="tab" id="heading15">
<h5 class="panel-title">
<a role="button" data-toggle="collapse" data-parent="#accordion15" href="#collapse15" aria-expanded="true" aria-controls="collapse15">
Checksums
<i class="fa fa-chevron-down"></i>
</a>
</h5>
</div>
<div id="collapse15" class="panel-collapse collapse" role="tabpanel" aria-labelledby="heading15">
<div class="panel-body">
<li><b>Windows:</b> SHA-256 69ea659b0ca0e160a1de9bd63dc5697f5eb89fff1d33484fb8ef9793e43d0d45</li>
<li><b>Mac Intel:</b> SHA-256 eb0531122a62859ce7b029e943fdad365603a916e6c15c107514c1e4a818d7ef</li>
<li><b>Mac Arm:</b> SHA-256 5e01465d93dfe18d7678a96705e7c26bb654b6766f06373b5cffbf77c641bccc</li>
<li><b>Linux DEB:</b> SHA-256 6828d35ae02763255790de6690909935a1f7c951373179ac0efd6c6b578b5219</li>
<li><b>Linux RPM:</b> SHA-256 7973c5bf41bdc78ca39ba64f93c6e4a33263d8dbfc604651bf1562bfeeea26f7</li>
<li><b>Linux Arch:</b> SHA-256 c783ce942c84f899d1f576d01d34fd4de3cefa0a1d577eda2bc5c4ceaec6cfdb</li>
</div>
</div>
</div>
</div>
### New
@ -115,17 +250,17 @@ For frequently asked questions about Docker Desktop releases, see [FAQs](faqs/ge
>
> [Windows](https://desktop.docker.com/win/main/amd64/96739/Docker%20Desktop%20Installer.exe)
<div class="panel-group" id="accordion10" role="tablist" aria-multiselectable="true">
<div class="panel-group" id="accordion14" role="tablist" aria-multiselectable="true">
<div class="panel panel-default">
<div class="panel-heading" role="tab" id="heading10">
<div class="panel-heading" role="tab" id="heading14">
<h5 class="panel-title">
<a role="button" data-toggle="collapse" data-parent="#accordion10" href="#collapse10" aria-expanded="true" aria-controls="collapse10">
<a role="button" data-toggle="collapse" data-parent="#accordion14" href="#collapse14" aria-expanded="true" aria-controls="collapse14">
Checksums
<i class="fa fa-chevron-down"></i>
</a>
</h5>
</div>
<div id="collapse10" class="panel-collapse collapse" role="tabpanel" aria-labelledby="heading10">
<div id="collapse14" class="panel-collapse collapse" role="tabpanel" aria-labelledby="heading14">
<div class="panel-body">
<li><b>Windows:</b> SHA-256 5f6db3cf5a2084fc7c584c90792f38a0caac91c4eed4f8653dde7bb8148517f1</li>
</div>

21
desktop/settings/mac.md
View File

@ -50,6 +50,27 @@ On the **General** tab, you can configure when to start Docker and specify other
- **Use Docker Compose V2**. Select to enable the `docker-compose` command to
use Docker Compose V2. For more information, see [Docker Compose V2](../../compose/compose-v2/index.md).
## Advanced
On the **Advanced** tab, you can reconfigure your initial installation settings:
- **Choose how to configure the installation of Docker's CLI tools**.
- **System**: Docker CLI tools are installed in the system directory under `/usr/local/bin`
- **User**: Docker CLI tools are installed in the user directory under `$HOME/.docker/bin`. You must then add `$HOME/.docker/bin` to your PATH. To add `$HOME/.docker/bin` to your path:
1. Open your shell configuration file. This is `~/.bashrc` if you're using a bash shell, or `~/.zshrc` if you're using a zsh shell.
2. Run the following command:
```console
$ export PATH=$PATH:~/.docker/bin
```
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](../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](../mac/permission-requirements.md#binding-privileged-ports).
For more information on each configuration
and use case, see [Permission requirements](../mac/permission-requirements.md).
## Resources
The **Resources** tab allows you to configure CPU, memory, disk, proxies,

4
desktop/uninstall.md
View File

@ -34,7 +34,7 @@ To uninstall Docker Desktop from your Windows machine:
<br>
To uninstall Docker Desktop from your Mac:
1. From the Docker menu, select **Troubleshoot** and then select **Uninstall**.
1. From the Docker menu, select the **Troubleshoot** icon in the top-right corner of Docker Dashboard and then select **Uninstall**.
2. Click **Uninstall** to confirm your selection.
> Uninstall Docker Desktop from the command line
@ -160,4 +160,4 @@ Remove the `credsStore` and `currentContext` properties from `$HOME/.docker/conf
<hr>
</div>
</div>
</div>

9
desktop/use-desktop/container.md
View File

@ -38,7 +38,7 @@ To open the integrated terminal, either:
You can obtain detailed information about the container when you select a container.
The **container view** displays **Logs**, **Inspect**, **Terminal**, and **Stats** tabs and provides quick action buttons to perform various actions.
The **container view** displays **Logs**, **Inspect**, **Terminal**, **Files**, and **Stats** tabs and provides quick action buttons to perform various actions.
- Select **Logs** to see logs from the container. You can also:
- Use `Cmd + f`/`Ctrl + f` to open the search bar and find specific entries. Search matches are highlighted in yellow.
@ -50,4 +50,11 @@ The **container view** displays **Logs**, **Inspect**, **Terminal**, and **Stats
- Select **Inspect** to view low-level information about the container. You can see the local path, version number of the image, SHA-256, port mapping, and other details.
- Select **Files** to explore the filesystem of running or stopped containers. You can also:
- See which files have been recently added, modified, or deleted
- Edit a file straight from the built-in editor
- Drag and drop files and folders between the host and the container
- Delete unnecessary files when you right-click on a file
- Download file and folders from the container straight to the host
- Select **Stats** to view information about the container resource utilization. You can see the amount of CPU, disk I/O, memory, and network I/O used by the container.

9
desktop/use-desktop/index.md
View File

@ -12,7 +12,7 @@ When you open Docker Desktop, the Docker Dashboard displays.
The **Containers** view provides a runtime view of all your containers and applications. It allows you to interact with containers and applications, and manage the lifecycle of your applications directly from your machine. This view also provides an intuitive interface to perform common actions to inspect, interact with, and manage your Docker objects including containers and Docker Compose-based applications. For more information, see [Explore running containers and applications](container.md).
The **Images** view displays a list of your Docker images and allows you to run an image as a container, pull the latest version of an image from Docker Hub, and inspect images. It also displays a summary of the vulnerability scanning report using Snyk. In addition, the **Images** view contains clean-up options to remove unwanted images from the disk to reclaim space. If you are logged in, you can also see the images you and your organization have shared on Docker Hub. For more information, see [Explore your images](images.md).
The **Images** view displays a list of your Docker images and allows you to run an image as a container, pull the latest version of an image from Docker Hub, and inspect images. It also displays a summary of image vulnerabilities. In addition, the **Images** view contains clean-up options to remove unwanted images from the disk to reclaim space. If you are logged in, you can also see the images you and your organization have shared on Docker Hub. For more information, see [Explore your images](images.md).
The **Volumes** view displays a list of volumes and allows you to easily create and delete volumes and see which ones are being used. For more information, see [Explore volumes](volumes.md).
@ -31,7 +31,7 @@ From the Docker Dashboard you can use Quick Search, which is located in the Dash
- Extensions. From here, you can learn more about the extension and install it with a single click. Or, if you already have an extension installed, you can open it straight from the search results.
- Any volume. From here you can view the associated container.
- Any volume. From here you can view the associated container.
## The Docker menu
@ -43,9 +43,9 @@ To display the Docker menu, right-click on the ![whale menu](../../assets/images
- **Sign in/Create Docker ID**
- **Settings**
- **Check for updates**
- **Troubleshoot**
- **Troubleshoot**
- **Switch to Windows containers**
- **About Docker Desktop**. Contains information on the versions you are running, and links to the Subscription Service Agreement for example.
- **About Docker Desktop**. Contains information on the versions you are running, and links to the Subscription Service Agreement for example.
- **Documentation**
- **Quick Start Guide**. Launches the Quick Start Guide.
- **Docker Hub**
@ -54,4 +54,3 @@ To display the Docker menu, right-click on the ![whale menu](../../assets/images
- **Pause**
- **Restart**
- **Quit Docker Desktop**

17
desktop/windows/permission-requirements.md
View File

@ -6,7 +6,7 @@ redirect_from:
- /desktop/windows/privileged-helper/
---
This page contains information about the permission requirements for running and installing Docker Desktop on Windows, the functionality of the privileged helper process `com.docker.service.exe` and the reasoning behind this approach.
This page contains information about the permission requirements for running and installing Docker Desktop on Windows, the functionality of the privileged helper process `com.docker.service` and the reasoning behind this approach.
It also provides clarity on running containers as `root` as opposed to having `Administrator` access on the host and the privileges of the Windows Docker engine and Windows containers.
@ -14,11 +14,11 @@ It also provides clarity on running containers as `root` as opposed to having `A
While Docker Desktop on Windows can be run without having `Administrator` privileges, it does require them during installation. On installation the user gets a UAC prompt which allows a privileged helper service to be installed. After that, Docker Desktop can be run by users without administrator privileges, provided they are members of the `docker-users` group. The user who performs the installation is automatically added to this group, but other users must be added manually. This allows the administrator to control who has access to Docker Desktop.
The reason for this approach is that Docker Desktop needs to perform a limited set of privileged operations which are conducted by the privileged helper process `com.docker.service.exe`. This approach allows, following the principle of least privilege, `Administrator` access to be used only for the operations for which it is absolutely necessary, while still being able to use Docker Desktop as an unprivileged user.
The reason for this approach is that Docker Desktop needs to perform a limited set of privileged operations which are conducted by the privileged helper process `com.docker.service`. This approach allows, following the principle of least privilege, `Administrator` access to be used only for the operations for which it is absolutely necessary, while still being able to use Docker Desktop as an unprivileged user.
## Privileged Helper
The privileged helper `com.docker.service.exe` is a Windows service which runs in the background with `SYSTEM` privileges. It listens on the named pipe `//./pipe/dockerBackendV2`. The developer runs the Docker Desktop application, which connects to the named pipe and sends commands to the service. This named pipe is protected, and only users that are part of the `docker-users` group can have access to it.
The privileged helper `com.docker.service` is a Windows service which runs in the background with `SYSTEM` privileges. It listens on the named pipe `//./pipe/dockerBackendV2`. The developer runs the Docker Desktop application, which connects to the named pipe and sends commands to the service. This named pipe is protected, and only users that are part of the `docker-users` group can have access to it.
The service performs the following functionalities:
- Ensuring that `kubernetes.docker.internal` is defined in the Win32 hosts file. Defining the DNS name `kubernetes.docker.internal` allows Docker to share Kubernetes contexts with containers.
@ -33,18 +33,19 @@ The service performs the following functionalities:
- Checking if required Windows features are both installed and enabled.
- Conducting healthchecks and retrieving the version of the service itself.
The service start mode depends on which container engine is selected:
- With Windows containers, or Hyper-v Linux containers the service is started when the system boots and runs all the time, even when Docker Desktop isn't running. This is required for the user to be able to launch Docker Desktop without admin privileges. If the user switches to WSL2 Linux containers, the service is stopped and doesn't start automatically upon next Windows boot.
- With WSL2 Linux containers, the service isn't necessary and therefore doesn't run automatically when the system boots. If the user switches to Windows containers or Hyper-v Linux containers, a UAC prompt is displayed which asks the user to accept the privileged operation to start the service. If accepted, the service is started and set to start automatically upon the next Windows boot.
## Containers running as root within the Linux VM
The Linux Docker daemon and containers run in a minimal, special-purpose Linux VM managed by Docker. It is immutable so users can’t extend it or change the installed software.
This means that although containers run by default as `root`, this does not allow altering the VM and does not grant `Administrator` access to the Windows host machine. The Linux VM serves as a security boundary and limits what resources from the host can be accessed. File sharing uses a user-space crafted file server and any directories from the host bind mounted into Docker containers still retain their original permissions. It does not give the user access to any files that it doesn’t already have access to.
This means that although containers run by default as `root`, this doesn't allow altering the VM and doesn't grant `Administrator` access to the Windows host machine. The Linux VM serves as a security boundary and limits what resources from the host can be accessed. File sharing uses a user-space crafted file server and any directories from the host bind mounted into Docker containers still retain their original permissions. It doesn't give the user access to any files that it doesn’t already have access to.
## Windows Containers
Unlike the Linux Docker engine and containers which run in a VM, Windows containers are an operating system feature, and run directly on the Windows host with `Administrator` privileges. For organizations which do not want their developers to run Windows containers, a `–no-windows-containers` installer flag is available from version 4.11 to disable their use.
Unlike the Linux Docker engine and containers which run in a VM, Windows containers are an operating system feature, and run directly on the Windows host with `Administrator` privileges. For organizations who don't want their developers to run Windows containers, a `–no-windows-containers` installer flag is available from version 4.11 to disable their use.
## Networking
For network connectivity, Docker Desktop uses a user-space process (`vpnkit`), which inherits constraints like firewall rules, VPN, HTTP proxy properties etc. from the user that launched it.

8
develop/remote-development.md
View File

@ -32,7 +32,7 @@ remote resources helps simplify and speed up the inner loop. There are several
tools available, commercial and open-source, that you can use to enable a hybrid
local-and-remote development environment. For example:
- [Telepresence](https://www.cncf.io/projects/telepresence/){: target="_blank" rel="noopener" class="_" }
- [Telepresence](https://app.getambassador.io/auth/realms/production/protocol/openid-connect/auth?client_id=docker-docs&response_type=code&redirect_uri=https%3A%2F%2Fapp.getambassador.io&utm_source=docker-docs&utm_medium=dockerwebsite&utm_campaign=Docker%26TP){: target="_blank" rel="noopener" class="_" }
- [CodeZero](https://www.codezero.io/){: target="_blank" rel="noopener" class="_" }
- [Gefyra](https://gefyra.dev/){: target="_blank" rel="noopener" class="_" }
- [kubefwd](https://kubefwd.com/){: target="_blank" rel="noopener" class="_" }
@ -72,9 +72,9 @@ You have a few options for how the local containers can integrate with the clust
Telepresence is free and open-source, and you can try it out by heading to
the
[Telepresence quickstart guide](https://www.telepresence.io/docs/latest/quick-start/){: target="_blank" rel="noopener" class="_" }.
[Telepresence quickstart guide](https://www.telepresence.io/docs/latest/quick-start/?utm_source=docker-docs&utm_medium=dockerwebsite&utm_campaign=Docker-TP){: target="_blank" rel="noopener" class="_" }.
There’s also a
[Telepresence extension for Docker Desktop](https://www.getambassador.io/docs/telepresence/latest/extension/intro){: target="_blank" rel="noopener" class="_" },
[Telepresence extension for Docker Desktop](https://www.getambassador.io/docs/telepresence/latest/extension/intro?utm_source=docker-docs&utm_medium=dockerwebsite&utm_campaign=Docker-TP){: target="_blank" rel="noopener" class="_" },
which helps you manage intercepts for your containers.
### Docker × Ambassador
@ -92,7 +92,7 @@ local-remote development environment easy and seamless. You can now connect your
Docker ID to Ambassador Cloud to sign in and use Telepresence. To get started:
1. Go to the
[Docker × Ambassador](https://app.getambassador.io/auth/realms/production/protocol/openid-connect/auth?client_id=docker-docs&response_type=code&redirect_uri=https://app.getambassador.io)
[Docker × Ambassador](https://app.getambassador.io/auth/realms/production/protocol/openid-connect/auth?client_id=docker-docs&response_type=code&redirect_uri=https%3A%2F%2Fapp.getambassador.io&utm_source=docker-docs&utm_medium=dockerwebsite&utm_campaign=Docker%26TP)
page.
2. Sign in using your Docker ID.
3. Authorize the Ambassador Cloud app.

23
docker-hub/2fa/disable-2fa.md
View File

@ -4,25 +4,16 @@ keywords: Docker, docker, registry, security, Docker Hub, authentication, two-fa
title: Disable two-factor authentication on Docker Hub
---
> **Note:**
> Disabling two-factor authentication will result in decreased security for your
> **Warning**
>
> Disabling two-factor authentication results in decreased security for your
> Docker Hub account.
{: .warning }
## Prerequisites
Two-factor authentication is enabled on your Docker Hub account.
## Disable two-factor authentication
To disable two-factor authentication, log in to your Docker Hub account. Click
on your username and select **Account Settings**. Go to Security and click on
**Disable 2FA**.
1. Sign in to your Docker Hub account.
2. Select your username and then from the dropdown menu, select **Account Settings**.
3. Navigate to the **Security** tab and select **Disable 2FA**.
4. Enter your password and select **Disable 2FA**.
![Disable 2FA button](../images/2fa-disable-2fa.png)
You will be prompted to input your Docker ID password. Enter your password and
click **Disable 2FA**.
![Enter your password view](../images/2fa-enter-pw-disable-2fa.png){:width="250px"}
You have successfully disabled two-factor authentication.

56
docker-hub/2fa/index.md
View File

@ -4,12 +4,11 @@ keywords: Docker, docker, registry, security, Docker Hub, authentication, two-fa
title: Enable two-factor authentication for Docker Hub
---
## About two-factor authentication
Two-factor authentication adds an extra layer of security to your Docker Hub
account by requiring a unique security code when you log into your account. The
security code will be required in addition to your password.
account by requiring a unique security code when you sign in to your account. The
security code is required in addition to your password.
When you enable two-factor authentication, you will also be provided a recovery
When you enable two-factor authentication, you are also provided with a recovery
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 Hub account](recover-hub-account/).
@ -21,45 +20,20 @@ You need a mobile phone with a time-based one-time password authenticator
application installed. Common examples include Google Authenticator or Yubico
Authenticator with a registered YubiKey.
> **Note:**
> Two-factor authentication is currently in beta. Feel free to provide feedback
> at the [Docker Hub feedback repo](https://github.com/docker/hub-feedback/issues).
{: .important}
## Enable two-factor authentication
To enable two-factor authentication, log in to your Docker Hub account. Click
on your username and select **Account Settings**. Go to Security and click
**Enable Two-Factor Authentication**.
1. Sign to your Docker Hub account.
2. Select your username and then from the dropdown menu, select **Account Settings**.
3. Select the **Security** tab and then select **Enable Two-Factor Authentication**.
The next page reminds you to download an authenticator app.
4. Select **Set up using an app**.
Your unique recovery code is sent to you.
5. Save your recovery code and store it somewhere safe.
Your recovery code can be used to recover your account in the event you lose access to your authenticator app.
![Two-factor home](../images/2fa-security-home.png)
6. Select **Next** and then open your authenticator app.
You can choose between scanning the QR code or entering a text code into your authenticator app.
7. Once you have linked your authenticator app, enter the six-digit code to in text field and then select **Next**.
The next page will remind you to download an authenticator app. Click **Set up**
**using an app**. You will receive your unique recovery code.
> **Save your recovery code and store it somewhere safe.**
>
> Your recovery code can be used to recover your account in the event you lose
> access to your authenticator app.
{: .important }
![Recovery code example](../images/2fa-recovery-code.png)
After you have saved your code, click **Next**.
Open your authenticator app. You can choose between scanning the QR code or
entering a text code into your authenticator app. Once you have linked your
authenticator app, it will give you a six-digit code to enter in text field.
Click **Next**.
![Enter special code view](../images/2fa-enter-code.png)
You have successfully enabled two-factor authentication. The next time you log
Two-factor authentication is now enabled. The next time you sign
in to your Docker Hub account, you will be asked for a security code.
> **Note:**
> Now that you have two-factor authentication enabled on your account, you must
> create at least one personal access token. Otherwise, you will be unable to
> log in to your account from the Docker CLI. See [Managing access tokens](../access-tokens)
> for more information.
{: .important }

18
docker-hub/2fa/new-recovery-code.md
View File

@ -7,20 +7,12 @@ title: Generate a new recovery code
If you have lost your two-factor authentication recovery code and still have
access to your Docker Hub account, you can generate a new recovery code.
## Prerequisites
Two-factor authentication is enabled on your Docker Hub account.
## Generate a new recovery code
To disable two-factor authentication, log in to your Docker Hub account. Click
on your username and select **Account Settings**. Go to **Security** and **Click here to generate a new code**.
1. Sign in to your Docker Hub account.
2. Select your username and then from the dropdown menu, select **Account Settings**.
3. Navigate to the **Security** tab and select **Click here to generate a new code**.
4. Enter your password.
![New recovery code link](../images/2fa-disable-2fa.png)
Enter your password.
![Enter your password view](../images/2fa-pw-new-code.png){:width="250px"}
Your new recovery code will be displayed. Remember to save your recovery code
Your new recovery code is displayed. Remember to save your recovery code
and store it somewhere safe.

8
docker-hub/2fa/recover-hub-account.md
View File

@ -5,9 +5,9 @@ title: Recover your Docker Hub account
---
If you have lost access to both your two-factor authentication application and
your recovery code,
If you have lost access to both your two-factor authentication application and your recovery code:
1. Navigate to [Docker Hub](https://hub.docker.com){: target="_blank" rel="noopener" class="_"} and enter your username and password.
2. Click **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){:target="_blank" rel="noopener" class="_"}. You must enter the primary email address associated with your Docker ID in the Contact Support form for recovery instructions.
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){:target="_blank" rel="noopener" class="_"}.
You must enter the primary email address associated with your Docker ID in the Contact Support form for recovery instructions.

69
docker-hub/access-tokens.md
View File

@ -1,67 +1,49 @@
---
title: Manage access tokens
title: Create and manage access tokens
description: Learn how to create and manage your personal Docker Hub access tokens to securely push and pull images programmatically.
keywords: docker hub, hub, security, PAT, personal access token
---
Docker Hub lets you create personal access tokens as alternatives to your password. You can use tokens to access Hub images from the Docker CLI.
If you are using the [Docker Hub CLI](https://github.com/docker/hub-tool#readme){: target="_blank" rel="noopener" class="_"}
tool (currently experimental) to access Hub images from the Docker CLI, you can create personal access tokens (PAT) as alternatives to your password.
Using personal access tokens provides some advantages over a password:
Compared to passwords, personal access tokens provide the following advantages:
* You can investigate the last usage of the access token and 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.
- 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.
Docker provides a [Docker Hub CLI](https://github.com/docker/hub-tool#readme){: target="_blank" rel="noopener" class="_"}
tool (currently experimental) and an API that allows you to interact with Docker Hub. Browse through the [Docker Hub API](/docker-hub/api/latest/){: target="_blank" rel="noopener" class="_"} documentation to explore the supported endpoints.
> **Important**
>
> Treat access tokens like your password and keep them secret. Store your
> tokens securely (for example, in a credential manager).
{: .important}
Access tokens are valuable for building integrations, as you can issue
multiple tokens &ndash; one for each integration &ndash; and revoke them at
Access tokens are also valuable for building integrations, as you can issue multiple tokens, one for each integration, and revoke them at
any time.
> **Note**
>
> If you have [two-factor authentication (2FA)](2fa/index.md) enabled on
> your account, you must create at least one personal access token. Otherwise,
> you will be unable to log in to your account from the Docker CLI.
> you won't be able to sign in to your account from the Docker CLI.
## Create an access token
The following video walks you through the process of managing access tokens.
> **Important**
>
> Treat access tokens like your password and keep them secret. Store your tokens securely in a credential manager for example.
{: .important}
<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/Qs5xGj85Aek" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
1. Sign in to [Docker Hub](https://hub.docker.com){: target="_blank" rel="noopener" class="_"}.
To create your access token:
2. Select your username in the top-right corner and from the dropdown menu select **Account Settings**.
1. Log in to [hub.docker.com](https://hub.docker.com){: target="_blank" rel="noopener" class="_"}.
2. Click on your username in the top right corner and select **[Account Settings](https://hub.docker.com/settings/general)**.
3. Select **[Security](https://hub.docker.com/settings/security) > New Access Token**.
4. Add a description for your token. Use something that indicates where the token
will be used, or set a purpose for the token. You can view the following access
permissions from the drop-down:
![New access token menu](images/hub-create-token.png){:width="700px"}
3. Select the **Security** tab and then **New Access Token**.
4. Add a description for your token. Use something that indicates the use case or purpose of the token.
5. 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 not delete the repository.
5. Copy the token that appears on the screen and save it. You will not be able
6. 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.
![Copy access token view](images/hub-copy-token.png){:width="700px"}
## Use an access token
You can use an access token anywhere that requires your Docker Hub
@ -81,16 +63,11 @@ a password.
You can rename, activate, deactivate, or delete a token as needed.
1. Access your tokens under **[Account Settings > Security](https://hub.docker.com/settings/security){: target="_blank" rel="noopener" class="_"}**.
1. Access your tokens under **Account Settings > Security**.
This page shows an overview of all your tokens. You can also view the number
of tokens that are activated and deactivated in the toolbar.
![Delete or edit and access token](images/hub-delete-edit-token.png){:width="700px"}
2. Choose a token and then select **Delete** or **Edit**, or use the menu on the far right of a token row to bring up the edit screen.
You can also select multiple tokens to delete at once.
2. Select a token and click **Delete** or **Edit**, or use the menu on
the far right of a token row to bring up the edit screen. You can also
select multiple tokens to delete at once.
![Modify an access token](images/hub-edit-token.png){:width="700px"}
3. After modifying the token, click the **Save** button to save your changes.
3. After modifying the token, select **Save**.

70
docker-hub/admin-overview.md Normal file
View File

@ -0,0 +1,70 @@
---
title: Administration
description: landing page for administration topic
keywords: administration, docker hub, admin
---
Sign in to Docker Hub to change account settings and carry out administrative or security-related tasks.
<div class="component-container">
<!--start row-->
<div class="row">
<div class="col-xs-12 col-sm-12 col-md-12 col-lg-4 block">
<div class="component">
<div class="component-icon">
<a href="/docker-hub/orgs/"><img src="/assets/images/contact.svg" alt="Set-up-an-org" width="70" height="70"></a>
</div>
<h2 id="set-up-an-org">Set up an organization</h2>
<p> <a href="/docker-hub/orgs/">Explore and set up an organization in Docker Hub</a></p>
</div>
</div>
<div class="col-xs-12 col-sm-12 col-md-12 col-lg-4 block">
<div class="component">
<div class="component-icon">
<a href="/docker-hub/orgs/"><img src="/assets/images/explore.svg" alt="onboard" width="70" height="70"></a>
</div>
<h2 id="onboard-users">Onboard users to your teams and organizations</h2>
<p>Learn how to onboard with <a href="/docker-hub/onboard-team/">Docker Team</a> or <a href="/docker-hub/onboard-business/">Docker Business</a> subscription.</p>
</div>
</div>
<div class="col-xs-12 col-sm-12 col-md-12 col-lg-4 block">
<div class="component">
<div class="component-icon">
<a href="/desktop/hardened-desktop/"><img src="/assets/images/lock.svg" alt="Release notes" width="70" height="70"></a>
</div>
<h2 id="hardened-desktop"><a href="/desktop/hardened-desktop/">Use Hardened Docker Desktop</a></h2>
<p>Explore the security model for Docker Desktop.</p>
</div>
</div>
</div>
<!--start row-->
<div class="row">
<div class="col-xs-12 col-sm-12 col-md-12 col-lg-4 block">
<div class="component">
<div class="component-icon">
<a href="/docker-hub/configure-sign-in/"><img src="/assets/images/sign-on.svg" alt="sign-in" width="70" height="70"></a>
</div>
<h2 id="sign-in"><a href="/docker-hub/configure-sign-in/">Enforce sign in</a></h2>
<p>Configure sign in for members of your teams and organizations.</p>
</div>
</div>
<div class="col-xs-12 col-sm-12 col-md-12 col-lg-4 block">
<div class="component">
<div class="component-icon">
<a href="/single-sign-on/"><img src="/assets/images/sso.svg" alt="SSO" width="70" height="70"></a>
</div>
<h2 id="SSO"><a href="/single-sign-on/">Enable Single Sign-On</a></h2>
<p>Understand and use Single Sign-On.</p>
</div>
</div>
<div class="col-xs-12 col-sm-12 col-md-12 col-lg-4 block">
<div class="component">
<div class="component-icon">
<a href="/docker-hub/2fa/"><img src="/assets/images/secure.svg" alt="2fa" width="70" height="70"></a>
</div>
<h2 id="2fa"><a href="/docker-hub/2fa/">Set up two-factor authentication</a></h2>
<p>Add an extra layer of authentication to your Docker account.</p>
</div>
</div>
</div>
</div>

34
docker-hub/audit-log.md
View File

@ -4,30 +4,33 @@ keywords: Team, organization, activity, log, audit, activities
title: Audit logs
---
{% include upgrade-cta.html
body="Audit logs are available for users subscribed to a Docker Team or a Business subscription. Upgrade now to start tracking events across your organization."
header-text="This feature requires a paid Docker subscription"
target-url="https://www.docker.com/pricing?utm_source=docker&utm_medium=webreferral&utm_campaign=docs_driven_upgrade_audit_log"
%}
> **Note**
>
> Audit logs requires a [Docker Team, or Business subscription](../subscription/index.md).
Audit logs display a chronological list of activities that occur at organization and repository levels. It provides owners of Docker Team accounts a report of all their team member activities. This allows the team owners to view and track what changes were made, the date when a change was made, and who initiated the change. For example, the audit logs display activities such as the date when a repository was created or deleted, the team member who created the repository, the name of the repository, and when there was a change to the privacy settings.
Audit logs display a chronological list of activities that occur at organization and repository levels. It provides a report to owners of Docker Team on all their team member activities.
With audit logs, team owners can view and track:
- What changes were made
- The date when a change was made
- Who initiated the change
For example, Audit logs display activities such as the date when a repository was created or deleted, the team member who created the repository, the name of the repository, and when there was a change to the privacy settings.
Team owners can also see the audit logs for their repository if the repository is part of the organization subscribed to a Docker Team plan.
Audit logs began tracking activities from the date the feature went live, that is from 25 January 2021. Activities that took place before this date are not captured.
## View the audit logs
To view the audit logs:
1. Sign into an owner account for the organization in Docker Hub.
2. Select your organization from the list and then click on the **Activity** tab.
![Organization activity tab](images/org-activity-tab.png){:width="700px"}
The audit logs begin tracking activities from the date the feature is live, that is from **25 January 2021**. Activities that took place before this date are not captured.
1. Sign in to Docker Hub.
2. Select your organization from the list and then select the **Activity** tab.
> **Note**
>
> Docker will retain the activity data for a period of three months.
> Docker retains the activity data for a period of three months.
## Customize the audit logs
@ -39,10 +42,9 @@ By default, all activities that occur at organization and repository levels are
>
> Activities created by the Docker Support team as part of resolving customer issues appear in the audit logs as **dockersupport**.
Click the **All Activities** drop-down list to view activities that are specific to an organization or a repository. After choosing **Organization** or **Repository**, you can further refine the results using the **All Actions** drop-down list. If you select the **Activities** tab from the **Repository** view, you can only filter repository-level activities.
![Refine organization activities](images/org-all-actions.png){:width="600px"}
Select the **All Activities** dropdown to view activities that are specific to an organization, repository, or billing. If you select the **Activities** tab from the **Repository** view, you can only filter repository-level activities.
After choosing **Organization**, **Repository**, or **Billing**, you can further refine the results using the **All Actions** dropdown.
## Audit logs event definitions

46
docker-hub/builds/advanced.md
View File

@ -6,11 +6,10 @@ redirect_from:
- /docker-cloud/builds/advanced/
---
{% include upgrade-cta.html
body="The Automated Builds feature is available for Docker Pro, Team, and Business users. Upgrade now to automatically build and push your images. If you are using automated builds for an open-source project, you can join our [Open Source Community](https://www.docker.com/community/open-source/application){: target='_blank' rel='noopener' class='_'} program to learn how Docker can support your project on Docker Hub."
header-text="This feature requires a Docker subscription"
target-url="https://www.docker.com/pricing?utm_source=docker&utm_medium=webreferral&utm_campaign=docs_driven_upgrade_auto_builds"
%}
> **Note**
>
> Automated builds require a
> [Docker Pro, Team, or Business subscription](../../subscription/index.md).
The following options allow you to customize your automated build and automated
test processes.
@ -21,8 +20,10 @@ Several utility environment variables are set by the build process, and are
available during automated builds, automated tests, and while executing
hooks.
> **Note**: These environment variables are only available to the build and test
processes and do not affect your service's run environment.
> **Note**
>
> These environment variables are only available to the build and test
processes and don't affect your service's run environment.
* `SOURCE_BRANCH`: the name of the branch or the tag that is currently being tested.
* `SOURCE_COMMIT`: the SHA1 hash of the commit being tested.
@ -51,12 +52,15 @@ services:
Docker Hub allows you to override and customize the `build`, `test` and `push`
commands during automated build and test processes using hooks. For example, you
might use a build hook to set build arguments used only during the build
process. (You can also set up [custom build phase hooks](#custom-build-phase-hooks)
to perform actions in between these commands.)
process. You can also set up [custom build phase hooks](#custom-build-phase-hooks)
to perform actions in between these commands.
**Use these hooks with caution.** The contents of these hook files replace the
> **Important**
>
>Use these hooks with caution. The contents of these hook files replace the
basic `docker` commands, so you must include a similar build, test or push
command in the hook or your automated process does not complete.
{: .important}
To override these phases, create a folder called `hooks` in your source code
repository at the same directory level as your Dockerfile. Create a file called
@ -64,7 +68,7 @@ repository at the same directory level as your Dockerfile. Create a file called
builder process can execute, such as `docker` and `bash` commands (prefixed
appropriately with `#!/bin/bash`).
These hooks will be running on an instance of [Amazon Linux 2](https://aws.amazon.com/amazon-linux-2/){:target="_blank" rel="noopener" class="_"},
These hooks run on an instance of [Amazon Linux 2](https://aws.amazon.com/amazon-linux-2/){:target="_blank" rel="noopener" class="_"},
a distro based on Red Hat Enterprise Linux (RHEL), which includes interpreters
such as Perl or Python, and utilities such as `git` or `curl`. Refer to the
[Amazon Linux 2 documentation](https://aws.amazon.com/amazon-linux-2/faqs/){:target="_blank" rel="noopener" class="_"}
@ -89,15 +93,15 @@ The following hooks are available:
* `hooks/post_build`
* `hooks/pre_test`
* `hooks/post_test`
* `hooks/pre_push` (only used when executing a build rule or [automated build](index.md) )
* `hooks/post_push` (only used when executing a build rule or [automated build](index.md) )
* `hooks/pre_push` (only used when executing a build rule or [Automated build](index.md) )
* `hooks/post_push` (only used when executing a build rule or [Automated build](index.md) )
### Build hook examples
#### Override the "build" phase to set variables
Docker Hub allows you to define build environment variables either in the hook
files, or from the automated build interface (which you can then reference in hooks).
files, or from the automated build interface, which you can then reference in hooks.
In the following example, we define a build hook that uses `docker build` arguments
to set the variable `CUSTOM` based on the value of variable we defined using the
@ -109,9 +113,11 @@ the image being built.
$ docker build --build-arg CUSTOM=$VAR -f $DOCKERFILE_PATH -t $IMAGE_NAME .
```
> **Caution**: A `hooks/build` file overrides the basic [docker build](../../engine/reference/commandline/build.md) command
used by the builder, so you must include a similar build command in the hook or
> **Important**
>
> A `hooks/build` file overrides the basic [docker build](../../engine/reference/commandline/build.md) command used by the builder, so you must include a similar build command in the hook or
the automated build fails.
{: .important}
Refer to the [docker build documentation](../../engine/reference/commandline/build.md#build-arg)
to learn more about Docker build-time variables.
@ -128,15 +134,15 @@ $ docker tag $IMAGE_NAME $DOCKER_REPO:$SOURCE_COMMIT
$ docker push $DOCKER_REPO:$SOURCE_COMMIT
```
## Source Repository / Branch Clones
## Source repository or branch clones
When Docker Hub pulls a branch from a source code repository, it performs
a shallow clone (only the tip of the specified branch). This has the advantage
a shallow clone, it clones only the tip of the specified branch. This has the advantage
of minimizing the amount of data transfer necessary from the repository and
speeding up the build because it pulls only the minimal code necessary.
Because of this, if you need to perform a custom action that relies on a different
branch (such as a `post_push` hook), you can't checkout that branch, unless
As a result, if you need to perform a custom action that relies on a different
branch, such as a `post_push` hook, you can't checkout that branch unless
you do one of the following:
* You can get a shallow checkout of the target branch by doing the following:

49
docker-hub/builds/automated-testing.md
View File

@ -7,18 +7,17 @@ redirect_from:
title: Automated repository tests
---
{% include upgrade-cta.html
body="The Automated Builds feature is available for Docker Pro, Team, and Business users. Upgrade now to automatically build and push your images. If you are using automated builds for an open-source project, you can join our [Open Source Community](https://www.docker.com/community/open-source/application){: target='_blank' rel='noopener' class='_'} program to learn how Docker can support your project on Docker Hub."
header-text="This feature requires a Docker subscription"
target-url="https://www.docker.com/pricing?utm_source=docker&utm_medium=webreferral&utm_campaign=docs_driven_upgrade_auto_builds"
%}
> **Note**
>
> Automated builds require a
> [Docker Pro, Team, or Business subscription](../../subscription/index.md).
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)
to run tests on each pull request to the source code repository to create a
continuous integration testing service.
Enabling `Autotest` builds an image for testing purposes, but does **not**
Enabling `Autotest` builds an image for testing purposes, but does not
automatically push the built image to the Docker repository. If you want to push
built images to your Docker Hub repository, enable [Automated Builds](index.md).
@ -43,28 +42,27 @@ a container using the built image.
You can define any number of linked services in this file. The only requirement
is that `sut` is defined. Its return code determines if tests passed or not.
Tests **pass** if the `sut` service returns `0`, and **fail** otherwise.
Tests pass if the `sut` service returns `0`, and fail otherwise.
> **Note**
>
> Only the `sut` service and all other services listed in
> [`depends_on`](../../compose/compose-file/compose-file-v2.md#depends_on) are
> [`depends_on`](../../compose/compose-file/05-services.md#depends_on) are
> started. If you have services that poll for changes in other services, be sure
> to include the polling services in the [`depends_on`](../../compose/compose-file/compose-file-v2.md#depends_on)
> to include the polling services in the [`depends_on`](../../compose/compose-file/05-services.md#depends_on)
> list to make sure all of your services start.
> Also make sure to include a compose file version from 2.0 upward as `depends_on`
> was added in [version 2.0](../../compose/compose-file/compose-versioning.md#version-2)
> file format.
You can define more than one `docker-compose.test.yml` file if needed. Any file
that ends in `.test.yml` is used for testing, and the tests run sequentially.
You can also use [custom build hooks](advanced.md#override-build-test-or-push-commands)
to further customize your test behavior.
> **Note**: If you enable Automated builds, they also run any tests defined
> **Note**
>
> If you enable Automated builds, they also run any tests defined
in the `test.yml` files.
## Enable automated tests on a repository
## Enable Automated tests on a repository
To enable testing on a source code repository, you must first create an
associated build-repository in Docker Hub. Your `Autotest` settings are
@ -72,24 +70,24 @@ configured on the same page as [automated builds](index.md), however
you do not need to enable Autobuilds to use `Autotest`. Autobuild is enabled per
branch or tag, and you do not need to enable it at all.
Only branches that are configured to use **Autobuild** push images to the
Only branches that are configured to use Autobuild push images to the
Docker repository, regardless of the Autotest settings.
1. Log in to Docker Hub and select **Repositories** in the top navigation.
1. Sign in to Docker Hub and select **Repositories**.
2. Select the repository you want to enable `Autotest` on.
3. From the repository view, click the **Builds** tab.
3. From the repository view, select the **Builds** tab.
4. Click **Configure automated builds**.
4. Select **Configure automated builds**.
5. Configure the automated build settings as explained in [Automated Builds](index.md).
At minimum you must configure:
* The source code repository
* the build location
* at least one build rule
* The build location
* At least one build rule
6. Choose your **Autotest** option.
@ -106,19 +104,22 @@ Docker repository, regardless of the Autotest settings.
pull requests to branches that match a build rule, including when the
pull request originated in an external source repository.
> **Note**: For security purposes, autotest on _external pull requests_ is
> **Important**
>
>For security purposes, autotest on external pull requests is
limited on public repositories. Private images are not pulled and
environment variables defined in Docker Hub are not
available. Automated builds continue to work as usual.
{: .important}
7. Click **Save** to save the settings, or click **Save and build** to save and
7. Select **Save** to save the settings, or select **Save and build** to save and
run an initial test.
## Check your test results
From the repository's details page, click **Timeline**.
From the repository's details page, select **Timeline**.
From this tab you can see any pending, in-progress, successful, and failed
builds and test runs for the repository.
You can click any timeline entry to view the logs for each test run.
You can choose any timeline entry to view the logs for each test run.

41
docker-hub/builds/how-builds-work.md Normal file
View File

@ -0,0 +1,41 @@
---
description: how automated builds work
keywords: docker hub, automated builds
title: How Automated builds work
---
> **Note**
>
> Automated builds require a
> [Docker Pro, Team, or Business subscription](../../subscription/index.md).
Docker Hub can automatically build images from source code in an external
repository and automatically push the built image to your Docker repositories.
![An automated build dashboard](images/index-dashboard.png){:width="750px"}
When you set up Automated builds, also called autobuilds, you create a list of
branches and tags that you want to build into Docker images. When you push code
to a source-code branch, for example in GitHub, for one of those listed image
tags, the push uses a webhook to trigger a new build, which produces a Docker
image. The built image is then pushed to Docker Hub.
> **Note**
>
> You can still use `docker push` to push pre-built images to
repositories with Automated builds configured.
If you have automated tests configured, these run after building but before
pushing to the registry. You can use these tests to create a continuous
integration workflow where a build that fails its tests doesn't push the built
image. Automated tests don't push images to the registry on their own. [Learn about automated image testing](automated-testing.md).
Depending on your [subscription](https://www.docker.com/pricing){: target="_blank" rel="noopener" class="_"},
you may get concurrent builds, which means that `N` autobuilds can be run at the
same time. `N` is configured according to your subscription. Once `N+1` builds
are running, any additional builds go into a queue to be run later.
The maximum number of pending builds in the queue is 30 and Docker Hub discards further
requests. The number of concurrent builds for Pro is 5 and
for Team and Business is 15.

279
docker-hub/builds/index.md
View File

@ -1,5 +1,5 @@
---
description: Set up automated builds
description: Set up Automated builds
keywords: automated, build, images, Docker Hub
redirect_from:
- /docker-hub/builds/automated-build/
@ -10,59 +10,28 @@ redirect_from:
title: Set up Automated Builds
---
{% include upgrade-cta.html
body="The Automated Builds feature is available for Docker Pro, Team, and Business users. Upgrade now to automatically build and push your images. If you are using automated builds for an open-source project, you can join our [Open Source Community](https://www.docker.com/community/open-source/application){: target='_blank' rel='noopener' class='_'} program to learn how Docker can support your project on Docker Hub."
header-text="This feature requires a Docker subscription"
target-url="https://www.docker.com/pricing?utm_source=docker&utm_medium=webreferral&utm_campaign=docs_driven_upgrade_auto_builds"
%}
## How Automated Builds work
Docker Hub can automatically build images from source code in an external
repository and automatically push the built image to your Docker repositories.
When you set up automated builds (also called autobuilds), you create a list of
branches and tags that you want to build into Docker images. When you push code
to a source code branch (for example in GitHub) for one of those listed image
tags, the push uses a webhook to trigger a new build, which produces a Docker
image. The built image is then pushed to the Docker Hub registry.
> **Note**
>
> You can still use `docker push` to push pre-built images to
repositories with Automated Builds configured.
> Automated builds require a
> [Docker Pro, Team, or Business subscription](../../subscription/index.md).
If you have automated tests configured, these run after building but before
pushing to the registry. You can use these tests to create a continuous
integration workflow where a build that fails its tests doesn't push the built
image. Automated tests don't push images to the registry on their own. [Learn about automated image testing](automated-testing.md).
This page contains information on:
- [Configuring Automated builds](#configure-automated-builds)
- [Advanced Automated build options](#advanced-automated-build-options)
- [Automated builds for teams](#autobuild-for-teams)
Depending on your [subscription](https://www.docker.com/pricing){: target="_blank" rel="noopener" class="_"},
you may get concurrent builds, which means that `N` autobuilds can be run at the
same time. `N` is configured according to your subscription. Once `N+1` builds
are running, any additional builds go into a queue to be run later.
The maximum number of pending builds in the queue is 30 and Docker Hub discards further
requests. The number of concurrent builds for Pro is 5 and
for Team and Business is 15.
![An automated build dashboard](images/index-dashboard.png)
## Configure automated build settings
## Configure Automated builds
You can configure repositories in Docker Hub so that they automatically
build an image each time you push new code to your source provider. If you have
[automated tests](automated-testing.md) configured, the new image is only pushed
when the tests succeed.
You can add builds to existing repositories, or add them when you create a repository.
1. From the **Repositories** section, select a repository to view its details.
2. Select the **Builds** tab.
3. If you are setting up automated builds for the first time, select the code
repository service (GitHub or Bitbucket) where the image's source code is stored.
3. Select either GitHub or Bitbucket to connect where the image's source code is stored.
> Note
>
@ -73,31 +42,32 @@ You can add builds to existing repositories, or add them when you create a repos
4. Select the **source repository** to build the Docker images from.
> Note
> You might need to specify an organization or user (the _namespace_) from
> the source code provider. Once you select a namespace, its source code
> You might need to specify an organization or user from
> the source code provider. Once you select a user, source code
> repositories appear in the **Select repository** dropdown list.
5. Optionally, enable [autotests](automated-testing.md#enable-automated-tests-on-a-repository).
5. Optional: Enable [autotests](automated-testing.md#enable-automated-tests-on-a-repository).
6. Review the default **Build Rules**, and optionally select the
**plus sign** to add and configure more build rules.
6. Review the default **Build Rules**
_Build rules_ control what Docker Hub builds into images from the contents
Build rules control what Docker Hub builds into images from the contents
of the source code repository, and how the resulting images are tagged
within the Docker repository.
A default build rule is set up for you, which you can edit or delete. This
default set builds from the `Branch` in your source code repository called
`master`, and creates a Docker image tagged with `latest`.
default rule sets builds from the `Branch` in your source code repository called
`master` or `main`, and creates a Docker image tagged with `latest`. For more information, see [set up build rules](#set-up-build-rules)
7. For each branch or tag, enable or disable the **Autobuild** toggle.
7. Optional: Select the **plus** icon to add and [configure more build rules](#set-up-build-rules).
8. For each branch or tag, enable or disable the **Autobuild** toggle.
Only branches or tags with autobuild enabled are built, tested, and have
the resulting image pushed to the repository. Branches with autobuild
disabled are built for test purposes (if enabled at the repository
level), but the built Docker image isn't pushed to the repository.
8. For each branch or tag, enable or disable the **Build Caching** toggle.
9. For each branch or tag, enable or disable the **Build Caching** toggle.
[Build caching](../../develop/develop-images/dockerfile_best-practices.md#leverage-build-cache)
can save time if you are building a large image frequently or have
@ -105,20 +75,20 @@ You can add builds to existing repositories, or add them when you create a repos
make sure all of your dependencies are resolved at build time, or if
you have a large layer that's quicker to build locally.
9. Click **Save** to save the settings, or click **Save and build** to save and
10. Select **Save** to save the settings, or select **Save and build** to save and
run an initial test.
> Note
>
> A webhook is automatically added to your source code repository to notify
> Docker Hub on every push. Only pushes to branches that's listed as the
> source for one or more tags trigger a build.
> Docker Hub on every push. Only pushes to branches that are listed as the
> source for one or more tags, trigger a build.
### Set up build rules
By default when you set up automated builds, a basic build rule is created for you.
This default rule watches for changes to the `master` branch in your source code
repository, and builds the `master` branch into a Docker image tagged with
By default when you set up Automated builds, a basic build rule is created for you.
This default rule watches for changes to the `master` or `main` branch in your source code
repository, and builds the `master` or `main` branch into a Docker image tagged with
`latest`.
In the **Build Rules** section, enter one or more sources to build.
@ -130,34 +100,34 @@ For each source:
* Enter the name of the **Source** branch or tag you want to build.
The first time you configure automated builds, a default build rule is set up
The first time you configure Automated builds, a default build rule is set up
for you. This default set builds from the `Branch` in your source code called
`master`, and creates a Docker image tagged with `latest`.
You can also use a regex to select which source branches or tags to build.
To learn more, see
[regexes](index.md#regexes-and-automated-builds).
[regexes](#regexes-and-automated-builds).
* Enter the tag to apply to Docker images built from this source.
If you configured a regex to select the source, you can reference the
capture groups and use its result as part of the tag. To learn more, see
[regexes](index.md#regexes-and-automated-builds).
[regexes](#regexes-and-automated-builds).
* Specify the **Dockerfile location** as a path relative to the root of the source code repository. If the Dockerfile is at the repository root, leave this path set to `/`.
> **Note**
>
> When Docker Hub pulls a branch from a source code repository, it performs a
> shallow clone (only the tip of the specified branch). Refer to
> [Advanced options for Autobuild and Autotest](advanced.md#source-repository--branch-clones)
> shallow clone - only the tip of the specified branch. Refer to
> [Advanced options for Autobuild and Autotest](advanced.md#source-repository-or-branch-clones)
> for more information.
### Environment variables for builds
You can set the values for environment variables used in your build processes
when you configure an automated build. Add your build environment variables by
clicking the plus sign next to the **Build environment variables** section, and
selecting the **plus** icon next to the **Build environment variables** section, and
then entering a variable name and the value.
When you set variable values from the Docker Hub UI, you can use them by the
@ -169,99 +139,29 @@ should remain secret.
>
> The variables set on the build configuration screen are used during
> the build processes only and shouldn't get confused with the environment
> values used by your service (for example to create service links).
## Check your active builds
A summary of a repository's builds appears both on the repository **General**
tab, and in the **Builds** tab. The **Builds** tab also displays a color coded
bar chart of the build queue times and durations. Both views display the
pending, in progress, successful, and failed builds for any tag of the
repository.
![Active builds](images/index-active.png)
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 namespace the build occurred in.
>**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.
![Build report](/docker-hub/images/index-report.png)
## Cancel or retry a build
While a build is in queue or running, a **Cancel** icon appears next to its build
report link on the General tab and on the Builds tab. You can also click the
**Cancel** on the build report page, or from the Timeline tab's logs
display for the build.
![List of builds showing the cancel icon](images/build-cancelicon.png)
## Failing builds
If a build fails, a **Retry** icon appears next to the build report line on the
**General** and **Builds** tabs. The **Build report** page and **Timeline logs** also display a **Retry** button.
![Timeline view showing the retry build button](images/retry-build.png)
> **Note**
>
> If you are viewing the build details for a repository that belongs to an
> Organization, the Cancel and Retry buttons only appear if you have `Read & Write` access to the repository.
Automated builds have a 4-hour execution time limit. If a build reaches this time limit, it's
automatically cancelled, and the build logs display the following message:
```text
2022-11-02T17:42:27Z The build was cancelled or exceeded the maximum execution time.
```
This log message is the same as when you actively cancel a build. To identify
whether a build was automatically cancelled, check the build duration.
## Disable an automated build
Automated builds are enabled per branch or tag, and can be disabled and
re-enabled. You might do this when you want to only build manually for
a while, for example when you are doing major refactoring in your code. When you disable autobuilds doesn't disable [autotests](automated-testing.md).
To disable an automated build:
1. From the **Repositories** page, select a repository, and select the **Builds** tab.
2. Click **Configure automated builds** to edit the repository's build settings.
3. In the **Build Rules** section, locate the branch or tag you no longer want
to automatically build.
4. Click the **autobuild** toggle next to the configuration line. When disabled the toggle is gray.
5. Click **Save** to save your changes.
> values used by your service, for example to create service links.
## Advanced automated build options
At the minimum you need a build rule composed of a source branch (or tag) and
destination Docker tag to set up an automated build. You can also change where
the build looks for the Dockerfile, set a path to the files the build use
(the build context), set up multiple static tags or branches to build from, and
use regular expressions (regexes) to dynamically select source code to build and
create dynamic tags.
At the minimum you need a build rule composed of a source branch, or tag, and a
destination Docker tag to set up an automated build. You can also:
- Change where the build looks for the Dockerfile
- Set a path to the files the build should use (the build context)
- Set up multiple static tags or branches to build from
- Use regular expressions (regexes) to dynamically select source code to build and
create dynamic tags
All of these options are available from the **Build configuration** screen for
each repository. Select **Repositories** from the left navigation, and select the name of the repository you want to edit. Select the **Builds** tab, and click **Configure Automated builds**.
each repository. Select **Repositories** from the left navigation, and select the name of the repository you want to edit. Select the **Builds** tab, and then select **Configure Automated builds**.
### Tag and branch builds
You can configure your automated builds so that pushes to specific branches or tags triggers a build.
1. In the **Build Rules** section, click the plus sign to add more sources to build.
1. In the **Build Rules** section, select the **plus** icon to add more sources to build.
2. Select the **Source type** to build: either a tag or a branch.
2. Select the **Source type** to build either a tag or a branch.
> Note
>
@ -291,7 +191,7 @@ Depending on how you arrange the files in your source code repository, the
files required to build your images may not be at the repository root. If that's
the case, you can specify a path where the build looks for the files.
The _build context_ is the path to the files needed for the build, relative to
The build context is the path to the files needed for the build, relative to
the root of the repository. Enter the path to these files in the **Build context** field. Enter `/` to set the build context as the root of the source code repository.
> **Note**
@ -303,17 +203,16 @@ the root of the repository. Enter the path to these files in the **Build context
You can specify the **Dockerfile location** as a path relative to the build
context. If the Dockerfile is at the root of the build context path, leave the
Dockerfile path set to `/`. (If the build context field is blank, set the path
to the Dockerfile from the root of the source repository.)
Dockerfile path set to `/`. If the build context field is blank, set the path
to the Dockerfile from the root of the source repository.
### Regexes and automated builds
### Regexes and Automated builds
You can specify a regular expression (regex) so that only matching branches or
tags are built. You can also use the results of the regex to create the Docker
tag that's applied to the built image.
You can use up to nine regular expression capture groups
(expressions enclosed in parentheses) to select a source to build, and reference
You can use up to nine regular expression capture groups, or expressions enclosed in parentheses, to select a source to build, and reference
these in the **Docker Tag** field using `{\1}` through `{\9}`.
<!-- Capture groups Not a priority
@ -331,56 +230,20 @@ Docker build system, add the [environment variable](index.md#environment-variabl
`DOCKER_BUILDKIT=0`. Refer to the [BuildKit](../../build/buildkit/index.md)
page for more information on BuildKit.
## Build repositories with linked private submodules
Docker Hub sets up a deploy key in your source code repository that allows it
to clone the repository and build it; however this key only works for a single,
specific code repository. If your source code repository uses private Git
submodules (or requires that you clone other private repositories to build),
Docker Hub cannot access these additional repos, your build cannot complete,
and an error is logged in your build timeline.
To work around this, you can set up your automated build using the `SSH_PRIVATE`
environment variable to override the deployment key and grant Docker Hub's build
system access to the repositories.
> **Note**
>
> If you are using autobuild for teams, use [the process below](index.md#service-users-for-team-autobuilds)
> instead, and configure a service user for your source code provider. You can
> also do this for an individual account to limit Docker Hub's access to your
> source repositories.
1. Generate a SSH keypair that you use for builds only, and add the public key to your source code provider account.
This step is optional, but allows you to revoke the build-only keypair without removing other access.
2. Copy the private half of the keypair to your clipboard.
3. In Docker Hub, navigate to the build page for the repository that has linked private submodules. (If necessary, follow the steps [here](index.md#configure-automated-build-settings) to configure the automated build.)
4. At the bottom of the screen, click the plus sign ( **+** ) next to **Build Environment variables**.
5. Enter `SSH_PRIVATE` as the name for the new environment variable.
6. Paste the private half of the keypair into the **Value** field.
7. Click **Save**, or **Save and Build** to validate that the build now completes.
> **Note**
>
> You must configure your private git submodules using git clone over SSH
> (`git@submodule.tld:some-submodule.git`) rather than HTTPS.
## Autobuild for Teams
When you create an automated build repository in your own account namespace, you
When you create an automated build repository in your own user account, you
can start, cancel, and retry builds, and edit and delete your own repositories.
These same actions are also available for team repositories from Docker Hub if
you are a member of the Organization's `Owners` team. If you are a member of a
you are a member of an organization's `Owners` team. If you are a member of a
team with `write` permissions you can start, cancel, and retry builds in your
team's repositories, but you cannot edit the team repository settings or delete
the team repositories. If your user account has `read` permission, or if you're
a member of a team with `read` permission, you can view the build configuration
including any testing settings.
| Action/Permission | read | write | admin | owner |
| Action/Permission | Read | Write | Admin | Owner |
| --------------------- | ---- | ----- | ----- | ----- |
| view build details | x | x | x | x |
| start, cancel, retry | | x | x | x |
@ -389,14 +252,16 @@ including any testing settings.
### Service users for team autobuilds
> **Note**: Only members of the `Owners` team can set up automated builds for teams.
> **Note**
>
> Only members of the `Owners` team can set up Automated builds for teams.
When you set up automated builds for teams, you grant Docker Hub access to
When you set up Automated builds for teams, you grant Docker Hub access to
your source code repositories using OAuth tied to a specific user account. This
means that Docker Hub has access to everything that the linked source provider
account can access.
For organizations and teams, it's recommended you create a dedicated service account (or "machine user") to grant access to the source provider. This ensures that no
For organizations and teams, it's recommended you create a dedicated service account to grant access to the source provider. This ensures that no
builds break as individual users' access permissions change, and that an
individual user's personal projects aren't exposed to an entire organization.
@ -407,7 +272,7 @@ set of repositories required for a specific build.
If you are building repositories with linked private submodules (private
dependencies), you also need to add an override `SSH_PRIVATE` environment
variable to automated builds associated with the account.
variable to automated builds associated with the account. For more information, see [Troubleshoot](troubleshoot.md#build-repositories-with-linked-private-submodules)
1. Create a service user account on your source provider, and generate SSH keys for it.
2. Create a "build" team in your organization.
@ -419,27 +284,17 @@ variable to automated builds associated with the account.
4. Add the service user to the "build" team on the source provider.
5. Log in to Docker Hub as a member of the `Owners` team, switch to the organization, and follow the instructions to [link to source code repository](link-source.md) using the service account.
5. Sign in to Docker Hub as a member of the `Owners` team, switch to the organization, and follow the instructions to [link to source code repository](link-source.md) using the service account.
> **Note**: You may need to log out of your individual account on the source code provider to create the link to the service account.
> **Note**
>
> You may need to log out of your individual account on the source code provider to create the link to the service account.
6. Optionally, use the SSH keys you generated to set up any builds with private submodules, using the service account and [the instructions above](index.md#build-repositories-with-linked-private-submodules).
6. Optional: Use the SSH keys you generated to set up any builds with private submodules, using the service account and [the instructions above](troubleshoot.md#build-repositories-with-linked-private-submodules).
## What's Next?
### Customize your build process
Additional advanced options are available for customizing your automated builds,
including utility environment variables, hooks, and build phase overrides. To
learn more see [Advanced options for Autobuild and Autotest](advanced.md).
### Add automated tests
To test your code before the image is pushed, you can use
Docker Hub's [Autotest](automated-testing.md) feature which
integrates seamlessly with autobuild and autoredeploy.
> **Note**
>
> While the Autotest feature builds an image for testing purposes, it
> doesn't push the resulting image to Docker Hub.
- [Customize your build process](advanced.md) with environment variables, hooks, and more
- [Add automated tests](automated-testing.md)
- [Manage your builds](manage-builds.md)
- [Troubleshoot](troubleshoot.md)

144
docker-hub/builds/link-source.md
View File

@ -1,91 +1,53 @@
---
description: Link to GitHub and BitBucket
keywords: Docker, docker, registry, accounts, plans, Dockerfile, Docker Hub, trusted, builds, trusted builds, automated builds, GitHub
title: Configure automated builds from GitHub and BitBucket
title: Configure Automated builds from GitHub and BitBucket
redirect_from:
- /docker-hub/github/
- /docker-hub/bitbucket/
- /docker-cloud/builds/link-source/
---
{% include upgrade-cta.html
body="The Automated Builds feature is available for Docker Pro, Team, and Business users. Upgrade now to automatically build and push your images. If you are using automated builds for an open-source project, you can join our [Open Source Community](https://www.docker.com/community/open-source/application){: target='_blank' rel='noopener' class='_'} program to learn how Docker can support your project on Docker Hub."
header-text="This feature requires a Docker subscription"
target-url="https://www.docker.com/pricing?utm_source=docker&utm_medium=webreferral&utm_campaign=docs_driven_upgrade_auto_builds"
%}
> **Note**
>
> Automated builds require a
> [Docker Pro, Team, or Business subscription](../../subscription/index.md).
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
repositories. You can configure this link for user accounts or
organizations.
> **Note**: If you are linking a source code provider to create autobuilds for a team, follow the instructions to [create a service account](index.md#service-users-for-team-autobuilds) for the team before linking the account as described below.
If you are linking a source code provider to create autobuilds for a team, follow the instructions to [create a service account](index.md#service-users-for-team-autobuilds) for the team before linking the account as described below.
## Link to a GitHub user account
1. Log in to Docker Hub using your Docker ID.
1. Sign in to Docker Hub.
2. Click **Account Settings** in the top-right dropdown navigation, then open **Linked Accounts**.
2. Select **Account Settings** in the top-right dropdown navigation, then select the **Linked Accounts** tab.
3. Click **Connect** for the source provider you want to link.
3. Select **Link provider** for the source provider you want to link.
![Linking source providers](images/linked-accounts.png)
> **Note**: If you want to unlink your current GitHub account and relink to a new GitHub account, make sure to completely logout of [GitHub] (https://github.com/){: target="_blank" rel="noopener"
class="_"} before linking via Docker Hub.
If you want to unlink your current GitHub account and relink to a new GitHub account, make sure to completely logout of [GitHub](https://github.com/){: target="_blank" rel="noopener"
class="_"} before linking via Docker Hub.
4. Review the settings for the **Docker Hub Builder** OAuth application.
![Granting access to GitHub account](images/authorize-builder.png)
![Granting access to GitHub account](images/authorize-builder.png){:width="750px"}
>**Note**: If you are the owner of any GitHub organizations, you might see
>**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
individually edit an organization's third-party access settings to grant or
revoke Docker Hub's access. See
[Grant access to a GitHub organization](link-source.md#grant-access-to-a-github-organization)
to learn more.
5. Click **Authorize docker** to save the link.
5. Select **Authorize docker** to save the link.
## Link to a Bitbucket user account
1. Log in to Docker Hub using your Docker ID.
2. Click **Account Settings** in the top-right dropdown navigation, then open
the **Linked Accounts** section.
3. Click **Connect** for the source provider you want to link.
![Linking Bitbucket](images/linked-accounts.png)
4. If necessary, log in to Bitbucket.
5. On the page that appears, click **Grant access**.
### Unlink a GitHub user account
To revoke Docker Hub's access to your GitHub account, you must unlink it both
from Docker Hub, *and* from your GitHub account.
1. Click **Account Settings** in the top-right dropdown navigation, then open
the **Linked Accounts** section.
2. Click the plug icon next to the source provider you want to remove.
3. Go to your GitHub account's **Settings** page.
4. Click **Applications** in the left navigation bar.
5. Click the `...` menu to the right of the Docker Hub Builder application and select **Revoke**.
> **Note**: Each repository that is configured as an automated build source
contains a webhook that notifies Docker Hub of changes in the repository.
This webhook is not automatically removed when you revoke access to a source
code provider.
## Grant access to a GitHub organization
### Grant access to a GitHub organization
If you are the owner of a GitHub organization, you can grant or revoke Docker
Hub's access to the organization's repositories. Depending on the GitHub
@ -94,11 +56,9 @@ organization's settings, you may need to be an organization owner.
If the organization has not had specific access granted or revoked before, you
can often grant access at the same time as you link your user account. In this
case, a **Grant access** button appears next to the organization name in the
link accounts screen, as shown below. If this button does not appear, you must
link accounts screen, as shown below. If this button does not appear, you must
manually grant the application's access.
![Granting access to GitHub organization](images/link-source-github-org-lite.png)
To manually grant Docker Hub access to a GitHub organization:
1. Link your user account using the instructions above.
@ -106,19 +66,16 @@ To manually grant Docker Hub access to a GitHub organization:
2. From your GitHub Account settings, locate the **Organization settings**
section at the lower left.
3. Click the organization you want to give Docker Hub access to.
3. Select the organization you want to give Docker Hub access to.
4. From the Organization Profile menu, click **Third-party access**.
4. Select **Third-party access**.
The page displays a list of third party applications and their access
status.
5. Click the pencil icon next to Docker Hub Builder.
6. Click **Grant access** next to the organization.
![Granting access to GitHub organization manually](images/link-source-github-org.png)
5. Select the pencil icon next to **Docker Hub Builder**.
6. Select **Grant access** next to the organization.
### Revoke access to a GitHub organization
@ -133,30 +90,65 @@ To revoke Docker Hub's access to an organization's GitHub repositories:
4. Click the pencil icon next to Docker Hub Builder.
5. On the next page, click **Deny access**.
5. On the next page, select **Deny access**.
### Unlink a GitHub user account
To revoke Docker Hub's access to your GitHub account, you must unlink it both
from Docker Hub, and from your GitHub account.
1. Select **Account Settings** in the top-right dropdown navigation, then open
the **Linked Accounts** section.
2. Select the plug icon next to the source provider you want to remove.
3. Go to your GitHub account's **Settings** page.
4. Select **Applications** in the left navigation bar.
5. Select the `...` menu to the right of the Docker Hub Builder application and select **Revoke**.
> **Note**
>
> Each repository that is configured as an automated build source
contains a webhook that notifies Docker Hub of changes in the repository.
This webhook is not automatically removed when you revoke access to a source
code provider.
## Link to a Bitbucket user account
1. Sign in to Docker Hub using your Docker ID.
2. Select **Account Settings** in the top-right dropdown navigation, then select the **Linked Accounts** tab.
3. Select **Link provider** for the source provider you want to link.
4. If necessary, sign in to Bitbucket.
5. On the page that appears, select **Grant access**.
### Unlink a Bitbucket user account
To permanently revoke Docker Hub's access to your Bitbucket account, you must
unlink it both from Docker Hub, *and* from your Bitbucket account.
unlink it both from Docker Hub, and from your Bitbucket account.
1. Log in to Docker Hub using your Docker ID.
1. Sign in to Docker Hub.
2. Click **Account Settings** in the top-right dropdown navigation, then open
2. Select **Account Settings** in the top-right dropdown navigation, then open
the **Linked Accounts** section.
3. Click the plug icon next to the source provider you want to remove.
3. Select the **Plug** icon next to the source provider you want to remove.
4. Go to your Bitbucket account and click the user menu icon in the top-right corner.
4. Go to your Bitbucket account and navigate to **Bitbucket settings**.
5. Click **Bitbucket settings**.
5. On the page that appears, select **OAuth**.
6. On the page that appears, click **OAuth**.
6. Select **Revoke** next to the Docker Hub line.
7. Click **Revoke** next to the Docker Hub line.
> **Note**: Each repository that is configured as an automated build source
> **Note**
>
> Each repository that is configured as an automated build source
contains a webhook that notifies Docker Hub of changes in the repository. This
webhook is not automatically removed when you revoke access to a source code
provider.

59
docker-hub/builds/manage-builds.md Normal file
View File

@ -0,0 +1,59 @@
---
title: Manage autobuilds
description: How to manage autobuilds in Docker Hub
keywords: autobuilds, automated, docker hub, registry
---
> **Note**
>
> Automated builds require a
> [Docker Pro, Team, or Business subscription](../../subscription/index.md).
## Cancel or retry a build
While a build is in queue or running, a **Cancel** icon appears next to its build
report link on the **General** tab and on the **Builds** tab. You can also select
**Cancel** on the **Build report** page, or from the **Timeline** tab's logs
display for the build.
![List of builds showing the cancel icon](images/build-cancelicon.png)
## Check your active builds
A summary of a repository's builds appears both on the repository **General**
tab, and in the **Builds** tab. The **Builds** tab also displays a color coded
bar chart of the build queue times and durations. Both views display the
pending, in progress, successful, and failed builds for any tag of the
repository.
![Active builds](images/index-active.png)
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**
>
> 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)
## Disable an automated build
Automated builds are enabled per branch or tag, and can be disabled and
re-enabled. You might do this when you want to only build manually for
a while, for example when you are doing major refactoring in your code. Disabling autobuilds doesn't disable [autotests](automated-testing.md).
To disable an automated build:
1. From the **Repositories** page, select a repository, and select the **Builds** tab.
2. Select **Configure automated builds** to edit the repository's build settings.
3. In the **Build Rules** section, locate the branch or tag you no longer want
to automatically build.
4. Select the **Autobuild** toggle next to the configuration line. When disabled the toggle is gray.
5. Select **Save**.

69
docker-hub/builds/troubleshoot.md Normal file
View File

@ -0,0 +1,69 @@
---
title: Troubleshoot your builds
description: How to troubleshoot Automated builds
keywords: docker hub, troubleshoot, automated builds, autobuilds
---
> **Note**
>
> Automated builds require a
> [Docker Pro, Team, or Business subscription](../../subscription/index.md).
## Failing builds
If a build fails, a **Retry** icon appears next to the build report line on the
**General** and **Builds** tabs. The **Build report** page and **Timeline logs** also display a **Retry** button.
![Timeline view showing the retry build button](images/retry-build.png)
> **Note**
>
> If you are viewing the build details for a repository that belongs to an
> organization, the **Cancel** and **Retry** buttons only appear if you have `Read & Write` access to the repository.
Automated builds have a 4-hour execution time limit. If a build reaches this time limit, it's
automatically cancelled, and the build logs display the following message:
```text
2022-11-02T17:42:27Z The build was cancelled or exceeded the maximum execution time.
```
This log message is the same as when you actively cancel a build. To identify
whether a build was automatically cancelled, check the build duration.
## Build repositories with linked private submodules
Docker Hub sets up a deploy key in your source code repository that allows it
to clone the repository and build it. This key only works for a single,
specific code repository. If your source code repository uses private Git
submodules, or requires that you clone other private repositories to build,
Docker Hub cannot access these additional repositories, your build cannot complete,
and an error is logged in your build timeline.
To work around this, you can set up your automated build using the `SSH_PRIVATE`
environment variable to override the deployment key and grant Docker Hub's build
system access to the repositories.
> **Note**
>
> If you are using autobuild for teams, use the process below
> instead, and configure a service user for your source code provider. You can
> also do this for an individual account to limit Docker Hub's access to your
> source repositories.
1. Generate a SSH keypair that you use for builds only, and add the public key to your source code provider account.
This step is optional, but allows you to revoke the build-only keypair without removing other access.
2. Copy the private half of the keypair to your clipboard.
3. In Docker Hub, navigate to the build page for the repository that has linked private submodules. (If necessary, follow the steps [here](index.md#configure-automated-builds) to configure the automated build.)
4. At the bottom of the screen, select the **plus** icon next to **Build Environment variables**.
5. Enter `SSH_PRIVATE` as the name for the new environment variable.
6. Paste the private half of the keypair into the **Value** field.
7. Select **Save**, or **Save and Build** to validate that the build now completes.
> **Note**
>
> You must configure your private git submodules using git clone over SSH
> (`git@submodule.tld:some-submodule.git`) rather than HTTPS.

5
docker-hub/company-owner.md
View File

@ -4,6 +4,11 @@ keywords: company, owners
title: Manage company owners
---
> **Note**
>
> The company layer is in [early access](../release-lifecycle.md#early-access-ea)
> and requires a Docker Team or Business subscription.
As a company owner, you can configure [Single Sign-on (SSO)](../single-sign-on/configure/index.md) and [System for Cross-domain Identity Management (SCIM)](../docker-hub/scim.md) for all organizations under the company. This is only visible if your organization has a Docker Business subscription. If you want to upgrade your subscription to include the organization under the company, see [upgrade your subscription](../subscription/upgrade.md).
## Add a company owner

58
docker-hub/convert-account.md
View File

@ -4,60 +4,44 @@ title: Convert an account into an organization
keywords: docker hub, hub, organization
---
You can convert an existing user account to an organization. You might want to do this if you need multiple users to access your account and the repositories that it’s connected to. Converting it to an organization gives you better control over permissions for these users through teams.
You can convert an existing user account to an organization. This is useful if you need multiple users to access your account and the repositories that it’s connected to. Converting it to an organization gives you better control over permissions for these users through [teams](manage-a-team.md).
> **Note:**
When you convert a user account to an organization, the account
is migrated to a Team plan and charged $35 per month for 5 seats. For more information,
see [Docker Pricing](https://www.docker.com/pricing){: target="_blank" rel="noopener" class="_"}.
> **Important**
>
> Once you convert your account to an organization, you can’t revert it to a user account, so make sure you really want to convert the user account.
> Once you convert your account to an organization, you can’t revert it to a user account.
{: .important}
## Prerequisites
Before you convert a user account to an organization, ensure that you have completed the following steps:
Before you convert a user account to an organization, ensure that you meet the following requirements:
1. The user account that you wish to convert must not be a member of a company or any teams or organizations. You must remove the account from all teams, organizations, or the company.
- The user account that you wish to convert must not be a member of a company or any teams or organizations. You must remove the account from all teams, organizations, or the company.
Go to **Organizations**, select an organization from the list, and then click the Leave organization arrow next to your username in the members list.
To do this:
1. Navigate to **Organizations** and then select the organization(s) you need to leave.
2. Find your username in the **Members** tab.
3. Select the **More options** menu and then select **Leave organization**.
If the user account is the sole owner of any organization or company, add someone to the "owners" team and then remove yourself from the organization or company.
2. You must have a separate Docker ID ready to assign it as the owner of the organization during conversion.
- You must have a separate Docker ID ready to assign it as the owner of the organization during conversion.
If you wish to convert your user account into an organization account and you do not have any other user accounts, you need to create a new user account to assign it as the owner of the new organization. This user account then becomes the first member of the "owners" team and has full administrative access to configure and manage the organization. You can add more users into the "owners" team after the conversion.
## Convert a Community account into an organization
## Convert an account into an organization
1. Ensure you have removed your user account from any company or teams or organizations. Also make sure that you have a new Docker ID before you convert an account. See the [Prerequisites](#prerequisites) section for details.
2. Click on your account name in the top navigation, then go to your **Account Settings**.
2. In the top-right of Docker Hub, select your account name and then from the dropdown menu, select **Account Settings**.
3. Under the **Convert Account** tab, click **Convert to Organization**.
3. From the **Convert Account** tab, select **Convert to Organization**.
4. Carefully review the warning displayed about converting a user account. This cannot be undone and will have considerable implications for your assets and the account.
4. Review the warning displayed about converting a user account. This action cannot be undone and has considerable implications for your assets and the account.
5. As part of the conversion, you must enter a **Docker ID** to set an organization owner. This is the user account that will manage the organization, and the only way to access the organization settings after conversion. You cannot use the same Docker ID as the account you are trying to convert.
5. Enter a **Docker ID** to set an organization owner. This is the user account that will manage the organization, and the only way to access the organization settings after conversion. You cannot use the same Docker ID as the account you are trying to convert.
6. Click **Convert** to confirm. The new owner will receive a notification email. Use that owner account to log into your new organization.
Your Community account has now been converted to an organization.
## Convert a Docker Pro tier into an organization
>**Note:**
>
> When you convert a Docker Pro subscription to an organization, the account
will be migrated to a Team plan and will be charged $35 per month for 5 seats. For more information,
see [Docker Pricing](https://www.docker.com/pricing){: target="_blank" rel="noopener" class="_"}.
1. Ensure you have removed your user account from any company or teams or organizations. Also make sure that you have a new Docker ID before you convert an account. See the [Prerequisites](#prerequisites) section for details.
2. Click on your account name in the top navigation bar, then go to your **Account Settings**.
3. Under the **Convert Account** tab, click **Convert to Organization**.
4. Carefully review the warning displayed about converting a user account. This cannot be undone and will have considerable implications for your assets and the account.
5. As part of the conversion, you must enter a **Docker ID** to set an organization owner. This is the user account that will manage the organization, and the only way to access the organization settings after conversion. You cannot use the same Docker ID as the account you are trying to convert.
6. Click **Convert** to confirm. The new owner will receive a notification email. Use that owner account to log into your new organization.
Your Pro user account has now been converted to an organization.
6. Select **Convert and Purchase** to confirm. The new owner receives a notification email. Use that owner account to log in to your new organization.

5
docker-hub/creating-companies.md
View File

@ -4,6 +4,11 @@ keywords: company, multiple organizations, manage companies
title: Overview
---
> **Note**
>
> The company layer is in [early access](../release-lifecycle.md#early-access-ea)
> and requires a Docker Team or Business subscription.
A company provides a single point of visibility across multiple organizations. Docker introduced this new view to simplify the management of Docker organizations and settings. It's available to Docker Business subscribers.
The following diagram depicts the set up of a company and how it relates to associated organizations.

58
docker-hub/deactivate-account.md
View File

@ -4,47 +4,65 @@ description: Learn how to deactivate a Docker Hub account or an organization
keywords: Docker Hub, delete, deactivate, account, organization
---
Your Docker Hub account or organization may also be linked to other Docker products and services, so deactivating it will also disable access to those products and services.
You can deactivate an account at any time.
## Deactivating an account
>**Warning**
>
> If your Docker Hub account or organization is linked to other Docker products and services, deactivating your account also removes access to those products and services.
{: .warning}
Before deactivating your Docker Hub account, please complete the following:
## Deactivate a user account
1. Download any images and tags you want to keep:
`docker pull -a <image>:<tag>`.
### Prerequisites
2. If you belong to any organizations, remove your account from all of them.
Before deactivating your Docker Hub account, ensure that you meet the following requirements:
3. If you are the sole owner of an organization, either add someone to the **owners** team 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.
- You must not be a member of a company or any teams or organizations. You must remove the account from all teams, organizations, or the company.
4. If you have an active subscription, downgrade it to the **Docker Personal** subscription.
To do this:
1. Navigate to **Organizations** and then select the organization(s) you need to leave.
2. Find your username in the **Members** tab.
3. Select the **More options** menu and then select **Leave organization**.
In Docker Hub, navigate to **_Your Account_** > **Account Settings** > **Billing**.
- If you are the sole owner of an organization, either add someone to [the **owners** team](manage-a-team.md#the-owners-team) 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.
5. Unlink your [Github and Bitbucket accounts](../docker-hub/builds/link-source.md#unlink-a-github-user-account).
- If you have an active subscription, [downgrade it to a Docker Personal subscription](../subscription/downgrade.md).
Once you have completed all the steps above, you may deactivate your account. On Docker Hub, go to **_Your Account_** > **Accounts Settings** > **Deactivate Account**.
- Download any images and tags you want to keep. Use `docker pull -a <image>:<tag>`.
> This cannot be undone! Be sure you've gathered all the data you need from your account before deactivating it.
- Unlink your [Github and Bitbucket accounts](../docker-hub/builds/link-source.md#unlink-a-github-user-account).
### Deactivate
Once you have completed all the steps above, you can deactivate your account.
1. Select your account name in the top-right of Docker Hub and from the dropdown menu, select **Account Settings**.
2. From the **Deactivate Account** tab, select **Deactivate account**.
> This cannot be undone. Be sure you've gathered all the data you need from your account before deactivating it.
{: .warning }
## Deactivating an organization
## Deactivate an organization
Before deactivating an organization, please complete the following:
1. Download any images and tags you want to keep:
- Download any images and tags you want to keep:
`docker pull -a <image>:<tag>`.
2. If you have an active subscription, downgrade it to the **Docker Free Team** subscription:
- If you have an active subscription, [downgrade it to a **Docker Free Team** subscription](../subscription/downgrade.md).
In Docker Hub, navigate to **Organizations** > **_Your Organization_** > **Billing**.
- Remove all other members, including those in the **Owners** team, within the organization.
3. Remove all other members, including those in the **Owners** team, within the organization.
- Unlink your [Github and Bitbucket accounts](../docker-hub/builds/link-source.md#unlink-a-github-user-account).
4. Unlink your [Github and Bitbucket accounts](../docker-hub/builds/link-source.md#unlink-a-github-user-account).
### Deactivate
Once you have completed all the steps above, you may deactivate your organization. On Docker Hub, go to **Organizations** > **_Your Organization_** > **Settings** > **Deactivate Org**.
Once you have completed all the steps above, you can deactivate your organization.
> This cannot be undone! Be sure you've gathered all the data you need from your organization before deactivating it.
1. On Docker Hub, select **Organizations**.
2. Choose the organization you want to deactivate.
3. In **Settings**, select the **Deactivate Org** tab and then **Deactivate organization**.
> This cannot be undone. Be sure you've gathered all the data you need from your organization before deactivating it.
{: .warning }

45
docker-hub/download-rate-limit.md
View File

@ -6,12 +6,15 @@ title: Download rate limit
## What's the download rate limit on Docker Hub
Docker Hub limits the number of Docker image downloads ("pulls")
based on the account type of the user pulling the image. Pull rates limits are based on individual IP address. For anonymous users, the rate limit is set to 100 pulls per 6 hours per IP address. For [authenticated](#how-do-i-authenticate-pull-requests) users, it's 200 pulls per 6 hour period. Users with a paid [Docker subscription](https://www.docker.com/pricing){: target="_blank" rel="noopener" class="_"} get up to 5000 pulls per day. If you require a higher number of pulls, you can also purchase an [Enhanced Service Account add-on](service-accounts.md#enhanced-service-account-add-on-pricing).
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.
Some images are unlimited through our [Open Source](https://www.docker.com/blog/expanded-support-for-open-source-software-projects/){: target="_blank" rel="noopener" class="_"} and [Publisher](https://www.docker.com/partners/programs){: target="_blank" rel="noopener" class="_"} programs.
For anonymous users, the rate limit is set to 100 pulls per 6 hours per IP address.
For [authenticated](#how-do-i-authenticate-pull-requests) users, it's 200 pulls per 6 hour period.
Users with a paid [Docker subscription](https://www.docker.com/pricing){: target="_blank" rel="noopener" class="_"} get up to 5000 pulls per day.
See [Docker Pricing](https://www.docker.com/pricing){: target="_blank" rel="noopener" class="_"} and [Resource Consumption Updates FAQ](https://www.docker.com/pricing/resource-consumption-updates){: target="_blank" rel="noopener" class="_"} for details.
If you require a higher number of pulls, you can also purchase an [Enhanced Service Account add-on](service-accounts.md#enhanced-service-account-add-on-pricing).
Some images are unlimited through our [Open Source](https://www.docker.com/blog/expanded-support-for-open-source-software-projects/){: target="_blank" rel="noopener" class="_"} and [Publisher](https://www.docker.com/partners/programs){: target="_blank" rel="noopener" class="_"} programs. See [Docker Pricing](https://www.docker.com/pricing){: target="_blank" rel="noopener" class="_"} and [Resource Consumption Updates FAQ](https://www.docker.com/pricing/resource-consumption-updates){: target="_blank" rel="noopener" class="_"} for details.
## Definition of limits
@ -34,17 +37,17 @@ manifest requests.
## How do I know my pull requests are being limited
When you issue a pull request and you are over the limit for your account type, Docker Hub will return a `429` response code with the following body when the manifest is requested:
When you issue a pull request and you are over the limit, Docker Hub returns a `429` response code with the following body when the manifest is requested:
```
You have reached your pull rate limit. You may increase the limit by authenticating and upgrading: https://www.docker.com/increase-rate-limits
```
You will see this error message in the Docker CLI or in the Docker Engine logs.
This error message appears in the Docker CLI or in the Docker Engine logs.
## How can I check my current rate
Valid manifest API requests to Hub will usually include the following rate limit headers in the response:
Valid API requests to Hub usually include the following rate limit headers in the response:
```
ratelimit-limit
@ -52,15 +55,19 @@ ratelimit-remaining
docker-ratelimit-source
```
These headers will be returned on both GET and HEAD requests. Note that using GET emulates a real pull and will count towards the limit; using HEAD won't, so we will use it in this example. To check your limits, you will need `curl`, `grep`, and `jq` installed.
These headers are returned on both GET and HEAD requests.
To get a token anonymously (if you are pulling anonymously):
>**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.
To get a token anonymously, if you are pulling anonymously:
```console
$ TOKEN=$(curl "https://auth.docker.io/token?service=registry.docker.io&scope=repository:ratelimitpreview/test:pull" | jq -r .token)
```
To get a token with a user account (if you are authenticating your pulls) - don't forget to insert your username and password in the following command:
To get a token with a user account, if you are authenticated (insert your username and password in the following command):
```console
$ TOKEN=$(curl --user 'username:password' "https://auth.docker.io/token?service=registry.docker.io&scope=repository:ratelimitpreview/test:pull" | jq -r .token)
@ -72,7 +79,7 @@ Then to get the headers showing your limits, run the following:
$ curl --head -H "Authorization: Bearer $TOKEN" https://registry-1.docker.io/v2/ratelimitpreview/test/manifests/latest
```
Which should return headers including these:
Which should return the following headers:
```http
ratelimit-limit: 100;w=21600
@ -80,13 +87,11 @@ ratelimit-remaining: 76;w=21600
docker-ratelimit-source: 192.0.2.1
```
This means my limit is 100 pulls per 21600 seconds (6 hours), and I have 76 pulls remaining.
> Remember that these headers are best-effort and there will be small variations.
In the example above, the pull limit is 100 pulls per 21600 seconds (6 hours), and there are 76 pulls remaining.
### I don't see any RateLimit headers
This 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.
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.
## I'm being limited to a lower rate even though I have a paid Docker subscription
@ -96,13 +101,13 @@ A Pro, Team, or a Business tier doesn't increase limits on your images for other
## How do I authenticate pull requests
The following section contains information on how to log into on Docker Hub to authenticate pull requests.
The following section contains information on how to sign in to Docker Hub to authenticate pull requests.
### Docker Desktop
If you are using Docker Desktop, you can log into Docker Hub from the Docker Desktop menu.
If you are using Docker Desktop, you can sign in to Docker Hub from the Docker Desktop menu.
Click **Sign in / Create Docker ID** from the Docker Desktop menu and follow the on-screen instructions to complete the sign-in process.
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
@ -140,13 +145,13 @@ If you are using any third-party platforms, follow your provider’s instruction
Docker Hub also has an overall rate limit to protect the application
and infrastructure. This limit applies to all requests to Hub
properties including web pages, APIs, image pulls, etc. The limit is
properties including web pages, APIs, 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 equally
regardless of account level.
You can differentiate between these limits by looking at the error
code. The "overall limit" will return a simple `429 Too Many Requests`
code. The "overall limit" returns a simple `429 Too Many Requests`
response. The pull limit returns a longer error message that
includes a link to this page.

55
docker-hub/dsos-program.md Normal file
View File

@ -0,0 +1,55 @@
---
description: Docker-Sponsored Open Source Program
title: Docker-Sponsored Open Source Program
keywords: docker hub, hub, insights, analytics, open source, Docker sponsored, program
---
The Docker-Sponsored Open Source Program provides several features and benefits to non-commercial open source developers.
The program grants the following perks to eligible projects:
- Verified Docker-Sponsored Open Source badge
- Insights and analytics
- Vulnerability scanning
- Removal of rate limiting for developers
- Improved discoverability on Docker Hub
These benefits are valid for one year and can be renewed if your project still meets the program requirements. Program members, and all users pulling public images from your project namespace get access to unlimited pulls and unlimited egress.
## Verified Docker-Sponsored Open Source badge
Docker verifies that developers can trust images with this badge as an active open source project.
![Fluent org with a Docker-Sponsored Open Source badge](images/sponsored-badge.png)
## Insights and analytics
The [insights and analytics](/docker-hub/publish/insights-analytics){:
target="blank" rel="noopener" class=""} service provides usage metrics for how
the community uses your Docker images, and grants you insight into your user's
behavior.
![The insights and analytics tab on the Docker Hub website](./publish/images/insights-and-analytics-tab.png)
Select the time span you want to view analytics data, and export the data in
either a summary or raw format. The summary format shows you image pulls per
tag, and the raw format lists information about every image pull for the
selected time span. Data points include tag, type of pull, user geolocation,
client tool (user agent), and more.
## Vulnerability scanning
Automatic vulnerability scanning using [Docker Scout](/scout/) for images published to Docker Hub.
Scanning images ensures that the published content is secure, and underlines to
developers that they can trust it. You can enable scanning on a per-repository
basis, refer to [vulnerability scanning](/docker-hub/vulnerability-scanning/){:
target="blank" rel="noopener" class=""} for more information about how to use
it.
## Who's eligible for the Docker-Sponsored Open Source program?
To qualify for the program, your project namespace must be shared in public repositories, meet [the Open Source Initiative definition](https://opensource.org/docs/osd), and be in active development with no pathway to commercialization.
Find out more by heading to the
[Docker-Sponsored Open Source Program](https://www.docker.com/community/open-source/application/#){:target="_blank"
rel="noopener" class="_"} application page.

24
docker-hub/group-mapping.md Normal file
View File

@ -0,0 +1,24 @@
---
description: Group mapping in Docker Hub
keywords: Group Mapping, SCIM, Docker Hub
title: Group Mapping
---
With directory group-to-team provisioning from your IdP, user updates will automatically sync with your Docker organizations and teams.
To correctly assign your users to Docker teams, you must create groups in your IDP following the naming pattern `organization:team`. For example, if you want to manage provisioning for the team "developers” in Docker, and your organization name is “moby,” you must create a group in your IdP with the name “moby:developers”.
Once you enable group mappings in your connection, users assigned to that group in your IdP will automatically be added to the team “developers” in Docker.
>**Tip**
>
>Use the same names for the Docker teams as your group names in the IdP to prevent further configuration. When you sync groups, a group is created if it doesn’t already exist.
{: .tip}
To take advantage of group mapping, make sure you have [enabled SCIM](scim.md) and then follow the instructions provided by your IdP:
- [Okta](https://help.okta.com/en-us/Content/Topics/users-groups-profiles/usgp-enable-group-push.htm){: target="_blank" rel="noopener" class="_" }
- [Azure AD](https://learn.microsoft.com/en-us/azure/active-directory/app-provisioning/customize-application-attributes){: target="_blank" rel="noopener" class="_" }
- [OneLogin](https://developers.onelogin.com/scim/create-app){: target="_blank" rel="noopener" class="_" }
Once complete, a user who signs in to Docker through SSO is automatically added to the organizations and teams mapped in the IdP.

56
docker-hub/image-access-management.md
View File

@ -4,26 +4,20 @@ keywords: image, access, management
title: Image Access Management
---
Image Access Management is a new feature that is a part of the Docker Business subscription. This feature allows Organization owners to control which types of images (Docker Official Images, Docker Verified Publisher Images, Community images) their developers can pull from Docker Hub.
>Note
>
>Image Access Management is available to [Docker Business](../subscription/details.md) customers only.
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 could 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.
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.
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.
## Configure Image Access Management permissions
The following video walks you through the process of configuring Image Access Management permissions.
<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/phFp0iqzwRQ" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
### Detailed instructions
To configure Image Access Management permissions, perform the following steps:
1. Log into your [Docker Hub](https://hub.docker.com){: target="_blank" rel="noopener" class="_"} account as an organization administrator.
2. Select an organization, and navigate to the **Settings** tab on the **Organizations** page and click Org Permissions.
![Image Access Management](images/image-access-management.png){:width="700px"}
3. Enable Image Access Management to set the permissions for the following categories of images you can manage:
1. Sign into your [Docker Hub](https://hub.docker.com){: target="_blank" rel="noopener" class="_"} account as an organization administrator.
2. Select an organization, and navigate to the **Settings** tab
3. From the **Organizations** page select **Org Permissions**.
4. Enable Image Access Management to set the permissions for the following categories of images you can manage:
- **Organization Images**: When Image Access Management is enabled, images from your organization are always allowed. These images can be public or private created by members within your organization.
- **Docker Official Images**: A curated set of Docker repositories hosted on Hub. They provide OS repositories, best practices for Dockerfiles, drop-in solutions, and applies security updates on time.
- **Docker Verified Publisher Images**: published by Docker partners that are part of the Verified Publisher program and are qualified to be included in the developer secure supply chain. You can set permissions to **Allowed** or **Restricted**.
@ -31,32 +25,14 @@ To configure Image Access Management permissions, perform the following steps:
> **Note**
>
> Image Access Management is set to Disabled by default. However, member(s) of the `owners` Team in your Organization have access to all images regardless of the settings.
> Image Access Management is turned off by default. However, members of the `owners` team in your organization have access to all images regardless of the settings.
4. Select the category restrictions for your images by clicking **Allowed**.
5. Once the restrictions are applied, your members can view the Org permissions page in a read-only format.
## Enforce authentication
To ensure that each org member uses images in a safe and secure environment, you
can perform the following steps below to enforce sign-in under your
organization. To do this:
1. Download the latest version of Docker Desktop, and then
2. Create a `registry.json` file.
Download Docker Desktop 4.0 or a later release.
- [Download and install for Windows](/desktop/install/windows-install)
- [Download and install for Mac](/desktop/install/mac-install/)
- [Download and install for Linux](/desktop/install/linux-install)
{% include configure-registry-json.md %}
5. Select the category restrictions for your images by selecting **Allowed**.
Once the restrictions are applied, your members can view the organization permissions page in a read-only format.
6. Optional: To ensure that each organization member uses images in a safe and secure environment, [enfore sign-in](../docker-hub/configure-sign-in.md).
## Verify the restrictions
To confirm that the restrictions are successful, have each org member pull an image onto their local computer after signing into Docker Desktop. If they are unable to sign in, they will receive an error message.
To confirm that the restrictions are successful, have each organization member pull an image onto their local computer after signing in to Docker Desktop. If they don't sign in, they receive an error message.
For example, if you enable Image Access Management, your members can pull an Organization Image, Docker Official Image, or Verified Publisher Image onto their local machine. If you disable the restrictions, your members can pull any image, including Community Images.
![Image Access Management](images/image-access-management-error.png){:width="700px"}
For example, if you enable Image Access Management, your members can only pull an Organization Image, Docker Official Image, or Verified Publisher Image onto their local machine. If you disable the restrictions, your members can pull any image, including community images.

72
docker-hub/image-management.md
View File

@ -4,69 +4,37 @@ keywords: dashboard, images, image management, inactive
title: Advanced Image Management dashboard
---
{% include upgrade-cta.html
body="Docker Pro, Team, and Business users can now use Docker Hub's **Advanced Image Management** dashboard. The dashboard enables a new level of access to your content, allowing fine-grained pruning of old data and exploration of old versions of pushed images. Upgrade now to start using the Advanced Image Management dashboard."
header-text="This feature requires a paid Docker subscription"
target-url="https://www.docker.com/pricing?utm_source=docker&utm_medium=webreferral&utm_campaign=docs_driven_upgrade_image-mgmt"
%}
> **Note**
>
> Image management requires a
> [Docker Pro, Team, or Business subscription](../subscription/index.md).
The **Advanced Image Management** dashboard allows you to manage Docker images across all repositories. [Upgrade](https://www.docker.com/pricing?utm_source=docker&utm_medium=webreferral&utm_campaign=docs_driven_upgrade){: target="_blank" rel="noopener" class="_"} your existing subscription to start using the Advanced Image Management dashboard. [Personal Access Tokens](../docker-hub/access-tokens.md) (PATs) are recommended when using automated flows and API integrations for added security. It's easier to manage your account if it becomes compromised and the account owner can remove them from Docker Hub.
Advanced Image Management allows you to manage Docker images across all repositories and streamline storage in Docker Hub.
The Advanced Image Management dashboard provides a snapshot of your existing images and allows you to view, sort, and filter images by tags, activity status, and date, and contains options to clean up your workspace by deleting images that are no longer required.
It provides:
- A snapshot of your existing images
- Allows you to view, sort, and filter images by tags, activity status, and date
- Contains options to clean up your workspace by deleting images that are no longer required
The dashboard provides visibility into the status of the images in your repository and allows you to reduce the number of images stored in Docker Hub by reviewing their active status. An image retains its 'active' status if it is pulled or pushed in the last month. If there isn’t any activity on the image in the last month, it is considered 'inactive'.
## Access the Advanced Image Management dashboard
By displaying the activity status and tags, the dashboard makes it easier for you to review the existing images and take actions to delete images that are not needed anymore. This is particularly helpful when your repository contains a lot of images that you have pushed over time, and you are now trying to streamline storage in Docker Hub.
1. Sign in to [Docker Hub](https://hub.docker.com){: target="_blank" rel="noopener" class="_"}.
2. Select **Repositories**.
3. Choose a repository.
4. Select **General** or **Tags**, and then select **Go to Advanced Image Management**.
The dashboard also displays the old versions of images you have pushed. When you push an image to Docker Hub, you push a manifest, a list of all the layers of your image, and the layers themselves. When you update an existing tag, only the new layers are pushed, along with the new manifest which references these layers. This new manifest gets the tag you specify when you push the image, such as `myNamespace/mytag:latest`. This does not remove the old manifests or the unique layers referenced by them from Hub. You can still use and reference these using the digest of the manifest if you know the SHA.
## Understand image activity status and tags
With the new Advanced Image Management dashboard, all of this is now simpler and accessible for you to browse, use, and clean up.
An image retains its 'active' status if it's pulled or pushed in the last month. If there isn’t any activity on the image in the last month, it's considered 'inactive'.
To access the Advanced Image Management dashboard:
The dashboard also displays the old versions of images you have pushed. When you push an image to Docker Hub, you push a manifest, which is a list of all the layers of your image and the layers themselves. When you update an existing tag, only the new layers are pushed along with the new manifest which references the new layers. This new manifest gets the tag you specify when you push the image, such as `myNamespace/mytag:latest`. This doesn't remove the old manifests or the unique layers referenced by them from Hub. You can still use and reference these using the digest of the manifest if you know the SHA.
1. Log in to [Docker Hub](https://hub.docker.com){: target="_blank" rel="noopener" class="_"}.
2. Click **Repositories** from the main menu and select a repository from the list.
3. Click **General** or **Tags**, and click **Go to Advanced Image Management**.
## Deleting a tagged image
![Advanced image management dashboard](images/advanced-image-general.png){:width="700px"}
A Docker image can contain multiple tags. A tag refers to a combination of artifacts or labels associated with the image. When you attempt to delete a tagged image, it deletes the tag associated with the image. This means, if there are any untagged images in your repository that previously held the same tag, those images will also be deleted even if they are active. Therefore, you must be careful when deleting tagged images.
4. In the dashboard you can sort and filter by active, inactive and untagged images.
> **Note**
>
> You must be logged in as a Docker Pro, Team, or a Business user to use the Advanced Image Management dashboard. Click [Upgrade](https://www.docker.com/pricing?utm_source=docker&utm_medium=webreferral&utm_campaign=docs_driven_upgrade){: target="_blank" rel="noopener"class="_"} to upgrade your existing subscription.
## View images
The Advanced Image Management dashboard provides a snapshot of your existing images and allows you to view images by tags, activity status and date, and also allows you to clean up your workspace by deleting images that are no longer required.
![Advanced image management dashboard](images/image-management-dashboard.png){:width="700px"}
## Delete images
You must be logged in as a Docker Pro, Team, or a Business user and have admin access to the repository to delete images. By default, the Advanced Image Management dashboard displays inactive images in the repository.
To delete an inactive image:
1. Log in to [Docker Hub](https://hub.docker.com){: target="_blank" rel="noopener" class="_"}.
2. Click **Repositories** from the main menu and select a repository from the list.
3. Click **General** or **Tags**, and click **Go to Advanced Image Management**.
4. Enable the **Inactive** filter to view your inactive tags.
![Advanced image management dashboard](images/dashboard-delete-image.png){:width="700px"}
5. Select the images that you want to delete from the repository and click the delete icon.
### Deleting a tagged image
A Docker image can contain multiple tags. A ‘tag’ refers to a combination of artifacts or labels associated with the image. When you attempt to delete a tagged image, it deletes the tag associated with the image. This means, if there are any untagged images in your repository that previously held the same tag, those images will also be deleted even if they are not inactive. Therefore, you must be careful when deleting tagged images.
For example, let's assume that Image-A is tagged as ‘latest’. You push another image, Image-B, and tag it as the new 'latest'. If you now delete Image-B, the 'latest' tag will be deleted, along with all images it previously referred to. However, if those images are tagged by another tag - in this case, if Image-B is also tagged with '1.5.0', for example, that tag would prevent its deletion.
For example, let's assume that Image A is tagged as ‘latest’. You push another image, Image B, and tag it as the new 'latest'. If you now delete Image-B, the 'latest' tag will be deleted, along with all images it previously referred to. However, if those images are tagged by another tag - in this case, if Image-B is also tagged with '1.5.0', for example, that tag would prevent its deletion.
## Advanced Image Management API
The Advanced Image Management API endpoints allow you to manage Docker images across all repositories. For more information, see [Advanced Image management API](../api/latest/).
## Feedback
Thank you for trying out the Advanced Image Management dashboard. Your feedback is very important to us. Let us know your feedback by creating an issue in the [hub-feedback](https://github.com/docker/hub-feedback/issues){: target="_blank" rel="noopener" class="_"} GitHub repository.

Some files were not shown because too many files have changed in this diff Show More