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

Merge pull request #13725 from docker/master 

Updates from Master
This commit is contained in:
Sebastiaan van Stijn 2021-10-22 20:14:40 +02:00 committed by GitHub
parent 6d8b535228 9c0f4b5f51
commit d09f53ae49
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 145 additions and 70 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
desktop/mac/networking.md
View File

@ -44,6 +44,32 @@ syntax for `-p` is `HOST_PORT:CLIENT_PORT`.
See [Proxies](index.md#proxies).
### SSH agent forwarding
Docker Desktop for Mac allows you to use the host’s SSH agent inside a container. To do this:
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`
1. Add the `SSH_AUTH_SOCK` environment variable in your container:
`-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:
```yaml
services:
web:
image: nginx:alpine
volumes:
- type: bind
source: /run/host-services/ssh-auth.sock
target: /run/host-services/ssh-auth.sock
environment:
- SSH_AUTH_SOCK=/run/host-services/ssh-auth.sock
```
## Known limitations, use cases, and workarounds
Following is a summary of current limitations on the Docker Desktop for {{Arch}}

8
desktop/mac/release-notes/index.md
View File

@ -27,9 +27,11 @@ This page contains information about the new features, improvements, known issue
### Bug fixes and minor changes
- Fixed a bug where a `Docker.qcow2` file would be ignored on upgrade and a fresh `Docker.raw` used instead, resulting in containers and images disappearing. If a system has both files (due to the previous bug) then the most recently modified file will be used, to avoid recent containers and images disappearing again. To force the use of the old `Docker.qcow2`, delete the newer `Docker.raw` file. Fixes [docker/for-mac#5998](https://github.com/docker/for-mac/issues/5998).
- Fixed update notification overlay sometimes getting out of sync between the Settings button and the Software update button in the Dashboard.
- Fixed menu entry to install a downloaded new Desktop update. When an update is ready to install `Restart` should change to `Update and restart`.
> When upgrading from 4.1.0, the Docker menu does not change to **Update and restart** so you can just wait for the download to complete (icon changes) and then select **Restart**. This bug is fixed in 4.1.1, for future upgrades.
- Fixed a bug where a `Docker.qcow2` file would be ignored on upgrade and a fresh `Docker.raw` used instead, resulting in containers and images disappearing. If a system has both files (due to the previous bug), then the most recently modified file will be used to avoid recent containers and images disappearing again. To force the use of the old `Docker.qcow2`, delete the newer `Docker.raw` file. Fixes [docker/for-mac#5998](https://github.com/docker/for-mac/issues/5998).
- Fixed the update notification overlay sometimes getting out of sync between the **Settings** button and the **Software update** button in the Docker Dashboard.
- Fixed the menu entry to install a newly downloaded Docker Desktop update. When an update is ready to install, the **Restart** option changes to **Update and restart**.
## Docker Desktop 4.1.0
2021-09-30

1
desktop/windows/release-notes/index.md
View File

@ -29,7 +29,6 @@ This page contains information about the new features, improvements, known issue
- Fixed a regression in WSL 2 integrations for some distros (e.g. Arch or Alpine). Fixes [docker/for-win#12229](https://github.com/docker/for-win/issues/12229)
- Fixed update notification overlay sometimes getting out of sync between the Settings button and the Software update button in the Dashboard.
## Docker Desktop 4.1.0
2021-09-30

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

@ -6,7 +6,8 @@ redirect_from:
- /docker-cloud/builds/advanced/
---
The following options allow you to customize your automated build and automated test processes.
The following options allow you to customize your automated build and automated
test processes.
## Environment variables for building and testing
@ -29,7 +30,7 @@ If you are using these build environment variables in a
`docker-compose.test.yml` file for automated testing, declare them in your `sut`
service's environment as shown below.
```none
```yaml
services:
sut:
build: .
@ -44,7 +45,8 @@ 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
basic `docker` commands, so you must include a similar build, test or push
@ -53,9 +55,14 @@ command in the hook or your automated process does not complete.
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
`hooks/build`, `hooks/test`, or `hooks/push` and include commands that the
builder process can execute, such as `docker` and `bash` commands (prefixed appropriately with `#!/bin/bash`).
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="_"}, a distro based on Ubuntu, which includes interpreters such as Perl and Python and utilities such as `git` or `curl`. Please check the link above for the full list.
These hooks will be running 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="_"}
for the full list of available interpreters and utilities.
## Custom build phase hooks
@ -65,7 +72,9 @@ autotest processes.
Create a folder called `hooks` in your source code repository at the same
directory level as your Dockerfile. Place files that define the hooks in that
folder. Hook files can include both `docker` commands, and `bash` commands as long as they are prefixed appropriately with `#!/bin/bash`. The builder executes the commands in the files before and after each step.
folder. Hook files can include both `docker` commands, and `bash` commands as
long as they are prefixed appropriately with `#!/bin/bash`. The builder executes
the commands in the files before and after each step.
The following hooks are available:
@ -81,27 +90,36 @@ The following hooks are available:
#### 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).
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).
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 Docker Hub build settings. `$DOCKERFILE_PATH` is a variable that we provide with the name of the Dockerfile we wish to build, and `$IMAGE_NAME` is the name of the image being built.
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
Docker Hub build settings. `$DOCKERFILE_PATH` is a variable that we provide with
the name of the Dockerfile we wish to build, and `$IMAGE_NAME` is the name of
the image being built.
```none
docker build --build-arg CUSTOM=$VAR -f $DOCKERFILE_PATH -t $IMAGE_NAME .
```console
$ 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
the automated build fails.
To learn more about Docker build-time variables, see the [docker build documentation](../../engine/reference/commandline/build.md#set-build-time-variables---build-arg).
Refer to the [docker build documentation](../../engine/reference/commandline/build.md#set-build-time-variables---build-arg)
to learn more about Docker build-time variables.
#### Push to multiple repos
By default the build process pushes the image only to the repository where the build settings are configured. If you need to push the same image to multiple repositories, you can set up a `post_push` hook to add additional tags and push to more repositories.
By default the build process pushes the image only to the repository where the
build settings are configured. If you need to push the same image to multiple
repositories, you can set up a `post_push` hook to add additional tags and push
to more repositories.
```none
docker tag $IMAGE_NAME $DOCKER_REPO:$SOURCE_COMMIT
docker push $DOCKER_REPO:$SOURCE_COMMIT
```console
$ docker tag $IMAGE_NAME $DOCKER_REPO:$SOURCE_COMMIT
$ docker push $DOCKER_REPO:$SOURCE_COMMIT
```
## Source Repository / Branch Clones
@ -117,9 +135,14 @@ you do one of the following:
* You can get a shallow checkout of the target branch by doing the following:
git fetch origin branch:mytargetbranch --depth 1
```console
$ git fetch origin branch:mytargetbranch --depth 1
```
* You can also "unshallow" the clone, which fetches the whole Git history (and potentially
takes a long time / moves a lot of data) by using the `--unshallow` flag on the fetch:
* You can also "unshallow" the clone, which fetches the whole Git history (and
potentially takes a long time / moves a lot of data) by using the `--unshallow`
flag on the fetch:
git fetch --unshallow origin
```console
$ git fetch --unshallow origin
```

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

@ -8,8 +8,9 @@ title: Automated repository tests
---
Docker Hub can automatically test changes to your source code repositories
using containers. You can enable `Autotest` on [any Docker Hub repository](/docker-hub/repos) to run tests on each pull request to the source code
repository to create a continuous integration testing service.
using containers. You can enable `Autotest` on [any Docker Hub repository](../repos.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**
automatically push the built image to the Docker repository. If you want to push
@ -24,7 +25,7 @@ contains the Dockerfile used to build the image.
For example:
```none
```yaml
services:
sut:
build: .
@ -38,8 +39,16 @@ 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.
> **Note**: Only the `sut` service and all other services listed in [`depends_on`](https://docs.docker.com/compose/compose-file/compose-file-v2/#depends_on) are started. For instance, if you have services that poll for changes in other services, be sure to include the polling services in the [`depends_on`](https://docs.docker.com/compose/compose-file/compose-file-v2/#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](https://docs.docker.com/compose/compose-file/compose-versioning/#version-2) file format.
> **Note**
>
> Only the `sut` service and all other services listed in
> [`depends_on`](../../compose/compose-file/compose-file-v2.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)
> 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.

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

@ -11,7 +11,7 @@ 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."
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"
%}
@ -19,12 +19,7 @@ title: Set up Automated 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.
> **Note**
>
> 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.
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
@ -42,14 +37,14 @@ pushing to the registry. You can use these tests to create a continuous
integration workflow where a build that fails its tests does not push the built
image. Automated tests do not push images to the registry on their own. [Learn more about automated image testing here.](automated-testing.md)
Depending on your [plan](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 by the plan that you
subscribe to. Once `N+1` builds are running, any additional builds are
queued to be run later.
Depending on your [plan](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 by the plan that you subscribe to. Once `N+1` builds
are running, any additional builds are queued to be run later.
> **Note**
>
> The total number of pending builds in the queue is limited to 30 and further requests will be discarded. The number of concurrent builds for Pro is 5 and for Team is 15.
The total number of pending builds in the queue is limited to 30 and further
requests will be discarded. The number of concurrent builds for Pro is 5 and
for Team and Business is 15.
![An automated build dashboard](images/index-dashboard.png)
@ -66,9 +61,10 @@ Builds can be added to existing repositories, or added when you create a reposit
2. Click 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.
You might redirected to the settings page to [link](link-source.md) the code repository service.
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.
You may be redirected to the settings page to [link](link-source.md) the code
repository service.
Otherwise, if you are editing the build settings for an existing automated
build, click **Configure automated builds**.
@ -82,7 +78,7 @@ You might redirected to the settings page to [link](link-source.md) the code rep
5. Optionally, enable [autotests](automated-testing.md#enable-automated-tests-on-a-repository).
6. Review the default **Build Rules**, and optionally click the
**plus sign** to add and configure more build rules.
**plus sign** to add and configure more build rules.
_Build rules_ control what Docker Hub builds into images from the contents
of the source code repository, and how the resulting images are tagged
@ -101,13 +97,14 @@ You might redirected to the settings page to [link](link-source.md) the code rep
8. 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
[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
many dependencies. You might want to leave build caching disabled to
make sure all of your dependencies are resolved at build time, or if
you have a large layer that is quicker to build locally.
9. Click **Save** to save the settings, or click **Save and build** to save and
run an initial test.
run an initial test.
A webhook is automatically added to your source code repository to notify
Docker Hub on every push. Only pushes to branches that are listed as the
@ -124,9 +121,8 @@ In the **Build Rules** section, enter one or more sources to build.
For each source:
* Select the **Source type** to build either a **tag** or a
**branch**. This tells the build system what to look for in the source code
repository.
* Select the **Source type** to build either a **tag** or a **branch**. This
tells the build system what to look for in the source code repository.
* Enter the name of the **Source** branch or tag you want to build.
@ -144,11 +140,16 @@ For each source:
capture groups and use its result as part of the tag. To learn more, see
[regexes](index.md#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 `/`.)
* 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) for more information.
> 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)
> for more information.
### Environment variables for builds
@ -201,8 +202,9 @@ display a **Retry** button.
> **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.
> 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.
## Disable an automated build
@ -272,11 +274,15 @@ Depending on how the files are arranged 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 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.
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**
>
> If you delete the default path `/` from the **Build context** field and leave it blank, the build system uses the path to the Dockerfile as the build context. However, to avoid confusion we recommend that you specify the complete path.
> If you delete the default path `/` from the **Build context** field and leave
> it blank, the build system uses the path to the Dockerfile as the build context.
> However, to avoid confusion we recommend that you specify the complete path.
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
@ -296,13 +302,16 @@ these in the **Docker Tag** field using `{\1}` through `{\9}`.
<!-- Capture groups Not a priority
#### Regex example: build from version number branch and tag with version number
You could also use capture groups to build and label images that come from various sources. For example, you might have
You could also use capture groups to build and label images that come from various
sources. For example, you might have
`/(alice|bob)-v([0-9.]+)/` -->
### Build images with BuildKit
Autobuilds use the BuildKit build system by default. If you want to use the legacy Docker build system, add the [environment variable](index.md#environment-variables-for-builds){: target="_blank" rel="noopener" class="_"} `DOCKER_BUILDKIT=0`. Refer to the [build images with BuildKit](../../develop/develop-images/build_enhancements.md)
Autobuilds use the BuildKit build system by default. If you want to use the legacy
Docker build system, add the [environment variable](index.md#environment-variables-for-builds){: target="_blank" rel="noopener" class="_"}
`DOCKER_BUILDKIT=0`. Refer to the [build images with BuildKit](../../develop/develop-images/build_enhancements.md)
page for more information on BuildKit.
## Build repositories with linked private submodules
@ -314,11 +323,16 @@ 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.
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.
> 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.
@ -333,11 +347,13 @@ To work around this, you can set up your automated build using the `SSH_PRIVATE`
> **Note**
>
> You must configure your private git submodules using git clone over SSH (`git@submodule.tld:some-submodule.git`) rather than HTTPS.
> 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 can start, cancel, and retry builds, and edit and delete your own repositories.
When you create an automated build repository in your own account namespace, 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
@ -381,7 +397,9 @@ variable to automated builds associated with the account.
2. Create a "build" team in your organization.
3. Ensure that the new "build" team has access to each repository and submodule you need to build.
Go to the repository's **Settings** page. On GitHub, add the new "build" team to the list of **Collaborators and Teams**. On Bitbucket, add the "build" team to the list of approved users on the **Access management** screen.
Go to the repository's **Settings** page. On GitHub, add the new "build" team
to the list of **Collaborators and Teams**. On Bitbucket, add the "build" team
to the list of approved users on the **Access management** screen.
4. Add the service user to the "build" team on the source provider.
@ -408,4 +426,4 @@ integrates seamlessly with autobuild and autoredeploy.
> **Note**
>
> While the Autotest feature builds an image for testing purposes, it
does not push the resulting image to Docker Hub.
> does not push the resulting image to Docker Hub.

1
engine/install/debian.md
View File

@ -83,7 +83,6 @@ from the repository.
$ sudo apt-get update
$ sudo apt-get install \
apt-transport-https \
ca-certificates \
curl \
gnupg \

1
engine/install/ubuntu.md
View File

@ -105,7 +105,6 @@ from the repository.
$ sudo apt-get update
$ sudo apt-get install \
apt-transport-https \
ca-certificates \
curl \
gnupg \