diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index b68fedc3bc1d..020e0fae1bda 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -18,17 +18,20 @@ jobs: JEKYLL_ENV=development DOCS_AWS_REGION=us-east-1 if [ "${{ github.ref }}" = "refs/heads/master" ]; then + DOCS_URL="https://docs-stage.docker.com" DOCS_S3_BUCKET="docs.docker.com-stage-us-east-1" DOCS_S3_CONFIG="_website-config-docs-stage.json" DOCS_LAMBDA_FUNCTION_CACHE="arn:aws:lambda:us-east-1:710015040892:function:docs-stage-cache-invalidator" DOCS_SLACK_MSG="Successfully promoted docs-stage from master. https://docs-stage.docker.com/" elif [ "${{ github.ref }}" = "refs/heads/published" ]; then JEKYLL_ENV=production + DOCS_URL="https://docs.docker.com" DOCS_S3_BUCKET="docs.docker.com-us-east-1" DOCS_S3_CONFIG="_website-config-docs.json" DOCS_LAMBDA_FUNCTION_CACHE="arn:aws:lambda:us-east-1:710015040892:function:docs-cache-invalidator" DOCS_SLACK_MSG="Successfully published docs. https://docs.docker.com/" elif [ "${{ github.ref }}" = "refs/heads/lab" ]; then + DOCS_URL="https://docs-lab.docker.com" DOCS_S3_BUCKET="" DOCS_LAMBDA_FUNCTION_CACHE="" DOCS_S3_CONFIG="_website-config-docs-lab.json" @@ -37,6 +40,7 @@ jobs: exit 1 fi echo "JEKYLL_ENV=$JEKYLL_ENV" >> $GITHUB_ENV + echo "DOCS_URL=$DOCS_URL" >> $GITHUB_ENV echo "DOCS_AWS_REGION=$DOCS_AWS_REGION" >> $GITHUB_ENV echo "DOCS_S3_BUCKET=$DOCS_S3_BUCKET" >> $GITHUB_ENV echo "DOCS_S3_CONFIG=$DOCS_S3_CONFIG" >> $GITHUB_ENV diff --git a/.gitignore b/.gitignore index 66fb99c3ff76..16bba78d6d6d 100644 --- a/.gitignore +++ b/.gitignore @@ -5,6 +5,7 @@ .jekyll-metadata _site/** .sass-cache/** +.vscode CNAME _kbase/** /vendor diff --git a/Dockerfile b/Dockerfile index 5502e21878e7..e8c0da542b05 100644 --- a/Dockerfile +++ b/Dockerfile @@ -10,7 +10,7 @@ ARG RUBY_VERSION=2.7.6 ARG BUNDLER_VERSION=2.3.13 ARG JEKYLL_ENV=development -ARG DOMAIN=docs.docker.com +ARG DOCS_URL=http://localhost:4000 # Base stage for building FROM ruby:${RUBY_VERSION}-alpine AS base @@ -44,28 +44,14 @@ COPY --from=vendored /out / # After building with jekyll, fix up some links FROM gem AS generate ARG JEKYLL_ENV -ARG DOMAIN +ARG DOCS_URL ENV TARGET=/out RUN --mount=type=bind,target=.,rw \ - --mount=type=cache,target=/src/.jekyll-cache </#https://${DOMAIN}/#" "${TARGET}/sitemap.xml" - ) -else - ( - set -x - bundle exec jekyll build --trace --profile -d ${TARGET} - mkdir -p ${TARGET}/js - echo '[]' > ${TARGET}/js/metadata.json - ) -fi -find ${TARGET} -type f -name '*.html' | while read i; do - sed -i "s#\(]* href=\"\)https://${DOMAIN}/#\1/#g" "$i" -done + --mount=type=cache,target=/src/.jekyll-cache <]* href=\")#{docs_url}/, '\1') + File.open(f, "w") { |f2| f2.puts replace } + end + + end_time = Time.now + Jekyll.logger.info "done in #{(end_time - beginning_time)} seconds" + end + end +end diff --git a/_plugins/fix_urls.rb b/_plugins/fix_urls.rb deleted file mode 100644 index 1d96f38ebc65..000000000000 --- a/_plugins/fix_urls.rb +++ /dev/null @@ -1,22 +0,0 @@ -require 'jekyll' -require 'octopress-hooks' - -module Jekyll - class FetchRemote < Octopress::Hooks::Site - def post_read(site) - beginning_time = Time.now - Jekyll.logger.info "Starting plugin fix_urls.rb..." - - Jekyll.logger.info " Fixing up URLs in swagger files" - Dir.glob(%w[./docker-hub/api/*.yaml ./engine/api/*.yaml]) do |file_name| - Jekyll.logger.info " #{file_name}" - text = File.read(file_name) - replace = text.gsub("https://docs.docker.com", "") - File.open(file_name, "w") { |file| file.puts replace } - end - - end_time = Time.now - Jekyll.logger.info "done in #{(end_time - beginning_time)} seconds" - end - end -end diff --git a/_plugins/update_sitemap.rb b/_plugins/update_sitemap.rb new file mode 100644 index 000000000000..a3be4a06ed60 --- /dev/null +++ b/_plugins/update_sitemap.rb @@ -0,0 +1,18 @@ +require_relative 'util.rb' + +Jekyll::Hooks.register :site, :post_write do |site| + beginning_time = Time.now + Jekyll.logger.info "Starting plugin update_sitemap.rb..." + + sitemap_path = File.join(site.dest, 'sitemap.xml') + + if File.exist?(sitemap_path) + sitemap_file = File.read(sitemap_path) + replace = sitemap_file.gsub!("/", "#{get_docs_url}/") + Jekyll.logger.info " Replacing '/' with '#{get_docs_url}/' in #{sitemap_path}" + File.open(sitemap_path, "w") { |file| file.puts replace } + end + + end_time = Time.now + Jekyll.logger.info "done in #{(end_time - beginning_time)} seconds" +end diff --git a/_plugins/util.rb b/_plugins/util.rb new file mode 100644 index 000000000000..d8f118d571d1 --- /dev/null +++ b/_plugins/util.rb @@ -0,0 +1,5 @@ +def get_docs_url + # DEPLOY_URL is from Netlify for preview + # https://docs.netlify.com/configure-builds/environment-variables/#deploy-urls-and-metadata + ENV['DEPLOY_URL'] || ENV['DOCS_URL'] || 'https://docs.docker.com' +end diff --git a/build/buildx/drivers/docker-container.md b/build/buildx/drivers/docker-container.md new file mode 100644 index 000000000000..de11b89f52a9 --- /dev/null +++ b/build/buildx/drivers/docker-container.md @@ -0,0 +1,7 @@ +--- +title: "Docker container driver" +keywords: build, buildx, driver, builder, docker-container +fetch_remote: + line_start: 2 + line_end: -1 +--- diff --git a/build/buildx/drivers/index.md b/build/buildx/drivers/index.md new file mode 100644 index 000000000000..0be093e09997 --- /dev/null +++ b/build/buildx/drivers/index.md @@ -0,0 +1,7 @@ +--- +title: "Buildx drivers overview" +keywords: build, buildx, driver, builder, docker-container, kubernetes, remote +fetch_remote: + line_start: 2 + line_end: -1 +--- diff --git a/build/buildx/drivers/kubernetes.md b/build/buildx/drivers/kubernetes.md new file mode 100644 index 000000000000..d89d6e7ac778 --- /dev/null +++ b/build/buildx/drivers/kubernetes.md @@ -0,0 +1,7 @@ +--- +title: "Kubernetes driver" +keywords: build, buildx, driver, builder, kubernetes +fetch_remote: + line_start: 2 + line_end: -1 +--- diff --git a/build/buildx/drivers/remote.md b/build/buildx/drivers/remote.md new file mode 100644 index 000000000000..e3eb1cdccff5 --- /dev/null +++ b/build/buildx/drivers/remote.md @@ -0,0 +1,22 @@ +--- +title: "Remote driver" +keywords: build, buildx, driver, builder, remote +fetch_remote: + line_start: 2 + line_end: -1 +--- + +> Beta +> +> Remote driver is currently available as a beta feature. We recommend that you +> do not use this feature in production environments. You can [build Buildx from source](https://github.com/docker/buildx#building){: target="_blank" rel="noopener" class="_"} +> to test the remote driver or use the following command to download and +> install an edge release of Buildx: +> +> ```console +> $ echo "FROM docker/buildx-bin:master" | docker buildx build --platform=local --output . -f - . +> $ mkdir -p ~/.docker/cli-plugins/ +> $ mv buildx ~/.docker/cli-plugins/docker-buildx +> ``` +{: .important} + diff --git a/build/buildx/index.md b/build/buildx/index.md index 775b92a26af6..a7fc32357ec0 100644 --- a/build/buildx/index.md +++ b/build/buildx/index.md @@ -34,19 +34,18 @@ In addition, Buildx also supports new features that are not yet available for regular `docker build` like building manifest lists, distributed caching, and exporting build results to OCI image tarballs. -You can run Buildx in different configurations that are exposed through a driver -concept. Currently, Docker supports a "docker" driver that uses the BuildKit -library bundled into the Docker daemon binary, and a "docker-container" driver -that automatically launches BuildKit inside a Docker container. - -The user experience of using Buildx is very similar across drivers. However, -there are some features that are not currently supported by the "docker" driver, -because the BuildKit library which is bundled into docker daemon uses a different -storage component. In contrast, all images built with the "docker" driver are -automatically added to the "docker images" view by default, whereas when using -other drivers, the method for outputting an image needs to be selected -with `--output`. +Buildx is flexible and can be run in different configurations that are exposed +through various "drivers". Each driver defines how and where a build should +run, and have different feature sets. +We currently support the following drivers: + +* The `docker` driver ([reference](/engine/reference/commandline/buildx_create/#driver)) +* The `docker-container` driver ([guide](drivers/docker-container.md), [reference](/engine/reference/commandline/buildx_create/#driver)) +* The `kubernetes` driver ([guide](drivers/kubernetes.md), [reference](/engine/reference/commandline/buildx_create/#driver)) +* The `remote` driver ([guide](drivers/remote.md)) + +For more information on drivers, see the [drivers guide](drivers/index.md). ## High-level build options with Bake diff --git a/build/buildx/install.md b/build/buildx/install.md index b2fe45d0ffce..0f33bd40122b 100644 --- a/build/buildx/install.md +++ b/build/buildx/install.md @@ -75,4 +75,4 @@ sets up docker builder command as an alias to `docker buildx`. This results in the ability to have [`docker build`](../../engine/reference/commandline/build.md) use the current buildx builder. -To remove this alias, run [`docker buildx uninstall`](../../engine/reference/commandline/buildx_uninstall.md). \ No newline at end of file +To remove this alias, run [`docker buildx uninstall`](../../engine/reference/commandline/buildx_uninstall.md). diff --git a/build/buildx/multiplatform-images.md b/build/buildx/multiplatform-images.md index 9f0b3fc87e57..21fda31c31db 100644 --- a/build/buildx/multiplatform-images.md +++ b/build/buildx/multiplatform-images.md @@ -3,6 +3,7 @@ title: Building multi-platform images description: Different strategies for building multi-platform images keywords: build, buildx, buildkit, multi-platform images --- + BuildKit is designed to work well for building for multiple platforms and not only for the architecture and operating system that the user invoking the build happens to run. @@ -75,4 +76,4 @@ ARG BUILDPLATFORM RUN echo "I am running on $BUILDPLATFORM, building for $TARGETPLATFORM" > /log FROM alpine COPY --from=build /log /log -``` \ No newline at end of file +``` diff --git a/build/buildx/multiple-builders.md b/build/buildx/multiple-builders.md index 4a68cf1555f9..7aebd879d0a3 100644 --- a/build/buildx/multiple-builders.md +++ b/build/buildx/multiple-builders.md @@ -3,6 +3,7 @@ title: Using multiple builders description: How to instantiate and work with multiple builders keywords: build, buildx, buildkit, builders, build drivers --- + By default, Buildx uses the `docker` driver if it is supported, providing a user experience very similar to the native `docker build`. Note that you must use a local shared daemon to build your applications. @@ -33,4 +34,4 @@ Docker also features a [`docker context`](../../engine/reference/commandline/con command that you can use to provide names for remote Docker API endpoints. Buildx integrates with `docker context` to ensure all the contexts automatically get a default builder instance. You can also set the context name as the target when -you create a new builder instance or when you add a node to it. \ No newline at end of file +you create a new builder instance or when you add a node to it. diff --git a/build/index.md b/build/index.md index 529cd1e4061f..085349c41f41 100644 --- a/build/index.md +++ b/build/index.md @@ -40,18 +40,15 @@ Bundle and package your code to run anywhere, from your local Docker Desktop, to To get started with Build, see the [Hello Build](hellobuild.md) page. * **Choosing a build driver** -Run Buildx with different configurations depending on the scenario you are working on, regardless of whether you are using your local machine or a remote compute cluster, all from the comfort of your local working environment. -Here’s a quick overview of the drivers and the use cases they support: - * `docker`– use the default built-in builder to get started quickly. - * `docker-container` – spin up a dedicated builder in a docker container to unlock more advanced features like advanced caching, and multi-platform images. - - * `kubernetes`– connect to your Kubernetes cluster to unlock more features and to run your builds at scale. - * `remote`– manually manage your own BuildKit builder and connect directly to it. +Run Buildx with different configurations depending on the scenario you are +working on, regardless of whether you are using your local machine or a remote +compute cluster, all from the comfort of your local working environment. +For more information on drivers, see the [drivers guide](buildx/drivers/index.md). * **Optimizing builds with cache management** Improve build performance by using a persistent shared build cache to avoid repeating costly operations such as package installations, downloading files from the internet, or code build steps. -* **Creating build-once, run-anywhere with multi-architecture builds** +* **Creating build-once, run-anywhere with multi-platform builds** Collaborate across platforms with one build artifact. See [Build multi-platform images](buildx/multiplatform-images.md). diff --git a/desktop/install/debian.md b/desktop/install/debian.md index 60c8b0cfc193..d3bd5a8e5ae0 100644 --- a/desktop/install/debian.md +++ b/desktop/install/debian.md @@ -49,10 +49,10 @@ 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 from the [release](../release-notes.md) page. +2. Download latest [DEB package](https://desktop.docker.com/linux/main/amd64/docker-desktop-4.11.0-amd64.deb?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-linux-amd64). 3. Install the package with apt as follows: - + ```console $ sudo apt-get update $ sudo apt-get install ./docker-desktop--.deb @@ -112,4 +112,4 @@ Remove the `credsStore` and `currentContext` properties from `$HOME/.docker/conf ## Next steps - Take a look at the [Get started](../../get-started/index.md) training modules to learn how to build an image and run it as a containerized application. -- Review the topics in [Develop with Docker](../../develop/index.md) to learn how to build new applications using Docker. \ No newline at end of file +- Review the topics in [Develop with Docker](../../develop/index.md) to learn how to build new applications using Docker. diff --git a/desktop/install/fedora.md b/desktop/install/fedora.md index 72abac4e75af..c287ac8b64d6 100644 --- a/desktop/install/fedora.md +++ b/desktop/install/fedora.md @@ -29,10 +29,10 @@ 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 from the [release](../release-notes.md) page. +2. Download latest [RPM package](https://desktop.docker.com/linux/main/amd64/docker-desktop-4.11.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: - + ```console $ sudo dnf install ./docker-desktop--.rpm ``` diff --git a/desktop/install/linux-install.md b/desktop/install/linux-install.md index cbf52caa99d5..6c2c26494c68 100644 --- a/desktop/install/linux-install.md +++ b/desktop/install/linux-install.md @@ -8,27 +8,26 @@ redirect_from: This page contains information about system requirements, download URLs, and instructions on how to install and update Docker Desktop for Linux. -> Download Docker Desktop for Linux packages +> Follow the links below to view the distro-specific installation instructions: > -> [DEB](https://desktop.docker.com/linux/main/amd64/docker-desktop-4.11.0-amd64.deb?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-linux-amd64){: .button .primary-btn } -> [RPM](https://desktop.docker.com/linux/main/amd64/docker-desktop-4.11.0-x86_64.rpm?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-linux-amd64){: .button .primary-btn } - -*For checksums, see [Release notes](../release-notes.md)* +> * [Ubuntu](ubuntu.md) +> * [Debian](debian.md) +> * [Fedora](fedora.md) ## System requirements To install Docker Desktop successfully, your Linux host must meet the following requirements: -- 64-bit kernel and CPU support for virtualization +- 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. +- **QEMU must be version 5.2 or newer**. We recommend upgrading to the latest version. - systemd init system. - Gnome or KDE Desktop environment. - -For many Linux distros, the Gnome environment does not support tray icons. To add support for tray icons, you need to install a Gnome extension. For example, [AppIndicator](https://extensions.gnome.org/extension/615/appindicator-support/)). + - For many Linux 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/)). - At least 4 GB of RAM. @@ -65,7 +64,7 @@ Docker supports Docker Desktop on the current LTS release of the aforementioned ### KVM virtualization support -Docker Desktop runs a VM that requires [KVM support](https://www.linux-kvm.org). +Docker Desktop runs a VM that requires [KVM support](https://www.linux-kvm.org). The `kvm` module should load automatically if the host has virtualization support. To load the module manually, run: diff --git a/desktop/install/ubuntu.md b/desktop/install/ubuntu.md index 784af4da78d1..22f100c12022 100644 --- a/desktop/install/ubuntu.md +++ b/desktop/install/ubuntu.md @@ -46,12 +46,12 @@ $ sudo apt install gnome-terminal Recommended approach to install Docker Desktop on Ubuntu: -1. Set up [Docker's package repository](../../engine/install/ubuntu.md#set-up-the-repository). +1. Set up [Docker's package repository](../../engine/install/ubuntu.md#set-up-the-repository). -2. Download latest DEB package from the [release](../release-notes.md) page. +2. Download latest [DEB package](https://desktop.docker.com/linux/main/amd64/docker-desktop-4.11.0-amd64.deb?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-linux-amd64). 3. Install the package with apt as follows: - + ```console $ sudo apt-get update $ sudo apt-get install ./docker-desktop--.deb diff --git a/desktop/install/windows-install.md b/desktop/install/windows-install.md index c1f8c2a4ff14..eb166de53ea5 100644 --- a/desktop/install/windows-install.md +++ b/desktop/install/windows-install.md @@ -54,7 +54,7 @@ Your Windows machine must meet the following requirements to successfully instal - 4GB system RAM - BIOS-level hardware virtualization support must be enabled in the BIOS settings. For more information, see - [Virtualization](../troubleshoot/topics.md). + [Virtualization](../troubleshoot/topics.md#virtualization). - Download and install the [Linux kernel update package](https://docs.microsoft.com/windows/wsl/wsl2-kernel){: target="_blank" rel="noopener" class="_"}. @@ -76,7 +76,7 @@ Your Windows machine must meet the following requirements to successfully instal - 4GB system RAM - BIOS-level hardware virtualization support must be enabled in the BIOS settings. For more information, see - [Virtualization](../troubleshoot/topics.md). + [Virtualization](../troubleshoot/topics.md#virtualization). @@ -89,9 +89,9 @@ Containers and images created with Docker Desktop are shared between all user accounts on machines where it is installed. This is because all Windows accounts use the same VM to build and run containers. Note that it is not possible to share containers and images between user accounts when using the Docker Desktop WSL 2 backend. -Nested virtualization scenarios, such as running Docker Desktop on a -VMWare or Parallels instance might work, but there are no guarantees. For -more information, see [Running Docker Desktop in a VM or VDI environment](../vm-vdi.md). +Running Docker Desktop inside a VMware ESXi or Azure VM is supported for Docker Business customers. +It requires enabling nested virtualization on the hypervisor first. +For more information, see [Running Docker Desktop in a VM or VDI environment](../vm-vdi.md). ### About Windows containers diff --git a/desktop/vm-vdi.md b/desktop/vm-vdi.md index a5d710180186..413af6496ff9 100644 --- a/desktop/vm-vdi.md +++ b/desktop/vm-vdi.md @@ -10,15 +10,15 @@ In general, Docker recommends running Docker Desktop natively on either Mac, Lin To run Docker Desktop in a virtual desktop environment, it is essential nested virtualization is enabled on the virtual machine that provides the virtual desktop. This is because, under the hood, Docker Desktop is using a Linux VM in which it runs Docker Engine and the containers. -## Nested virtualization support +## Virtual desktop support >Note > -> Nested virtualization support is only available to Docker Business customers. +> Support for running Docker Desktop on a virtual desktop is available to Docker Business customers, on VMware ESXi or Azure VMs only. -The support available from Docker extends to installing and running Docker Desktop inside the VM, once the nested virtualization is set up correctly. For more information on Docker Desktop support, see [Get support](support.md). +The support available from Docker extends to installing and running Docker Desktop inside the VM, once the nested virtualization is set up correctly. The only hypervisors we have successfully tested are VMware ESXi and Azure, and there is no support for other VMs. For more information on Docker Desktop support, see [Get support](support.md). -For troubleshooting problems and intermittent failures that are outside of Docker's control, you should contact your hypervisor vendor. Each hypervisor vendor offers different levels of support. For example, Microsoft supports running nested Hyper-V both on-prem and on Azure, with some version constraints. This may not be the case for VMWare ESXi or Citrix Hypervisor. +For troubleshooting problems and intermittent failures that are outside of Docker's control, you should contact your hypervisor vendor. Each hypervisor vendor offers different levels of support. For example, Microsoft supports running nested Hyper-V both on-prem and on Azure, with some version constraints. This may not be the case for VMWare ESXi. ## Enable nested virtualization @@ -35,9 +35,6 @@ You may also need to [configure some network settings](https://www.vembu.com/blo ### Enable nested virtualization on Microsoft Hyper-V -Nested virtualization is supported by Microsoft for running Hyper-V inside a VM running on a Hyper-V host, in Azure or on-prem (Hyper-V on Hyper-V). +Nested virtualization is supported by Microsoft for running Hyper-V inside an Azure VM. For Azure virtual machines, [check that the VM size chosen supports nested virtualization](https://docs.microsoft.com/en-us/azure/virtual-machines/sizes). Microsoft provides [a helpful list on Azure VM sizes](https://docs.microsoft.com/en-us/azure/virtual-machines/acu) and highlights the sizes that currently support nested virtualization. For internal testing, we used D4s_v5 machines. We recommend this specification or above for optimal performance of Docker Desktop. - -For on-prem virtual machines, check the constraints on the host VM operating system and [follow the steps documented by Microsoft](https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/user-guide/nested-virtualization). - diff --git a/desktop/windows/permission-requirements.md b/desktop/windows/permission-requirements.md new file mode 100644 index 000000000000..efcd7bb63903 --- /dev/null +++ b/desktop/windows/permission-requirements.md @@ -0,0 +1,49 @@ +--- +description: Permission requirements for Docker Desktop for Windows +keywords: Docker Desktop, Windows, security, install +title: Docker Desktop permission requirements for Windows +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, as well as clarification about running containers as `root` as opposed to having `Administrator` access on the host and the privileges of the Windows Docker engine and Windows containers. + +## Permission requirements + +While Docker Desktop can be run without having `Administrator` privileges, it does require them during installation. On installation the user gets an UAC prompt which allows a privileged helper service to be installed. After that Docker Desktop can be run by users without Administrator privileges, provided that 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. + +## 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 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. +- Securely caching the Registry Access Management policy which is read-only for the developer. +- Creating the Hyper-V VM `"DockerDesktopVM"` and managing its lifecycle - starting, stopping and destroying it. The VM name is hard coded in the service code so the service cannot be used for creating or manipulating any other VMs. +- Getting the VHDX disk size. +- Moving the VHDX file or folder. +- Starting and stopping the Windows Docker engine and querying whether it is running. +- Deleting all Windows containers data files. +- Checking if Hyper-V is enabled. +- Checking if the bootloader activates Hyper-V. +- Checking if required Windows features are both installed and enabled. +- Conducting healthchecks and retrieving the version of the service itself. + + +## 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. + +## 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. + +## 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. + + + diff --git a/docker-bake.hcl b/docker-bake.hcl index 107cea49496b..2e4749b96f9d 100644 --- a/docker-bake.hcl +++ b/docker-bake.hcl @@ -1,6 +1,9 @@ variable "JEKYLL_ENV" { default = "development" } +variable "DOCS_URL" { + default = "http://localhost:4000" +} variable "DOCS_SITE_DIR" { default = "_site" } @@ -8,6 +11,7 @@ variable "DOCS_SITE_DIR" { target "_common" { args = { JEKYLL_ENV = JEKYLL_ENV + DOCS_URL = DOCS_URL } no-cache-filter = ["generate"] } diff --git a/docker-compose.yml b/docker-compose.yml index 7d5ab9d730b5..6e9c5f8f5dfe 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -10,6 +10,7 @@ services: build: args: - JEKYLL_ENV + - DOCS_URL context: . image: docs/docstage ports: diff --git a/docker-hub/api/latest.yaml b/docker-hub/api/latest.yaml index 4c6d652a06e2..3332a3c29fd1 100644 --- a/docker-hub/api/latest.yaml +++ b/docker-hub/api/latest.yaml @@ -100,6 +100,11 @@ tags: description: | The repository endpoints allow you to manage your repository's configuration like description. + - name: scim + x-displayName: SCIM + description: | + SCIM is a provisioning system that lets you manage users within your identity provider (IdP). + For more information, see [System for Cross-domain Identity management](https://docs.docker.com/docker-hub/scim/). x-tagGroups: - name: General tags: @@ -113,6 +118,7 @@ x-tagGroups: - audit-logs - org-settings - repositories + - scim paths: /v2/users/login: post: @@ -875,6 +881,266 @@ paths: response: value: detail: Object not found + + /v2/scim/2.0/ServiceProviderConfig: + get: + summary: Get service provider config + description: | + Returns a service provider config for Docker's configuration. + tags: [ scim ] + security: + - bearerSCIMAuth: [ ] + responses: + 200: + $ref: '#/components/responses/scim_get_service_provider_config_resp' + 401: + $ref: "#/components/responses/scim_unauthorized" + 500: + $ref: "#/components/responses/scim_error" + + /v2/scim/2.0/ResourceTypes: + get: + summary: List resource types + description: | + Returns all resource types supported for the SCIM configuration. + tags: [ scim ] + security: + - bearerSCIMAuth: [ ] + responses: + 200: + $ref: "#/components/responses/scim_get_resource_types_resp" + 401: + $ref: "#/components/responses/scim_unauthorized" + 500: + $ref: "#/components/responses/scim_error" + + /v2/scim/2.0/ResourceTypes/{name}: + get: + summary: Get a resource type + description: | + Returns a resource type by name. + tags: [ scim ] + parameters: + - name: name + in: path + schema: + type: string + example: User + security: + - bearerSCIMAuth: [ ] + responses: + 200: + $ref: "#/components/responses/scim_get_resource_type_resp" + 401: + $ref: "#/components/responses/scim_unauthorized" + 404: + $ref: "#/components/responses/scim_not_found" + 500: + $ref: "#/components/responses/scim_error" + + /v2/scim/2.0/Schemas: + get: + summary: List schemas + description: | + Returns all schemas supported for the SCIM configuration. + tags: [ scim ] + security: + - bearerSCIMAuth: [ ] + responses: + 200: + $ref: "#/components/responses/scim_get_schemas_resp" + 401: + $ref: "#/components/responses/scim_unauthorized" + 500: + $ref: "#/components/responses/scim_error" + + /v2/scim/2.0/Schemas/{id}: + get: + summary: Get a schema + description: | + Returns a schema by ID. + tags: [ scim ] + parameters: + - name: id + in: path + schema: + type: string + example: urn:ietf:params:scim:schemas:core:2.0:User + security: + - bearerSCIMAuth: [ ] + responses: + 200: + $ref: "#/components/responses/scim_get_schema_resp" + 401: + $ref: "#/components/responses/scim_unauthorized" + 404: + $ref: "#/components/responses/scim_not_found" + 500: + $ref: "#/components/responses/scim_error" + + /v2/scim/2.0/Users: + get: + summary: List users + description: | + List users, returns paginated users for an organization. Use `startIndex` + and `count` query parameters to receive paginated results. + + **Sorting:**
+ Sorting lets you to specify the order of returned resources by specifying + a combination of `sortBy` and `sortOrder` query parameters. + + The `sortBy` parameter specifies the attribute whose value will be used + to order the returned responses. The `sortOrder` parameter defines the + order in which the `sortBy` parameter is applied. Allowed values are + "ascending" and "descending". + + **Filtering:**
+ You can request a subset of resources by specifying the `filter` query + parameter containing a filter expression. Attribute names and attribute + operators used in filters are case insensitive. The filter parameter + must contain at least one valid expression. Each expression must contain + an attribute name followed by an attribute operator and an optional + value. + + Supported operators are listed below. + + - `eq` equal + - `ne` not equal + - `co` contains + - `sw` starts with + - `and` Logical "and" + - `or` Logical "or" + - `not` "Not" function + - `()` Precedence grouping + tags: [ scim ] + security: + - bearerSCIMAuth: [ ] + parameters: + - name: startIndex + in: query + schema: + type: integer + minimum: 1 + description: "" + example: 1 + - name: count + in: query + schema: + type: integer + minimum: 1 + maximum: 200 + description: "" + example: 10 + - name: filter + in: query + schema: + type: string + description: "" + example: userName eq "jon.snow@docker.com" + - $ref: "#/components/parameters/scim_attributes" + - name: sortOrder + in: query + schema: + type: string + enum: + - ascending + - descending + - name: sortBy + in: query + schema: + type: string + description: "User attribute to sort by." + example: userName + responses: + 200: + $ref: "#/components/responses/scim_get_users_resp" + 400: + $ref: "#/components/responses/scim_bad_request" + 401: + $ref: "#/components/responses/scim_unauthorized" + 403: + $ref: "#/components/responses/scim_forbidden" + 404: + $ref: "#/components/responses/scim_not_found" + 500: + $ref: "#/components/responses/scim_error" + + post: + summary: Create user + description: | + Creates a user. If the user already exists by email, they are assigned + to the organization on the "company" team. + tags: [ scim ] + security: + - bearerSCIMAuth: [ ] + requestBody: + $ref: "#/components/requestBodies/scim_create_user_request" + responses: + 201: + $ref: "#/components/responses/scim_create_user_resp" + 400: + $ref: "#/components/responses/scim_bad_request" + 401: + $ref: "#/components/responses/scim_unauthorized" + 403: + $ref: "#/components/responses/scim_forbidden" + 404: + $ref: "#/components/responses/scim_not_found" + 409: + $ref: "#/components/responses/scim_conflict" + 500: + $ref: "#/components/responses/scim_error" + + /v2/scim/2.0/Users/{id}: + parameters: + - $ref: "#/components/parameters/scim_user_id" + get: + summary: Get a user + description: | + Returns a user by ID. + tags: [ scim ] + security: + - bearerSCIMAuth: [ ] + responses: + 200: + $ref: "#/components/responses/scim_get_user_resp" + 400: + $ref: "#/components/responses/scim_bad_request" + 401: + $ref: "#/components/responses/scim_unauthorized" + 403: + $ref: "#/components/responses/scim_forbidden" + 404: + $ref: "#/components/responses/scim_not_found" + 500: + $ref: "#/components/responses/scim_error" + put: + summary: Update a user + description: | + Updates a user. Use this route to change the user's name, activate, + and deactivate the user. + tags: [ scim ] + security: + - bearerSCIMAuth: [ ] + requestBody: + $ref: "#/components/requestBodies/scim_update_user_request" + responses: + 200: + $ref: "#/components/responses/scim_update_user_resp" + 400: + $ref: "#/components/responses/scim_bad_request" + 401: + $ref: "#/components/responses/scim_unauthorized" + 403: + $ref: "#/components/responses/scim_forbidden" + 404: + $ref: "#/components/responses/scim_not_found" + 409: + $ref: "#/components/responses/scim_conflict" + 500: + $ref: "#/components/responses/scim_error" + + servers: - url: https://hub.docker.com/ components: @@ -903,6 +1169,180 @@ components: application/json: schema: $ref: "#/components/schemas/Error" + + scim_bad_request: + description: Bad Request + content: + application/scim+json: + schema: + allOf: + - $ref: "#/components/schemas/scim_error" + - properties: + status: + example: "400" + scimType: + type: string + description: Some types of errors will return this per the + specification. + scim_unauthorized: + description: Unauthorized + content: + application/scim+json: + schema: + allOf: + - $ref: "#/components/schemas/scim_error" + - properties: + status: + example: "401" + scim_forbidden: + description: Forbidden + content: + application/scim+json: + schema: + allOf: + - $ref: "#/components/schemas/scim_error" + - properties: + status: + example: "403" + scim_not_found: + description: Not Found + content: + application/scim+json: + schema: + allOf: + - $ref: "#/components/schemas/scim_error" + - properties: + status: + example: "404" + scim_conflict: + description: Conflict + content: + application/scim+json: + schema: + allOf: + - $ref: "#/components/schemas/scim_error" + - properties: + status: + example: "409" + scim_error: + description: Internal Error + content: + application/scim+json: + schema: + allOf: + - $ref: "#/components/schemas/scim_error" + - properties: + status: + example: "500" + + scim_get_service_provider_config_resp: + description: "" + content: + application/scim+json: + schema: + $ref: "#/components/schemas/scim_service_provider_config" + + scim_get_resource_types_resp: + description: "" + content: + application/scim+json: + schema: + type: object + properties: + schemas: + type: array + items: + type: string + example: [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ] + totalResults: + type: integer + example: 1 + resources: + type: array + items: + $ref: "#/components/schemas/scim_resource_type" + + scim_get_resource_type_resp: + description: "" + content: + application/scim+json: + schema: + $ref: "#/components/schemas/scim_resource_type" + + scim_get_schemas_resp: + description: "" + content: + application/scim+json: + schema: + type: object + properties: + schemas: + type: array + items: + type: string + example: [ urn:ietf:params:scim:api:messages:2.0:ListResponse ] + totalResults: + type: integer + example: 1 + resources: + type: array + items: + $ref: "#/components/schemas/scim_schema" + + scim_get_schema_resp: + description: "" + content: + application/scim+json: + schema: + $ref: "#/components/schemas/scim_schema" + + scim_get_users_resp: + description: "" + content: + application/scim+json: + schema: + type: object + properties: + schemas: + type: array + items: + type: string + example: [ urn:ietf:params:scim:api:messages:2.0:ListResponse ] + totalResults: + type: integer + example: 1 + startIndex: + type: integer + example: 1 + itemsPerPage: + type: integer + example: 10 + resources: + type: array + items: + $ref: "#/components/schemas/scim_user" + + scim_create_user_resp: + description: "" + content: + application/scim+json: + schema: + $ref: "#/components/schemas/scim_user" + + scim_get_user_resp: + description: "" + content: + application/scim+json: + schema: + $ref: "#/components/schemas/scim_user" + + scim_update_user_resp: + description: "" + content: + application/scim+json: + schema: + $ref: "#/components/schemas/scim_user" + schemas: UsersLoginRequest: description: User login details @@ -1619,3 +2059,337 @@ components: Hello from Docker! This message shows that your installation appears to be working correctly. ``` + + scim_error: + type: object + properties: + status: + type: string + description: The status code for the response in string format. + schemas: + type: array + items: + type: string + default: urn:ietf:params:scim:api:messages:2.0:Error + detail: + type: string + description: Details about why the request failed. + + scim_service_provider_config: + type: object + properties: + schemas: + type: array + items: + type: string + example: [ "urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig" ] + documentationUri: + type: string + example: "" + patch: + properties: + supported: + type: boolean + example: false + bulk: + type: object + properties: + supported: + type: boolean + example: false + maxOperations: + type: integer + maxPayloadSize: + type: integer + filter: + type: object + properties: + supported: + type: boolean + example: true + maxResults: + type: integer + example: 99999 + changePassword: + type: object + properties: + supported: + type: boolean + example: false + sort: + type: object + properties: + supported: + type: boolean + example: true + etag: + type: object + properties: + supported: + type: boolean + example: false + authenticationSchemes: + type: object + properties: + name: + type: string + example: OAuth 2.0 Bearer Token + description: + type: string + example: The OAuth 2.0 Bearer Token Authentication scheme. OAuth enables clients to access protected resources by obtaining an access token, which is defined in RFC 6750 as "a string representing an access authorization issued to the client", rather than using the resource owner's credentials directly. + specUri: + type: string + example: "http://tools.ietf.org/html/rfc6750" + type: + type: string + example: oauthbearertoken + + scim_resource_type: + type: object + properties: + schemas: + type: array + items: + type: string + example: "urn:ietf:params:scim:schemas:core:2.0:ResourceType" + id: + type: string + example: User + name: + type: string + example: User + description: + type: string + example: User + endpoint: + type: string + example: "/Users" + schema: + type: string + example: "urn:ietf:params:scim:schemas:core:2.0:User" + + scim_schema_attribute: + type: object + properties: + name: + type: string + example: userName + type: + enum: + - string + - boolean + - complex + type: string + example: string + multiValued: + type: boolean + example: false + description: + type: string + example: Unique identifier for the User, typically used by the user to directly authenticate to the service provider. Each User MUST include a non-empty userName value. This identifier MUST be unique across the service provider's entire set of Users. + required: + type: boolean + example: true + caseExact: + type: boolean + example: false + mutability: + type: string + example: readWrite + returned: + type: string + example: default + uniqueness: + type: string + example: server + + + scim_schema_parent_attribute: + allOf: + - $ref: "#/components/schemas/scim_schema_attribute" + - type: object + properties: + subAttributes: + type: array + items: + $ref: "#/components/schemas/scim_schema_attribute" + + scim_schema: + type: object + properties: + schemas: + type: array + items: + type: string + example: [ urn:ietf:params:scim:schemas:core:2.0:Schema ] + id: + type: string + example: urn:ietf:params:scim:schemas:core:2.0:User + name: + type: string + example: User + description: + type: string + example: User Account + attributes: + type: array + example: [ ] + items: + $ref: "#/components/schemas/scim_schema_parent_attribute" + + scim_email: + type: object + properties: + value: + type: string + example: jon.snow@docker.com + display: + type: string + example: jon.snow@docker.com + primary: + type: boolean + example: true + + scim_group: + type: object + properties: + value: + type: string + example: "nightswatch" + display: + type: string + example: "nightswatch" + + scim_user_username: + type: string + description: The user's email address. This must be reachable via email. + example: jon.snow@docker.com + + scim_user_name: + type: object + properties: + givenName: + type: string + example: Jon + familyName: + type: string + example: Snow + + scim_user_display_name: + type: string + description: The username in Docker. Also known as the "Docker ID". + example: jonsnow + + scim_user_schemas: + type: array + items: + type: string + example: "urn:ietf:params:scim:schemas:core:2.0:User" + minItems: 1 + + scim_user_id: + type: string + example: d80f7c79-7730-49d8-9a41-7c42fb622d9c + description: The unique identifier for the user. A v4 UUID. + + scim_user: + type: object + properties: + schemas: + $ref: "#/components/schemas/scim_user_schemas" + id: + $ref: "#/components/schemas/scim_user_id" + userName: + $ref: "#/components/schemas/scim_user_username" + name: + $ref: "#/components/schemas/scim_user_name" + displayName: + $ref: "#/components/schemas/scim_user_display_name" + active: + type: boolean + example: true + emails: + type: array + items: + $ref: "#/components/schemas/scim_email" + groups: + type: array + items: + $ref: "#/components/schemas/scim_group" + meta: + type: object + properties: + resourceType: + type: string + example: User + location: + type: string + example: https://hub.docker.com/v2/scim/2.0/Users/d80f7c79-7730-49d8-9a41-7c42fb622d9c + created: + type: string + description: The creation date for the user as a RFC3339 formatted + string. + example: 2022-05-20T00:54:18Z + lastModified: + type: string + description: The date the user was last modified as a RFC3339 + formatted string. + example: 2022-05-20T00:54:18Z + + parameters: + scim_attributes: + in: query + name: attributes + schema: + type: string + description: Comma delimited list of attributes to limit to in the + response. + example: userName,displayName + scim_user_id: + name: id + in: path + schema: + type: string + description: The user ID. + example: "d80f7c79-7730-49d8-9a41-7c42fb622d9c" + + requestBodies: + scim_create_user_request: + required: true + content: + application/scim+json: + schema: + type: object + required: + - schemas + - userName + properties: + schemas: + $ref: "#/components/schemas/scim_user_schemas" + userName: + $ref: "#/components/schemas/scim_user_username" + name: + $ref: "#/components/schemas/scim_user_name" + + scim_update_user_request: + required: true + content: + application/scim+json: + schema: + type: object + required: + - schemas + properties: + schemas: + $ref: "#/components/schemas/scim_user_schemas" + name: + allOf: + - $ref: "#/components/schemas/scim_user_name" + - description: If this is omitted from the request, the + update will skip the update on it. We will only ever + change the name, but not clear it. + enabled: + type: boolean + default: false + description: If this is omitted from the request, it will + default to false resulting in a deactivated user. diff --git a/sitemap.xsl b/sitemap.xsl new file mode 100644 index 000000000000..95ce53b1c949 --- /dev/null +++ b/sitemap.xsl @@ -0,0 +1,81 @@ + + + + + + + Docker Docs XML Sitemap + + + + +

Docker Docs XML Sitemap

+
+

This is an XML Sitemap which is supposed to be processed by search engines like Google, Bing, ...

+

You can find more information about XML sitemaps on sitemaps.org and Google's list of sitemap programs.

+

This sitemap contains URLs.

+
+
+ + + + + + + + + high + + + + + +
LocationLast Modification
+ + + + + + + + +
+
+ + + + diff --git a/support/index.md b/support/index.md index b2bd8e80550c..e07ec533439c 100644 --- a/support/index.md +++ b/support/index.md @@ -48,6 +48,7 @@ If you have a paid Docker subscription, you can get support for the following ty For Windows users, you can also request support on: * Enabling virtualization in BIOS * Enabling Windows features + * Running inside [certain VM or VDI environments](../desktop/vm-vdi.md) (Docker Business customers only) ## What is not supported?